diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-05 18:37:14 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-05 18:37:14 +0000 |
| commit | ea648e70a989cca190cd7403fe892fd2dcc290b4 (patch) | |
| tree | e2b6b1c647da68b0d4d66082835e256eb30970e8 /doc/arm | |
| parent | Initial commit. (diff) | |
| download | bind9-upstream.tar.xz bind9-upstream.zip | |
Adding upstream version 1:9.11.5.P4+dfsg.upstream/1%9.11.5.P4+dfsgupstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
93 files changed, 58439 insertions, 0 deletions
diff --git a/doc/arm/Bv9ARM-book.xml b/doc/arm/Bv9ARM-book.xml new file mode 100644 index 0000000..719b074 --- /dev/null +++ b/doc/arm/Bv9ARM-book.xml @@ -0,0 +1,18117 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Converted by db4-upgrade version 1.0 --> +<book xmlns:db="http://docbook.org/ns/docbook" version="5.0"> + <info> + <title>BIND 9 Administrator Reference Manual</title> + <!-- insert copyright start --> + <copyright> + <year>2000</year> + <year>2001</year> + <year>2002</year> + <year>2003</year> + <year>2004</year> + <year>2005</year> + <year>2006</year> + <year>2007</year> + <year>2008</year> + <year>2009</year> + <year>2010</year> + <year>2011</year> + <year>2012</year> + <year>2013</year> + <year>2014</year> + <year>2015</year> + <year>2016</year> + <year>2017</year> + <year>2018</year> + <year>2019</year> + <holder>Internet Systems Consortium, Inc. ("ISC")</holder> + </copyright> + <!-- insert copyright end --> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="releaseinfo.xml"/> + </info> + + <chapter xml:id="Bv9ARM.ch01"><info><title>Introduction</title></info> + + <para> + The Internet Domain Name System (<acronym>DNS</acronym>) + consists of the syntax + to specify the names of entities in the Internet in a hierarchical + manner, the rules used for delegating authority over names, and the + system implementation that actually maps names to Internet + addresses. <acronym>DNS</acronym> data is maintained in a + group of distributed + hierarchical databases. + </para> + + <section xml:id="doc_scope"><info><title>Scope of Document</title></info> + + <para> + The Berkeley Internet Name Domain + (<acronym>BIND</acronym>) implements a + domain name server for a number of operating systems. This + document provides basic information about the installation and + care of the Internet Systems Consortium (<acronym>ISC</acronym>) + <acronym>BIND</acronym> version 9 software package for + system administrators. + </para> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pkgversion.xml"/> + </section> + + <section xml:id="organization"><info><title>Organization of This Document</title></info> + + <para> + In this document, <emphasis>Chapter 1</emphasis> introduces + the basic <acronym>DNS</acronym> and <acronym>BIND</acronym> concepts. <emphasis>Chapter 2</emphasis> + describes resource requirements for running <acronym>BIND</acronym> in various + environments. Information in <emphasis>Chapter 3</emphasis> is + <emphasis>task-oriented</emphasis> in its presentation and is + organized functionally, to aid in the process of installing the + <acronym>BIND</acronym> 9 software. The task-oriented + section is followed by + <emphasis>Chapter 4</emphasis>, which contains more advanced + concepts that the system administrator may need for implementing + certain options. <emphasis>Chapter 5</emphasis> + describes the <acronym>BIND</acronym> 9 lightweight + resolver. The contents of <emphasis>Chapter 6</emphasis> are + organized as in a reference manual to aid in the ongoing + maintenance of the software. <emphasis>Chapter 7</emphasis> addresses + security considerations, and + <emphasis>Chapter 8</emphasis> contains troubleshooting help. The + main body of the document is followed by several + <emphasis>appendices</emphasis> which contain useful reference + information, such as a <emphasis>bibliography</emphasis> and + historic information related to <acronym>BIND</acronym> + and the Domain Name + System. + </para> + </section> + <section xml:id="conventions"><info><title>Conventions Used in This Document</title></info> + + <para> + In this document, we use the following general typographic + conventions: + </para> + + <informaltable> + <tgroup cols="2"> + <colspec colname="1" colnum="1" colwidth="3.000in"/> + <colspec colname="2" colnum="2" colwidth="2.625in"/> + <tbody> + <row> + <entry colname="1"> + <para> + <emphasis>To describe:</emphasis> + </para> + </entry> + <entry colname="2"> + <para> + <emphasis>We use the style:</emphasis> + </para> + </entry> + </row> + <row> + <entry colname="1"> + <para> + a pathname, filename, URL, hostname, + mailing list name, or new term or concept + </para> + </entry> + <entry colname="2"> + <para> + <filename>Fixed width</filename> + </para> + </entry> + </row> + <row> + <entry colname="1"> + <para> + literal user + input + </para> + </entry> + <entry colname="2"> + <para> + <userinput>Fixed Width Bold</userinput> + </para> + </entry> + </row> + <row> + <entry colname="1"> + <para> + program output + </para> + </entry> + <entry colname="2"> + <para> + <computeroutput>Fixed Width</computeroutput> + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para> + The following conventions are used in descriptions of the + <acronym>BIND</acronym> configuration file:<informaltable colsep="0" frame="all" rowsep="0"> + <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="2Level-table"> + <colspec colname="1" colnum="1" colsep="0" colwidth="3.000in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="2.625in"/> + <tbody> + <row rowsep="0"> + <entry colname="1" colsep="1" rowsep="1"> + <para> + <emphasis>To describe:</emphasis> + </para> + </entry> + <entry colname="2" rowsep="1"> + <para> + <emphasis>We use the style:</emphasis> + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1" colsep="1" rowsep="1"> + <para> + keywords + </para> + </entry> + <entry colname="2" rowsep="1"> + <para> + <literal>Fixed Width</literal> + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1" colsep="1" rowsep="1"> + <para> + variables + </para> + </entry> + <entry colname="2" rowsep="1"> + <para> + <varname>Fixed Width</varname> + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1" colsep="1"> + <para> + Optional input + </para> + </entry> + <entry colname="2"> + <para> + <optional>Text is enclosed in square brackets</optional> + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </section> + <section xml:id="dns_overview"><info><title>The Domain Name System (<acronym>DNS</acronym>)</title></info> + + <para> + The purpose of this document is to explain the installation + and upkeep of the <acronym>BIND</acronym> (Berkeley Internet + Name Domain) software package, and we + begin by reviewing the fundamentals of the Domain Name System + (<acronym>DNS</acronym>) as they relate to <acronym>BIND</acronym>. + </para> + + <section xml:id="dns_fundamentals"><info><title>DNS Fundamentals</title></info> + + <para> + The Domain Name System (DNS) is a hierarchical, distributed + database. It stores information for mapping Internet host names to + IP + addresses and vice versa, mail routing information, and other data + used by Internet applications. + </para> + + <para> + Clients look up information in the DNS by calling a + <emphasis>resolver</emphasis> library, which sends queries to one or + more <emphasis>name servers</emphasis> and interprets the responses. + The <acronym>BIND</acronym> 9 software distribution + contains a name server, <command>named</command>, and a + resolver library, <command>liblwres</command>. + </para> + + </section> + <section xml:id="domain_names"><info><title>Domains and Domain Names</title></info> + + <para> + The data stored in the DNS is identified by <emphasis>domain names</emphasis> that are organized as a tree according to + organizational or administrative boundaries. Each node of the tree, + called a <emphasis>domain</emphasis>, is given a label. The domain + name of the + node is the concatenation of all the labels on the path from the + node to the <emphasis>root</emphasis> node. This is represented + in written form as a string of labels listed from right to left and + separated by dots. A label need only be unique within its parent + domain. + </para> + + <para> + For example, a domain name for a host at the + company <emphasis>Example, Inc.</emphasis> could be + <literal>ourhost.example.com</literal>, + where <literal>com</literal> is the + top level domain to which + <literal>ourhost.example.com</literal> belongs, + <literal>example</literal> is + a subdomain of <literal>com</literal>, and + <literal>ourhost</literal> is the + name of the host. + </para> + + <para> + For administrative purposes, the name space is partitioned into + areas called <emphasis>zones</emphasis>, each starting at a node and + extending down to the leaf nodes or to nodes where other zones + start. + The data for each zone is stored in a <emphasis>name server</emphasis>, which answers queries about the zone using the + <emphasis>DNS protocol</emphasis>. + </para> + + <para> + The data associated with each domain name is stored in the + form of <emphasis>resource records</emphasis> (<acronym>RR</acronym>s). + Some of the supported resource record types are described in + <xref linkend="types_of_resource_records_and_when_to_use_them"/>. + </para> + + <para> + For more detailed information about the design of the DNS and + the DNS protocol, please refer to the standards documents listed in + <xref linkend="rfcs"/>. + </para> + </section> + + <section xml:id="zones"><info><title>Zones</title></info> + + <para> + To properly operate a name server, it is important to understand + the difference between a <emphasis>zone</emphasis> + and a <emphasis>domain</emphasis>. + </para> + + <para> + As stated previously, a zone is a point of delegation in + the <acronym>DNS</acronym> tree. A zone consists of + those contiguous parts of the domain + tree for which a name server has complete information and over which + it has authority. It contains all domain names from a certain point + downward in the domain tree except those which are delegated to + other zones. A delegation point is marked by one or more + <emphasis>NS records</emphasis> in the + parent zone, which should be matched by equivalent NS records at + the root of the delegated zone. + </para> + + <para> + For instance, consider the <literal>example.com</literal> + domain which includes names + such as <literal>host.aaa.example.com</literal> and + <literal>host.bbb.example.com</literal> even though + the <literal>example.com</literal> zone includes + only delegations for the <literal>aaa.example.com</literal> and + <literal>bbb.example.com</literal> zones. A zone can + map + exactly to a single domain, but could also include only part of a + domain, the rest of which could be delegated to other + name servers. Every name in the <acronym>DNS</acronym> + tree is a + <emphasis>domain</emphasis>, even if it is + <emphasis>terminal</emphasis>, that is, has no + <emphasis>subdomains</emphasis>. Every subdomain is a domain and + every domain except the root is also a subdomain. The terminology is + not intuitive and we suggest that you read RFCs 1033, 1034 and 1035 + to + gain a complete understanding of this difficult and subtle + topic. + </para> + + <para> + Though <acronym>BIND</acronym> is called a "domain name + server", + it deals primarily in terms of zones. The master and slave + declarations in the <filename>named.conf</filename> file + specify + zones, not domains. When you ask some other site if it is willing to + be a slave server for your <emphasis>domain</emphasis>, you are + actually asking for slave service for some collection of zones. + </para> + </section> + + <section xml:id="auth_servers"><info><title>Authoritative Name Servers</title></info> + + <para> + Each zone is served by at least + one <emphasis>authoritative name server</emphasis>, + which contains the complete data for the zone. + To make the DNS tolerant of server and network failures, + most zones have two or more authoritative servers, on + different networks. + </para> + + <para> + Responses from authoritative servers have the "authoritative + answer" (AA) bit set in the response packets. This makes them + easy to identify when debugging DNS configurations using tools like + <command>dig</command> (<xref linkend="diagnostic_tools"/>). + </para> + + <section xml:id="primary_master"><info><title>The Primary Master</title></info> + + <para> + The authoritative server where the master copy of the zone + data is maintained is called the + <emphasis>primary master</emphasis> server, or simply the + <emphasis>primary</emphasis>. Typically it loads the zone + contents from some local file edited by humans or perhaps + generated mechanically from some other local file which is + edited by humans. This file is called the + <emphasis>zone file</emphasis> or + <emphasis>master file</emphasis>. + </para> + + <para> + In some cases, however, the master file may not be edited + by humans at all, but may instead be the result of + <emphasis>dynamic update</emphasis> operations. + </para> + </section> + + <section xml:id="slave_server"><info><title>Slave Servers</title></info> + + <para> + The other authoritative servers, the <emphasis>slave</emphasis> + servers (also known as <emphasis>secondary</emphasis> servers) + load the zone contents from another server using a replication + process known as a <emphasis>zone transfer</emphasis>. + Typically the data are transferred directly from the primary + master, but it is also possible to transfer it from another + slave. In other words, a slave server may itself act as a + master to a subordinate slave server. + </para> + <para> + Periodically, the slave server must send a refresh query to + determine whether the zone contents have been updated. This + is done by sending a query for the zone's SOA record and + checking whether the SERIAL field has been updated; if so, + a new transfer request is initiated. The timing of these + refresh queries is controlled by the SOA REFRESH and RETRY + fields, but can be overrridden with the + <command>max-refresh-time</command>, + <command>min-refresh-time</command>, + <command>max-retry-time</command>, and + <command>min-retry-time</command> options. + </para> + <para> + If the zone data cannot be updated within the time specified + by the SOA EXPIRE option (up to a hard-coded maximum of + 24 weeks) then the slave zone expires and will no longer + respond to queries. + </para> + </section> + + <section xml:id="stealth_server"><info><title>Stealth Servers</title></info> + + <para> + Usually all of the zone's authoritative servers are listed in + NS records in the parent zone. These NS records constitute + a <emphasis>delegation</emphasis> of the zone from the parent. + The authoritative servers are also listed in the zone file itself, + at the <emphasis>top level</emphasis> or <emphasis>apex</emphasis> + of the zone. You can list servers in the zone's top-level NS + records that are not in the parent's NS delegation, but you cannot + list servers in the parent's delegation that are not present at + the zone's top level. + </para> + + <para> + A <emphasis>stealth server</emphasis> is a server that is + authoritative for a zone but is not listed in that zone's NS + records. Stealth servers can be used for keeping a local copy of + a + zone to speed up access to the zone's records or to make sure that + the + zone is available even if all the "official" servers for the zone + are + inaccessible. + </para> + + <para> + A configuration where the primary master server itself is a + stealth server is often referred to as a "hidden primary" + configuration. One use for this configuration is when the primary + master + is behind a firewall and therefore unable to communicate directly + with the outside world. + </para> + + </section> + + </section> + <section xml:id="cache_servers"><info><title>Caching Name Servers</title></info> + + <!-- + - Terminology here is inconsistent. Probably ought to + - convert to using "recursive name server" everywhere + - with just a note about "caching" terminology. + --> + + <para> + The resolver libraries provided by most operating systems are + <emphasis>stub resolvers</emphasis>, meaning that they are not + capable of + performing the full DNS resolution process by themselves by talking + directly to the authoritative servers. Instead, they rely on a + local + name server to perform the resolution on their behalf. Such a + server + is called a <emphasis>recursive</emphasis> name server; it performs + <emphasis>recursive lookups</emphasis> for local clients. + </para> + + <para> + To improve performance, recursive servers cache the results of + the lookups they perform. Since the processes of recursion and + caching are intimately connected, the terms + <emphasis>recursive server</emphasis> and + <emphasis>caching server</emphasis> are often used synonymously. + </para> + + <para> + The length of time for which a record may be retained in + the cache of a caching name server is controlled by the + Time To Live (TTL) field associated with each resource record. + </para> + + <section xml:id="forwarder"><info><title>Forwarding</title></info> + + <para> + Even a caching name server does not necessarily perform + the complete recursive lookup itself. Instead, it can + <emphasis>forward</emphasis> some or all of the queries + that it cannot satisfy from its cache to another caching name + server, + commonly referred to as a <emphasis>forwarder</emphasis>. + </para> + + <para> + There may be one or more forwarders, + and they are queried in turn until the list is exhausted or an + answer + is found. Forwarders are typically used when you do not + wish all the servers at a given site to interact directly with the + rest of + the Internet servers. A typical scenario would involve a number + of internal <acronym>DNS</acronym> servers and an + Internet firewall. Servers unable + to pass packets through the firewall would forward to the server + that can do it, and that server would query the Internet <acronym>DNS</acronym> servers + on the internal server's behalf. + </para> + </section> + + </section> + + <section xml:id="multi_role"><info><title>Name Servers in Multiple Roles</title></info> + + <para> + The <acronym>BIND</acronym> name server can + simultaneously act as + a master for some zones, a slave for other zones, and as a caching + (recursive) server for a set of local clients. + </para> + + <para> + However, since the functions of authoritative name service + and caching/recursive name service are logically separate, it is + often advantageous to run them on separate server machines. + + A server that only provides authoritative name service + (an <emphasis>authoritative-only</emphasis> server) can run with + recursion disabled, improving reliability and security. + + A server that is not authoritative for any zones and only provides + recursive service to local + clients (a <emphasis>caching-only</emphasis> server) + does not need to be reachable from the Internet at large and can + be placed inside a firewall. + </para> + + </section> + </section> + + </chapter> + + <chapter xml:id="Bv9ARM.ch02"><info><title><acronym>BIND</acronym> Resource Requirements</title></info> + + <section xml:id="hw_req"><info><title>Hardware requirements</title></info> + <para> + <acronym>DNS</acronym> hardware requirements have + traditionally been quite modest. + For many installations, servers that have been pensioned off from + active duty have performed admirably as <acronym>DNS</acronym> servers. + </para> + <para> + The DNSSEC features of <acronym>BIND</acronym> 9 + may prove to be quite + CPU intensive however, so organizations that make heavy use of these + features may wish to consider larger systems for these applications. + <acronym>BIND</acronym> 9 is fully multithreaded, allowing + full utilization of + multiprocessor systems for installations that need it. + </para> + </section> + <section xml:id="cpu_req"><info><title>CPU Requirements</title></info> + <para> + CPU requirements for <acronym>BIND</acronym> 9 range from + i486-class machines + for serving of static zones without caching, to enterprise-class + machines if you intend to process many dynamic updates and DNSSEC + signed zones, serving many thousands of queries per second. + </para> + </section> + <section xml:id="mem_req"><info><title>Memory Requirements</title></info> + <para> + The memory of the server has to be large enough to fit the + cache and zones loaded off disk. The <command>max-cache-size</command> + option can be used to limit the amount of memory used by the cache, + at the expense of reducing cache hit rates and causing more <acronym>DNS</acronym> + traffic. + Additionally, if additional section caching + (<xref linkend="acache"/>) is enabled, + the <command>max-acache-size</command> option can be used to + limit the amount + of memory used by the mechanism. + It is still good practice to have enough memory to load + all zone and cache data into memory — unfortunately, the best + way + to determine this for a given installation is to watch the name server + in operation. After a few weeks the server process should reach + a relatively stable size where entries are expiring from the cache as + fast as they are being inserted. + </para> + <!-- + - Add something here about leaving overhead for attacks? + - How much overhead? Percentage? + --> + </section> + + <section xml:id="intensive_env"><info><title>Name Server Intensive Environment Issues</title></info> + + <para> + For name server intensive environments, there are two alternative + configurations that may be used. The first is where clients and + any second-level internal name servers query a main name server, which + has enough memory to build a large cache. This approach minimizes + the bandwidth used by external name lookups. The second alternative + is to set up second-level internal name servers to make queries + independently. + In this configuration, none of the individual machines needs to + have as much memory or CPU power as in the first alternative, but + this has the disadvantage of making many more external queries, + as none of the name servers share their cached data. + </para> + </section> + + <section xml:id="supported_os"><info><title>Supported Operating Systems</title></info> + + <para> + ISC <acronym>BIND</acronym> 9 compiles and runs on a large + number + of Unix-like operating systems and on + Microsoft Windows Server 2003 and 2008, and Windows XP and Vista. + For an up-to-date + list of supported systems, see the README file in the top level + directory + of the BIND 9 source distribution. + </para> + </section> + </chapter> + + <chapter xml:id="Bv9ARM.ch03"><info><title>Name Server Configuration</title></info> + + <para> + In this chapter we provide some suggested configurations along + with guidelines for their use. We suggest reasonable values for + certain option settings. + </para> + + <section xml:id="sample_configuration"><info><title>Sample Configurations</title></info> + + <section xml:id="cache_only_sample"><info><title>A Caching-only Name Server</title></info> + + <para> + The following sample configuration is appropriate for a caching-only + name server for use by clients internal to a corporation. All + queries + from outside clients are refused using the <command>allow-query</command> + option. Alternatively, the same effect could be achieved using + suitable + firewall rules. + </para> + +<programlisting> +// Two corporate subnets we wish to allow queries from. +acl corpnets { 192.168.4.0/24; 192.168.7.0/24; }; +options { + // Working directory + directory "/etc/namedb"; + + allow-query { corpnets; }; +}; +// Provide a reverse mapping for the loopback +// address 127.0.0.1 +zone "0.0.127.in-addr.arpa" { + type master; + file "localhost.rev"; + notify no; +}; +</programlisting> + + </section> + + <section xml:id="auth_only_sample"><info><title>An Authoritative-only Name Server</title></info> + + <para> + This sample configuration is for an authoritative-only server + that is the master server for "<filename>example.com</filename>" + and a slave for the subdomain "<filename>eng.example.com</filename>". + </para> + +<programlisting> +options { + // Working directory + directory "/etc/namedb"; + // Do not allow access to cache + allow-query-cache { none; }; + // This is the default + allow-query { any; }; + // Do not provide recursive service + recursion no; +}; + +// Provide a reverse mapping for the loopback +// address 127.0.0.1 +zone "0.0.127.in-addr.arpa" { + type master; + file "localhost.rev"; + notify no; +}; +// We are the master server for example.com +zone "example.com" { + type master; + file "example.com.db"; + // IP addresses of slave servers allowed to + // transfer example.com + allow-transfer { + 192.168.4.14; + 192.168.5.53; + }; +}; +// We are a slave server for eng.example.com +zone "eng.example.com" { + type slave; + file "eng.example.com.bk"; + // IP address of eng.example.com master server + masters { 192.168.4.12; }; +}; +</programlisting> + + </section> + </section> + + <section xml:id="load_balancing"><info><title>Load Balancing</title></info> + + <!-- + - Add explanation of why load balancing is fragile at best + - and completely pointless in the general case. + --> + + <para> + A primitive form of load balancing can be achieved in + the <acronym>DNS</acronym> by using multiple records + (such as multiple A records) for one name. + </para> + + <para> + For example, if you have three WWW servers with network addresses + of 10.0.0.1, 10.0.0.2 and 10.0.0.3, a set of records such as the + following means that clients will connect to each machine one third + of the time: + </para> + + <informaltable colsep="0" rowsep="0"> + <tgroup cols="5" colsep="0" rowsep="0" tgroupstyle="2Level-table"> + <colspec colname="1" colnum="1" colsep="0" colwidth="0.875in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="0.500in"/> + <colspec colname="3" colnum="3" colsep="0" colwidth="0.750in"/> + <colspec colname="4" colnum="4" colsep="0" colwidth="0.750in"/> + <colspec colname="5" colnum="5" colsep="0" colwidth="2.028in"/> + <tbody> + <row rowsep="0"> + <entry colname="1"> + <para> + Name + </para> + </entry> + <entry colname="2"> + <para> + TTL + </para> + </entry> + <entry colname="3"> + <para> + CLASS + </para> + </entry> + <entry colname="4"> + <para> + TYPE + </para> + </entry> + <entry colname="5"> + <para> + Resource Record (RR) Data + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <literal>www</literal> + </para> + </entry> + <entry colname="2"> + <para> + <literal>600</literal> + </para> + </entry> + <entry colname="3"> + <para> + <literal>IN</literal> + </para> + </entry> + <entry colname="4"> + <para> + <literal>A</literal> + </para> + </entry> + <entry colname="5"> + <para> + <literal>10.0.0.1</literal> + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para/> + </entry> + <entry colname="2"> + <para> + <literal>600</literal> + </para> + </entry> + <entry colname="3"> + <para> + <literal>IN</literal> + </para> + </entry> + <entry colname="4"> + <para> + <literal>A</literal> + </para> + </entry> + <entry colname="5"> + <para> + <literal>10.0.0.2</literal> + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para/> + </entry> + <entry colname="2"> + <para> + <literal>600</literal> + </para> + </entry> + <entry colname="3"> + <para> + <literal>IN</literal> + </para> + </entry> + <entry colname="4"> + <para> + <literal>A</literal> + </para> + </entry> + <entry colname="5"> + <para> + <literal>10.0.0.3</literal> + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <para> + When a resolver queries for these records, <acronym>BIND</acronym> will rotate + them and respond to the query with the records in a different + order. In the example above, clients will randomly receive + records in the order 1, 2, 3; 2, 3, 1; and 3, 1, 2. Most clients + will use the first record returned and discard the rest. + </para> + <para> + For more detail on ordering responses, check the + <command>rrset-order</command> sub-statement in the + <command>options</command> statement, see + <xref endterm="rrset_ordering_title" linkend="rrset_ordering"/>. + </para> + + </section> + + <section xml:id="ns_operations"><info><title>Name Server Operations</title></info> + + <section xml:id="tools"><info><title>Tools for Use With the Name Server Daemon</title></info> + <para> + This section describes several indispensable diagnostic, + administrative and monitoring tools available to the system + administrator for controlling and debugging the name server + daemon. + </para> + <section xml:id="diagnostic_tools"><info><title>Diagnostic Tools</title></info> + <para> + The <command>dig</command>, <command>host</command>, and + <command>nslookup</command> programs are all command + line tools + for manually querying name servers. They differ in style and + output format. + </para> + + <variablelist> + <varlistentry> + <term xml:id="dig"><command>dig</command></term> + <listitem> + <para> + <command>dig</command> + is the most versatile and complete of these lookup tools. + It has two modes: simple interactive + mode for a single query, and batch mode which executes a + query for + each in a list of several query lines. All query options are + accessible + from the command line. + </para> + <cmdsynopsis label="Usage" sepchar=" "> + <command>dig</command> + <arg choice="opt" rep="norepeat">@<replaceable>server</replaceable></arg> + <arg choice="plain" rep="norepeat"><replaceable>domain</replaceable></arg> + <arg choice="opt" rep="norepeat"><replaceable>query-type</replaceable></arg> + <arg choice="opt" rep="norepeat"><replaceable>query-class</replaceable></arg> + <arg choice="opt" rep="norepeat">+<replaceable>query-option</replaceable></arg> + <arg choice="opt" rep="norepeat">-<replaceable>dig-option</replaceable></arg> + <arg choice="opt" rep="norepeat">%<replaceable>comment</replaceable></arg> + </cmdsynopsis> + <para> + The usual simple use of <command>dig</command> will take the form + </para> + <simpara> + <command>dig @server domain query-type query-class</command> + </simpara> + <para> + For more information and a list of available commands and + options, see the <command>dig</command> man + page. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>host</command></term> + <listitem> + <para> + The <command>host</command> utility emphasizes + simplicity + and ease of use. By default, it converts + between host names and Internet addresses, but its + functionality + can be extended with the use of options. + </para> + <cmdsynopsis label="Usage" sepchar=" "> + <command>host</command> + <arg choice="opt" rep="norepeat">-aCdlnrsTwv</arg> + <arg choice="opt" rep="norepeat">-c <replaceable>class</replaceable></arg> + <arg choice="opt" rep="norepeat">-N <replaceable>ndots</replaceable></arg> + <arg choice="opt" rep="norepeat">-t <replaceable>type</replaceable></arg> + <arg choice="opt" rep="norepeat">-W <replaceable>timeout</replaceable></arg> + <arg choice="opt" rep="norepeat">-R <replaceable>retries</replaceable></arg> + <arg choice="opt" rep="norepeat">-m <replaceable>flag</replaceable></arg> + <arg choice="opt" rep="norepeat">-4</arg> + <arg choice="opt" rep="norepeat">-6</arg> + <arg choice="plain" rep="norepeat"><replaceable>hostname</replaceable></arg> + <arg choice="opt" rep="norepeat"><replaceable>server</replaceable></arg> + </cmdsynopsis> + <para> + For more information and a list of available commands and + options, see the <command>host</command> man + page. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>nslookup</command></term> + <listitem> + <para><command>nslookup</command> + has two modes: interactive and + non-interactive. Interactive mode allows the user to + query name servers for information about various + hosts and domains or to print a list of hosts in a + domain. Non-interactive mode is used to print just + the name and requested information for a host or + domain. + </para> + <cmdsynopsis label="Usage" sepchar=" "> + <command>nslookup</command> + <arg rep="repeat" choice="opt">-option</arg> + <group choice="opt" rep="norepeat"> + <arg choice="opt" rep="norepeat"><replaceable>host-to-find</replaceable></arg> + <arg choice="opt" rep="norepeat">- <arg choice="opt" rep="norepeat">server</arg></arg> + </group> + </cmdsynopsis> + <para> + Interactive mode is entered when no arguments are given (the + default name server will be used) or when the first argument + is a + hyphen (`-') and the second argument is the host name or + Internet address + of a name server. + </para> + <para> + Non-interactive mode is used when the name or Internet + address + of the host to be looked up is given as the first argument. + The + optional second argument specifies the host name or address + of a name server. + </para> + <para> + Due to its arcane user interface and frequently inconsistent + behavior, we do not recommend the use of <command>nslookup</command>. + Use <command>dig</command> instead. + </para> + </listitem> + + </varlistentry> + </variablelist> + </section> + + <section xml:id="admin_tools"><info><title>Administrative Tools</title></info> + <para> + Administrative tools play an integral part in the management + of a server. + </para> + <variablelist> + <varlistentry xml:id="named-checkconf" xreflabel="Named Configuration Checking application"> + + <term><command>named-checkconf</command></term> + <listitem> + <para> + The <command>named-checkconf</command> program + checks the syntax of a <filename>named.conf</filename> file. + </para> + <cmdsynopsis label="Usage" sepchar=" "> + <command>named-checkconf</command> + <arg choice="opt" rep="norepeat">-jvz</arg> + <arg choice="opt" rep="norepeat">-t <replaceable>directory</replaceable></arg> + <arg choice="opt" rep="norepeat"><replaceable>filename</replaceable></arg> + </cmdsynopsis> + </listitem> + </varlistentry> + <varlistentry xml:id="named-checkzone" xreflabel="Zone Checking application"> + + <term><command>named-checkzone</command></term> + <listitem> + <para> + The <command>named-checkzone</command> program + checks a master file for + syntax and consistency. + </para> + <cmdsynopsis label="Usage" sepchar=" "> + <command>named-checkzone</command> + <arg choice="opt" rep="norepeat">-djqvD</arg> + <arg choice="opt" rep="norepeat">-c <replaceable>class</replaceable></arg> + <arg choice="opt" rep="norepeat">-o <replaceable>output</replaceable></arg> + <arg choice="opt" rep="norepeat">-t <replaceable>directory</replaceable></arg> + <arg choice="opt" rep="norepeat">-w <replaceable>directory</replaceable></arg> + <arg choice="opt" rep="norepeat">-k <replaceable>(ignore|warn|fail)</replaceable></arg> + <arg choice="opt" rep="norepeat">-n <replaceable>(ignore|warn|fail)</replaceable></arg> + <arg choice="opt" rep="norepeat">-W <replaceable>(ignore|warn)</replaceable></arg> + <arg choice="plain" rep="norepeat"><replaceable>zone</replaceable></arg> + <arg choice="opt" rep="norepeat"><replaceable>filename</replaceable></arg> + </cmdsynopsis> + </listitem> + </varlistentry> + <varlistentry xml:id="named-compilezone" xreflabel="Zone Compilation application"> + <term><command>named-compilezone</command></term> + <listitem> + <para> + Similar to <command>named-checkzone,</command> but + it always dumps the zone content to a specified file + (typically in a different format). + </para> + </listitem> + </varlistentry> + <varlistentry xml:id="rndc" xreflabel="Remote Name Daemon Control application"> + + <term><command>rndc</command></term> + <listitem> + <para> + The remote name daemon control + (<command>rndc</command>) program allows the + system + administrator to control the operation of a name server. + Since <acronym>BIND</acronym> 9.2, <command>rndc</command> + supports all the commands of the BIND 8 <command>ndc</command> + utility except <command>ndc start</command> and + <command>ndc restart</command>, which were also + not supported in <command>ndc</command>'s + channel mode. + If you run <command>rndc</command> without any + options + it will display a usage message as follows: + </para> + <cmdsynopsis label="Usage" sepchar=" "> + <command>rndc</command> + <arg choice="opt" rep="norepeat">-c <replaceable>config</replaceable></arg> + <arg choice="opt" rep="norepeat">-s <replaceable>server</replaceable></arg> + <arg choice="opt" rep="norepeat">-p <replaceable>port</replaceable></arg> + <arg choice="opt" rep="norepeat">-y <replaceable>key</replaceable></arg> + <arg choice="plain" rep="norepeat"><replaceable>command</replaceable></arg> + <arg rep="repeat" choice="opt"><replaceable>command</replaceable></arg> + </cmdsynopsis> + + <para>See <xref linkend="man.rndc"/> for details of + the available <command>rndc</command> commands. + </para> + + <para> + <command>rndc</command> requires a configuration file, + since all + communication with the server is authenticated with + digital signatures that rely on a shared secret, and + there is no way to provide that secret other than with a + configuration file. The default location for the + <command>rndc</command> configuration file is + <filename>/etc/rndc.conf</filename>, but an + alternate + location can be specified with the <option>-c</option> + option. If the configuration file is not found, + <command>rndc</command> will also look in + <filename>/etc/rndc.key</filename> (or whatever + <varname>sysconfdir</varname> was defined when + the <acronym>BIND</acronym> build was + configured). + The <filename>rndc.key</filename> file is + generated by + running <command>rndc-confgen -a</command> as + described in + <xref linkend="controls_statement_definition_and_usage"/>. + </para> + + <para> + The format of the configuration file is similar to + that of <filename>named.conf</filename>, but + limited to + only four statements, the <command>options</command>, + <command>key</command>, <command>server</command> and + <command>include</command> + statements. These statements are what associate the + secret keys to the servers with which they are meant to + be shared. The order of statements is not + significant. + </para> + + <para> + The <command>options</command> statement has + three clauses: + <command>default-server</command>, <command>default-key</command>, + and <command>default-port</command>. + <command>default-server</command> takes a + host name or address argument and represents the server + that will + be contacted if no <option>-s</option> + option is provided on the command line. + <command>default-key</command> takes + the name of a key as its argument, as defined by a <command>key</command> statement. + <command>default-port</command> specifies the + port to which + <command>rndc</command> should connect if no + port is given on the command line or in a + <command>server</command> statement. + </para> + + <para> + The <command>key</command> statement defines a + key to be used + by <command>rndc</command> when authenticating + with + <command>named</command>. Its syntax is + identical to the + <command>key</command> statement in <filename>named.conf</filename>. + The keyword <userinput>key</userinput> is + followed by a key name, which must be a valid + domain name, though it need not actually be hierarchical; + thus, + a string like "<userinput>rndc_key</userinput>" is a valid + name. + The <command>key</command> statement has two + clauses: + <command>algorithm</command> and <command>secret</command>. + While the configuration parser will accept any string as the + argument + to algorithm, currently only the strings + "<userinput>hmac-md5</userinput>", + "<userinput>hmac-sha1</userinput>", + "<userinput>hmac-sha224</userinput>", + "<userinput>hmac-sha256</userinput>", + "<userinput>hmac-sha384</userinput>" + and "<userinput>hmac-sha512</userinput>" + have any meaning. The secret is a Base64 encoded string + as specified in RFC 3548. + </para> + + <para> + The <command>server</command> statement + associates a key + defined using the <command>key</command> + statement with a server. + The keyword <userinput>server</userinput> is followed by a + host name or address. The <command>server</command> statement + has two clauses: <command>key</command> and <command>port</command>. + The <command>key</command> clause specifies the + name of the key + to be used when communicating with this server, and the + <command>port</command> clause can be used to + specify the port <command>rndc</command> should + connect + to on the server. + </para> + + <para> + A sample minimal configuration file is as follows: + </para> + +<programlisting> +key rndc_key { + algorithm "hmac-sha256"; + secret + "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K"; +}; +options { + default-server 127.0.0.1; + default-key rndc_key; +}; +</programlisting> + + <para> + This file, if installed as <filename>/etc/rndc.conf</filename>, + would allow the command: + </para> + + <para> + <prompt>$ </prompt><userinput>rndc reload</userinput> + </para> + + <para> + to connect to 127.0.0.1 port 953 and cause the name server + to reload, if a name server on the local machine were + running with + following controls statements: + </para> + +<programlisting> +controls { + inet 127.0.0.1 + allow { localhost; } keys { rndc_key; }; +}; +</programlisting> + + <para> + and it had an identical key statement for + <literal>rndc_key</literal>. + </para> + + <para> + Running the <command>rndc-confgen</command> + program will + conveniently create a <filename>rndc.conf</filename> + file for you, and also display the + corresponding <command>controls</command> + statement that you need to + add to <filename>named.conf</filename>. + Alternatively, + you can run <command>rndc-confgen -a</command> + to set up + a <filename>rndc.key</filename> file and not + modify + <filename>named.conf</filename> at all. + </para> + + </listitem> + </varlistentry> + </variablelist> + + </section> + </section> + + <section xml:id="signals"><info><title>Signals</title></info> + <para> + Certain UNIX signals cause the name server to take specific + actions, as described in the following table. These signals can + be sent using the <command>kill</command> command. + </para> + <informaltable frame="all"> + <tgroup cols="2"> + <colspec colname="1" colnum="1" colsep="0" colwidth="1.125in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="4.000in"/> + <tbody> + <row rowsep="0"> + <entry colname="1"> + <para><command>SIGHUP</command></para> + </entry> + <entry colname="2"> + <para> + Causes the server to read <filename>named.conf</filename> and + reload the database. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>SIGTERM</command></para> + </entry> + <entry colname="2"> + <para> + Causes the server to clean up and exit. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>SIGINT</command></para> + </entry> + <entry colname="2"> + <para> + Causes the server to clean up and exit. + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </section> + </section> + </chapter> + + <chapter xml:id="Bv9ARM.ch04"><info><title>Advanced DNS Features</title></info> + + <section xml:id="notify"><info><title>Notify</title></info> + <para> + <acronym>DNS</acronym> NOTIFY is a mechanism that allows master + servers to notify their slave servers of changes to a zone's data. In + response to a <command>NOTIFY</command> from a master server, the + slave will check to see that its version of the zone is the + current version and, if not, initiate a zone transfer. + </para> + + <para> + For more information about <acronym>DNS</acronym> + <command>NOTIFY</command>, see the description of the + <command>notify</command> option in <xref linkend="boolean_options"/> and + the description of the zone option <command>also-notify</command> in + <xref linkend="zone_transfers"/>. The <command>NOTIFY</command> + protocol is specified in RFC 1996. + </para> + + <note><simpara> + As a slave zone can also be a master to other slaves, <command>named</command>, + by default, sends <command>NOTIFY</command> messages for every zone + it loads. Specifying <command>notify master-only;</command> will + cause <command>named</command> to only send <command>NOTIFY</command> for master + zones that it loads. + </simpara></note> + + </section> + + <section xml:id="dynamic_update"><info><title>Dynamic Update</title></info> + + <para> + Dynamic Update is a method for adding, replacing or deleting + records in a master server by sending it a special form of DNS + messages. The format and meaning of these messages is specified + in RFC 2136. + </para> + + <para> + Dynamic update is enabled by including an + <command>allow-update</command> or an <command>update-policy</command> + clause in the <command>zone</command> statement. + </para> + + <para> + If the zone's <command>update-policy</command> is set to + <userinput>local</userinput>, updates to the zone + will be permitted for the key <varname>local-ddns</varname>, + which will be generated by <command>named</command> at startup. + See <xref linkend="dynamic_update_policies"/> for more details. + </para> + + <para> + Dynamic updates using Kerberos signed requests can be made + using the TKEY/GSS protocol by setting either the + <command>tkey-gssapi-keytab</command> option, or alternatively + by setting both the <command>tkey-gssapi-credential</command> + and <command>tkey-domain</command> options. Once enabled, + Kerberos signed requests will be matched against the update + policies for the zone, using the Kerberos principal as the + signer for the request. + </para> + + <para> + Updating of secure zones (zones using DNSSEC) follows RFC + 3007: RRSIG, NSEC and NSEC3 records affected by updates are + automatically regenerated by the server using an online + zone key. Update authorization is based on transaction + signatures and an explicit server policy. + </para> + + <section xml:id="journal"><info><title>The journal file</title></info> + + <para> + All changes made to a zone using dynamic update are stored + in the zone's journal file. This file is automatically created + by the server when the first dynamic update takes place. + The name of the journal file is formed by appending the extension + <filename>.jnl</filename> to the name of the + corresponding zone + file unless specifically overridden. The journal file is in a + binary format and should not be edited manually. + </para> + + <para> + The server will also occasionally write ("dump") + the complete contents of the updated zone to its zone file. + This is not done immediately after + each dynamic update, because that would be too slow when a large + zone is updated frequently. Instead, the dump is delayed by + up to 15 minutes, allowing additional updates to take place. + During the dump process, transient files will be created + with the extensions <filename>.jnw</filename> and + <filename>.jbk</filename>; under ordinary circumstances, these + will be removed when the dump is complete, and can be safely + ignored. + </para> + + <para> + When a server is restarted after a shutdown or crash, it will replay + the journal file to incorporate into the zone any updates that + took + place after the last zone dump. + </para> + + <para> + Changes that result from incoming incremental zone transfers are + also + journalled in a similar way. + </para> + + <para> + The zone files of dynamic zones cannot normally be edited by + hand because they are not guaranteed to contain the most recent + dynamic changes — those are only in the journal file. + The only way to ensure that the zone file of a dynamic zone + is up to date is to run <command>rndc stop</command>. + </para> + + <para> + If you have to make changes to a dynamic zone + manually, the following procedure will work: + Disable dynamic updates to the zone using + <command>rndc freeze <replaceable>zone</replaceable></command>. + This will update the zone's master file with the changes + stored in its <filename>.jnl</filename> file. + Edit the zone file. Run + <command>rndc thaw <replaceable>zone</replaceable></command> + to reload the changed zone and re-enable dynamic updates. + </para> + + <para> + <command>rndc sync <replaceable>zone</replaceable></command> + will update the zone file with changes from the journal file + without stopping dynamic updates; this may be useful for viewing + the current zone state. To remove the <filename>.jnl</filename> + file after updating the zone file, use + <command>rndc sync -clean</command>. + </para> + + </section> + + </section> + + <section xml:id="incremental_zone_transfers"><info><title>Incremental Zone Transfers (IXFR)</title></info> + + <para> + The incremental zone transfer (IXFR) protocol is a way for + slave servers to transfer only changed data, instead of having to + transfer the entire zone. The IXFR protocol is specified in RFC + 1995. See <xref linkend="proposed_standards"/>. + </para> + + <para> + When acting as a master, <acronym>BIND</acronym> 9 + supports IXFR for those zones + where the necessary change history information is available. These + include master zones maintained by dynamic update and slave zones + whose data was obtained by IXFR. For manually maintained master + zones, and for slave zones obtained by performing a full zone + transfer (AXFR), IXFR is supported only if the option + <command>ixfr-from-differences</command> is set + to <userinput>yes</userinput>. + </para> + + <para> + When acting as a slave, <acronym>BIND</acronym> 9 will + attempt to use IXFR unless + it is explicitly disabled. For more information about disabling + IXFR, see the description of the <command>request-ixfr</command> clause + of the <command>server</command> statement. + </para> + </section> + + <section xml:id="split_dns"><info><title>Split DNS</title></info> + + <para> + Setting up different views, or visibility, of the DNS space to + internal and external resolvers is usually referred to as a + <emphasis>Split DNS</emphasis> setup. There are several + reasons an organization would want to set up its DNS this way. + </para> + <para> + One common reason for setting up a DNS system this way is + to hide "internal" DNS information from "external" clients on the + Internet. There is some debate as to whether or not this is actually + useful. + Internal DNS information leaks out in many ways (via email headers, + for example) and most savvy "attackers" can find the information + they need using other means. + However, since listing addresses of internal servers that + external clients cannot possibly reach can result in + connection delays and other annoyances, an organization may + choose to use a Split DNS to present a consistent view of itself + to the outside world. + </para> + <para> + Another common reason for setting up a Split DNS system is + to allow internal networks that are behind filters or in RFC 1918 + space (reserved IP space, as documented in RFC 1918) to resolve DNS + on the Internet. Split DNS can also be used to allow mail from outside + back in to the internal network. + </para> + <section xml:id="split_dns_sample"><info><title>Example split DNS setup</title></info> + <para> + Let's say a company named <emphasis>Example, Inc.</emphasis> + (<literal>example.com</literal>) + has several corporate sites that have an internal network with + reserved + Internet Protocol (IP) space and an external demilitarized zone (DMZ), + or "outside" section of a network, that is available to the public. + </para> + <para> + <emphasis>Example, Inc.</emphasis> wants its internal clients + to be able to resolve external hostnames and to exchange mail with + people on the outside. The company also wants its internal resolvers + to have access to certain internal-only zones that are not available + at all outside of the internal network. + </para> + <para> + In order to accomplish this, the company will set up two sets + of name servers. One set will be on the inside network (in the + reserved + IP space) and the other set will be on bastion hosts, which are + "proxy" + hosts that can talk to both sides of its network, in the DMZ. + </para> + <para> + The internal servers will be configured to forward all queries, + except queries for <filename>site1.internal</filename>, <filename>site2.internal</filename>, <filename>site1.example.com</filename>, + and <filename>site2.example.com</filename>, to the servers + in the + DMZ. These internal servers will have complete sets of information + for <filename>site1.example.com</filename>, <filename>site2.example.com</filename>, <filename>site1.internal</filename>, + and <filename>site2.internal</filename>. + </para> + <para> + To protect the <filename>site1.internal</filename> and <filename>site2.internal</filename> domains, + the internal name servers must be configured to disallow all queries + to these domains from any external hosts, including the bastion + hosts. + </para> + <para> + The external servers, which are on the bastion hosts, will + be configured to serve the "public" version of the <filename>site1</filename> and <filename>site2.example.com</filename> zones. + This could include things such as the host records for public servers + (<filename>www.example.com</filename> and <filename>ftp.example.com</filename>), + and mail exchange (MX) records (<filename>a.mx.example.com</filename> and <filename>b.mx.example.com</filename>). + </para> + <para> + In addition, the public <filename>site1</filename> and <filename>site2.example.com</filename> zones + should have special MX records that contain wildcard (`*') records + pointing to the bastion hosts. This is needed because external mail + servers do not have any other way of looking up how to deliver mail + to those internal hosts. With the wildcard records, the mail will + be delivered to the bastion host, which can then forward it on to + internal hosts. + </para> + <para> + Here's an example of a wildcard MX record: + </para> + <programlisting>* IN MX 10 external1.example.com.</programlisting> + <para> + Now that they accept mail on behalf of anything in the internal + network, the bastion hosts will need to know how to deliver mail + to internal hosts. In order for this to work properly, the resolvers + on + the bastion hosts will need to be configured to point to the internal + name servers for DNS resolution. + </para> + <para> + Queries for internal hostnames will be answered by the internal + servers, and queries for external hostnames will be forwarded back + out to the DNS servers on the bastion hosts. + </para> + <para> + In order for all this to work properly, internal clients will + need to be configured to query <emphasis>only</emphasis> the internal + name servers for DNS queries. This could also be enforced via + selective + filtering on the network. + </para> + <para> + If everything has been set properly, <emphasis>Example, Inc.</emphasis>'s + internal clients will now be able to: + </para> + <itemizedlist> + <listitem> + <simpara> + Look up any hostnames in the <literal>site1</literal> + and + <literal>site2.example.com</literal> zones. + </simpara> + </listitem> + <listitem> + <simpara> + Look up any hostnames in the <literal>site1.internal</literal> and + <literal>site2.internal</literal> domains. + </simpara> + </listitem> + <listitem> + <simpara>Look up any hostnames on the Internet.</simpara> + </listitem> + <listitem> + <simpara>Exchange mail with both internal and external people.</simpara> + </listitem> + </itemizedlist> + <para> + Hosts on the Internet will be able to: + </para> + <itemizedlist> + <listitem> + <simpara> + Look up any hostnames in the <literal>site1</literal> + and + <literal>site2.example.com</literal> zones. + </simpara> + </listitem> + <listitem> + <simpara> + Exchange mail with anyone in the <literal>site1</literal> and + <literal>site2.example.com</literal> zones. + </simpara> + </listitem> + </itemizedlist> + + <para> + Here is an example configuration for the setup we just + described above. Note that this is only configuration information; + for information on how to configure your zone files, see <xref linkend="sample_configuration"/>. + </para> + + <para> + Internal DNS server config: + </para> + +<programlisting> + +acl internals { 172.16.72.0/24; 192.168.1.0/24; }; + +acl externals { <varname>bastion-ips-go-here</varname>; }; + +options { + ... + ... + forward only; + // forward to external servers + forwarders { + <varname>bastion-ips-go-here</varname>; + }; + // sample allow-transfer (no one) + allow-transfer { none; }; + // restrict query access + allow-query { internals; externals; }; + // restrict recursion + allow-recursion { internals; }; + ... + ... +}; + +// sample master zone +zone "site1.example.com" { + type master; + file "m/site1.example.com"; + // do normal iterative resolution (do not forward) + forwarders { }; + allow-query { internals; externals; }; + allow-transfer { internals; }; +}; + +// sample slave zone +zone "site2.example.com" { + type slave; + file "s/site2.example.com"; + masters { 172.16.72.3; }; + forwarders { }; + allow-query { internals; externals; }; + allow-transfer { internals; }; +}; + +zone "site1.internal" { + type master; + file "m/site1.internal"; + forwarders { }; + allow-query { internals; }; + allow-transfer { internals; } +}; + +zone "site2.internal" { + type slave; + file "s/site2.internal"; + masters { 172.16.72.3; }; + forwarders { }; + allow-query { internals }; + allow-transfer { internals; } +}; +</programlisting> + + <para> + External (bastion host) DNS server config: + </para> + +<programlisting> +acl internals { 172.16.72.0/24; 192.168.1.0/24; }; + +acl externals { bastion-ips-go-here; }; + +options { + ... + ... + // sample allow-transfer (no one) + allow-transfer { none; }; + // default query access + allow-query { any; }; + // restrict cache access + allow-query-cache { internals; externals; }; + // restrict recursion + allow-recursion { internals; externals; }; + ... + ... +}; + +// sample slave zone +zone "site1.example.com" { + type master; + file "m/site1.foo.com"; + allow-transfer { internals; externals; }; +}; + +zone "site2.example.com" { + type slave; + file "s/site2.foo.com"; + masters { another_bastion_host_maybe; }; + allow-transfer { internals; externals; } +}; +</programlisting> + + <para> + In the <filename>resolv.conf</filename> (or equivalent) on + the bastion host(s): + </para> + +<programlisting> +search ... +nameserver 172.16.72.2 +nameserver 172.16.72.3 +nameserver 172.16.72.4 +</programlisting> + + </section> + </section> + <section xml:id="tsig"><info><title>TSIG</title></info> + + <para> + TSIG (Transaction SIGnatures) is a mechanism for authenticating DNS + messages, originally specified in RFC 2845. It allows DNS messages + to be cryptographically signed using a shared secret. TSIG can + be used in any DNS transaction, as a way to restrict access to + certain server functions (e.g., recursive queries) to authorized + clients when IP-based access control is insufficient or needs to + be overridden, or as a way to ensure message authenticity when it + is critical to the integrity of the server, such as with dynamic + UPDATE messages or zone transfers from a master to a slave server. + </para> + <para> + This is a guide to setting up TSIG in <acronym>BIND</acronym>. + It describes the configuration syntax and the process of creating + TSIG keys. + </para> + <para> + <command>named</command> supports TSIG for server-to-server + communication, and some of the tools included with + <acronym>BIND</acronym> support it for sending messages to + <command>named</command>: + <itemizedlist> + <listitem> + <xref linkend="man.nsupdate"/> supports TSIG via the + <option>-k</option>, <option>-l</option> and + <option>-y</option> command line options, or via + the <command>key</command> command when running + interactively. + </listitem> + <listitem> + <xref linkend="man.dig"/> supports TSIG via the + <option>-k</option> and <option>-y</option> command + line options. + </listitem> + </itemizedlist> + </para> + + <section><info><title>Generating a Shared Key</title></info> + <para> + TSIG keys can be generated using the <command>tsig-keygen</command> + command; the output of the command is a <command>key</command> directive + suitable for inclusion in <filename>named.conf</filename>. The + key name, algorithm and size can be specified by command line parameters; + the defaults are "tsig-key", HMAC-SHA256, and 256 bits, respectively. + </para> + <para> + Any string which is a valid DNS name can be used as a key name. + For example, a key to be shared between servers called + <emphasis>host1</emphasis> and <emphasis>host2</emphasis> could + be called "host1-host2.", and this key could be generated using: + </para> +<programlisting> + $ tsig-keygen host1-host2. > host1-host2.key +</programlisting> + <para> + This key may then be copied to both hosts. The key name and secret + must be identical on both hosts. + (Note: copying a shared secret from one server to another is beyond + the scope of the DNS. A secure transport mechanism should be used: + secure FTP, SSL, ssh, telephone, encrypted email, etc.) + </para> + <para> + <command>tsig-keygen</command> can also be run as + <command>ddns-confgen</command>, in which case its output includes + additional configuration text for setting up dynamic DNS in + <command>named</command>. See <xref linkend="man.ddns-confgen"/> + for details. + </para> + </section> + + <section><info><title>Loading A New Key</title></info> + <para> + For a key shared between servers called + <emphasis>host1</emphasis> and <emphasis>host2</emphasis>, + the following could be added to each server's + <filename>named.conf</filename> file: + </para> +<programlisting> +key "host1-host2." { + algorithm hmac-sha256; + secret "DAopyf1mhCbFVZw7pgmNPBoLUq8wEUT7UuPoLENP2HY="; +}; +</programlisting> + <para> + (This is the same key generated above using + <command>tsig-keygen</command>.) + </para> + <para> + Since this text contains a secret, it + is recommended that either <filename>named.conf</filename> not be + world-readable, or that the <command>key</command> directive + be stored in a file which is not world-readable, and which is + included in <filename>named.conf</filename> via the + <command>include</command> directive. + </para> + <para> + Once a key has been added to <filename>named.conf</filename> and the + server has been restarted or reconfigured, the server can recognize + the key. If the server receives a message signed by the + key, it will be able to verify the signature. If the signature + is valid, the response will be signed using the same key. + </para> + <para> + TSIG keys that are known to a server can be listed using the + command <command>rndc tsig-list</command>. + </para> + </section> + + <section><info><title>Instructing the Server to Use a Key</title></info> + <para> + A server sending a request to another server must be told whether + to use a key, and if so, which key to use. + </para> + <para> + For example, a key may be specified for each server in the + <command>masters</command> statement in the definition of a + slave zone; in this case, all SOA QUERY messages, NOTIFY + messages, and zone transfer requests (AXFR or IXFR) will be + signed using the specified key. Keys may also be specified + in the <command>also-notify</command> statement of a master + or slave zone, causing NOTIFY messages to be signed using + the specified key. + </para> + <para> + Keys can also be specified in a <command>server</command> + directive. Adding the following on <emphasis>host1</emphasis>, + if the IP address of <emphasis>host2</emphasis> is 10.1.2.3, would + cause <emphasis>all</emphasis> requests from <emphasis>host1</emphasis> + to <emphasis>host2</emphasis>, including normal DNS queries, to be + signed using the <command>host1-host2.</command> key: + </para> +<programlisting> +server 10.1.2.3 { + keys { host1-host2. ;}; +}; +</programlisting> + <para> + Multiple keys may be present in the <command>keys</command> + statement, but only the first one is used. As this directive does + not contain secrets, it can be used in a world-readable file. + </para> + <para> + Requests sent by <emphasis>host2</emphasis> to <emphasis>host1</emphasis> + would <emphasis>not</emphasis> be signed, unless a similar + <command>server</command> directive were in <emphasis>host2</emphasis>'s + configuration file. + </para> + <para> + Whenever any server sends a TSIG-signed DNS request, it will expect + the response to be signed with the same key. If a response is not + signed, or if the signature is not valid, the response will be + rejected. + </para> + </section> + + <section><info><title>TSIG-Based Access Control</title></info> + <para> + TSIG keys may be specified in ACL definitions and ACL directives + such as <command>allow-query</command>, <command>allow-transfer</command> + and <command>allow-update</command>. + The above key would be denoted in an ACL element as + <command>key host1-host2.</command> + </para> + <para> + An example of an <command>allow-update</command> directive using + a TSIG key: + </para> +<programlisting> +allow-update { !{ !localnets; any; }; key host1-host2. ;}; +</programlisting> + <para> + This allows dynamic updates to succeed only if the UPDATE + request comes from an address in <command>localnets</command>, + <emphasis>and</emphasis> if it is signed using the + <command>host1-host2.</command> key. + </para> + <para> + See <xref linkend="dynamic_update_policies"/> for a discussion of + the more flexible <command>update-policy</command> statement. + </para> + </section> + + <section><info><title>Errors</title></info> + <para> + Processing of TSIG-signed messages can result in several errors: + <itemizedlist> + <listitem> + If a TSIG-aware server receives a message signed by an + unknown key, the response will be unsigned, with the TSIG + extended error code set to BADKEY. + </listitem> + <listitem> + If a TSIG-aware server receives a message from a known key + but with an invalid signature, the response will be unsigned, + with the TSIG extended error code set to BADSIG. + </listitem> + <listitem> + If a TSIG-aware server receives a message with a time + outside of the allowed range, the response will be signed, with + the TSIG extended error code set to BADTIME, and the time values + will be adjusted so that the response can be successfully + verified. + </listitem> + </itemizedlist> + In all of the above cases, the server will return a response code + of NOTAUTH (not authenticated). + </para> + </section> + </section> + + <section xml:id="tkey"><info><title>TKEY</title></info> + + <para> + TKEY (Transaction KEY) is a mechanism for automatically negotiating + a shared secret between two hosts, originally specified in RFC 2930. + </para> + <para> + There are several TKEY "modes" that specify how a key is to be + generated or assigned. <acronym>BIND</acronym> 9 implements only + one of these modes: Diffie-Hellman key exchange. Both hosts are + required to have a KEY record with algorithm DH (though this + record is not required to be present in a zone). + </para> + <para> + The TKEY process is initiated by a client or server by sending + a query of type TKEY to a TKEY-aware server. The query must include + an appropriate KEY record in the additional section, and + must be signed using either TSIG or SIG(0) with a previously + established key. The server's response, if successful, will + contain a TKEY record in its answer section. After this transaction, + both participants will have enough information to calculate a + shared secret using Diffie-Hellman key exchange. The shared secret + can then be used by to sign subsequent transactions between the + two servers. + </para> + <para> + TSIG keys known by the server, including TKEY-negotiated keys, can + be listed using <command>rndc tsig-list</command>. + </para> + <para> + TKEY-negotiated keys can be deleted from a server using + <command>rndc tsig-delete</command>. This can also be done via + the TKEY protocol itself, by sending an authenticated TKEY query + specifying the "key deletion" mode. + </para> + + </section> + <section xml:id="sig0"><info><title>SIG(0)</title></info> + + <para> + <acronym>BIND</acronym> partially supports DNSSEC SIG(0) + transaction signatures as specified in RFC 2535 and RFC 2931. + SIG(0) uses public/private keys to authenticate messages. Access control + is performed in the same manner as TSIG keys; privileges can be + granted or denied in ACL directives based on the key name. + </para> + <para> + When a SIG(0) signed message is received, it will only be + verified if the key is known and trusted by the server. The + server will not attempt to recursively fetch or validate the + key. + </para> + <para> + SIG(0) signing of multiple-message TCP streams is not supported. + </para> + <para> + The only tool shipped with <acronym>BIND</acronym> 9 that + generates SIG(0) signed messages is <command>nsupdate</command>. + </para> + </section> + + <section xml:id="DNSSEC"><info><title>DNSSEC</title></info> + <para> + Cryptographic authentication of DNS information is possible + through the DNS Security (<emphasis>DNSSEC-bis</emphasis>) extensions, + defined in RFC 4033, RFC 4034, and RFC 4035. + This section describes the creation and use of DNSSEC signed zones. + </para> + + <para> + In order to set up a DNSSEC secure zone, there are a series + of steps which must be followed. <acronym>BIND</acronym> + 9 ships + with several tools + that are used in this process, which are explained in more detail + below. In all cases, the <option>-h</option> option prints a + full list of parameters. Note that the DNSSEC tools require the + keyset files to be in the working directory or the + directory specified by the <option>-d</option> option, and + that the tools shipped with BIND 9.2.x and earlier are not compatible + with the current ones. + </para> + + <para> + There must also be communication with the administrators of + the parent and/or child zone to transmit keys. A zone's security + status must be indicated by the parent zone for a DNSSEC capable + resolver to trust its data. This is done through the presence + or absence of a <literal>DS</literal> record at the + delegation + point. + </para> + + <para> + For other servers to trust data in this zone, they must + either be statically configured with this zone's zone key or the + zone key of another zone above this one in the DNS tree. + </para> + + <section xml:id="dnssec_keys"><info><title>Generating Keys</title></info> + + <para> + The <command>dnssec-keygen</command> program is used to + generate keys. + </para> + + <para> + A secure zone must contain one or more zone keys. The + zone keys will sign all other records in the zone, as well as + the zone keys of any secure delegated zones. Zone keys must + have the same name as the zone, a name type of + <command>ZONE</command>, and must be usable for + authentication. + It is recommended that zone keys use a cryptographic algorithm + designated as "mandatory to implement" by the IETF; currently + the only one is RSASHA1. + </para> + + <para> + The following command will generate a 768-bit RSASHA1 key for + the <filename>child.example</filename> zone: + </para> + + <para> + <userinput>dnssec-keygen -a RSASHA1 -b 768 -n ZONE child.example.</userinput> + </para> + + <para> + Two output files will be produced: + <filename>Kchild.example.+005+12345.key</filename> and + <filename>Kchild.example.+005+12345.private</filename> + (where + 12345 is an example of a key tag). The key filenames contain + the key name (<filename>child.example.</filename>), + algorithm (3 + is DSA, 1 is RSAMD5, 5 is RSASHA1, etc.), and the key tag (12345 in + this case). + The private key (in the <filename>.private</filename> + file) is + used to generate signatures, and the public key (in the + <filename>.key</filename> file) is used for signature + verification. + </para> + + <para> + To generate another key with the same properties (but with + a different key tag), repeat the above command. + </para> + + <para> + The <command>dnssec-keyfromlabel</command> program is used + to get a key pair from a crypto hardware and build the key + files. Its usage is similar to <command>dnssec-keygen</command>. + </para> + + <para> + The public keys should be inserted into the zone file by + including the <filename>.key</filename> files using + <command>$INCLUDE</command> statements. + </para> + + </section> + <section xml:id="dnssec_signing"><info><title>Signing the Zone</title></info> + + <para> + The <command>dnssec-signzone</command> program is used + to sign a zone. + </para> + + <para> + Any <filename>keyset</filename> files corresponding to + secure subzones should be present. The zone signer will + generate <literal>NSEC</literal>, <literal>NSEC3</literal> + and <literal>RRSIG</literal> records for the zone, as + well as <literal>DS</literal> for the child zones if + <literal>'-g'</literal> is specified. If <literal>'-g'</literal> + is not specified, then DS RRsets for the secure child + zones need to be added manually. + </para> + + <para> + The following command signs the zone, assuming it is in a + file called <filename>zone.child.example</filename>. By + default, all zone keys which have an available private key are + used to generate signatures. + </para> + + <para> + <userinput>dnssec-signzone -o child.example zone.child.example</userinput> + </para> + + <para> + One output file is produced: + <filename>zone.child.example.signed</filename>. This + file + should be referenced by <filename>named.conf</filename> + as the + input file for the zone. + </para> + + <para><command>dnssec-signzone</command> + will also produce a keyset and dsset files and optionally a + dlvset file. These are used to provide the parent zone + administrators with the <literal>DNSKEYs</literal> (or their + corresponding <literal>DS</literal> records) that are the + secure entry point to the zone. + </para> + + </section> + + <section xml:id="dnssec_config"><info><title>Configuring Servers</title></info> + + <para> + To enable <command>named</command> to respond appropriately + to DNS requests from DNSSEC aware clients, + <command>dnssec-enable</command> must be set to yes. + (This is the default setting.) + </para> + + <para> + To enable <command>named</command> to validate answers from + other servers, the <command>dnssec-enable</command> option + must be set to <userinput>yes</userinput>, and the + <command>dnssec-validation</command> options must be set to + <userinput>yes</userinput> or <userinput>auto</userinput>. + </para> + + <para> + If <command>dnssec-validation</command> is set to + <userinput>auto</userinput>, then a default + trust anchor for the DNS root zone will be used. + If it is set to <userinput>yes</userinput>, however, + then at least one trust anchor must be configured + with a <command>trusted-keys</command> or + <command>managed-keys</command> statement in + <filename>named.conf</filename>, or DNSSEC validation + will not occur. The default setting is + <userinput>yes</userinput>. + </para> + + <para> + <command>trusted-keys</command> are copies of DNSKEY RRs + for zones that are used to form the first link in the + cryptographic chain of trust. All keys listed in + <command>trusted-keys</command> (and corresponding zones) + are deemed to exist and only the listed keys will be used + to validated the DNSKEY RRset that they are from. + </para> + + <para> + <command>managed-keys</command> are trusted keys which are + automatically kept up to date via RFC 5011 trust anchor + maintenance. + </para> + + <para> + <command>trusted-keys</command> and + <command>managed-keys</command> are described in more detail + later in this document. + </para> + + <para> + Unlike <acronym>BIND</acronym> 8, <acronym>BIND</acronym> + 9 does not verify signatures on load, so zone keys for + authoritative zones do not need to be specified in the + configuration file. + </para> + + <para> + After DNSSEC gets established, a typical DNSSEC configuration + will look something like the following. It has one or + more public keys for the root. This allows answers from + outside the organization to be validated. It will also + have several keys for parts of the namespace the organization + controls. These are here to ensure that <command>named</command> + is immune to compromises in the DNSSEC components of the security + of parent zones. + </para> + +<programlisting> +managed-keys { + /* Root Key */ + "." initial-key 257 3 3 "BNY4wrWM1nCfJ+CXd0rVXyYmobt7sEEfK3clRbGaTwS + JxrGkxJWoZu6I7PzJu/E9gx4UC1zGAHlXKdE4zYIpRh + aBKnvcC2U9mZhkdUpd1Vso/HAdjNe8LmMlnzY3zy2Xy + 4klWOADTPzSv9eamj8V18PHGjBLaVtYvk/ln5ZApjYg + hf+6fElrmLkdaz MQ2OCnACR817DF4BBa7UR/beDHyp + 5iWTXWSi6XmoJLbG9Scqc7l70KDqlvXR3M/lUUVRbke + g1IPJSidmK3ZyCllh4XSKbje/45SKucHgnwU5jefMtq + 66gKodQj+MiA21AfUVe7u99WzTLzY3qlxDhxYQQ20FQ + 97S+LKUTpQcq27R7AT3/V5hRQxScINqwcz4jYqZD2fQ + dgxbcDTClU0CRBdiieyLMNzXG3"; +}; + +trusted-keys { + /* Key for our organization's forward zone */ + example.com. 257 3 5 "AwEAAaxPMcR2x0HbQV4WeZB6oEDX+r0QM6 + 5KbhTjrW1ZaARmPhEZZe3Y9ifgEuq7vZ/z + GZUdEGNWy+JZzus0lUptwgjGwhUS1558Hb + 4JKUbbOTcM8pwXlj0EiX3oDFVmjHO444gL + kBOUKUf/mC7HvfwYH/Be22GnClrinKJp1O + g4ywzO9WglMk7jbfW33gUKvirTHr25GL7S + TQUzBb5Usxt8lgnyTUHs1t3JwCY5hKZ6Cq + FxmAVZP20igTixin/1LcrgX/KMEGd/biuv + F4qJCyduieHukuY3H4XMAcR+xia2nIUPvm + /oyWR8BW/hWdzOvnSCThlHf3xiYleDbt/o + 1OTQ09A0="; + + /* Key for our reverse zone. */ + 2.0.192.IN-ADDRPA.NET. 257 3 5 "AQOnS4xn/IgOUpBPJ3bogzwc + xOdNax071L18QqZnQQQAVVr+i + LhGTnNGp3HoWQLUIzKrJVZ3zg + gy3WwNT6kZo6c0tszYqbtvchm + gQC8CzKojM/W16i6MG/eafGU3 + siaOdS0yOI6BgPsw+YZdzlYMa + IJGf4M4dyoKIhzdZyQ2bYQrjy + Q4LB0lC7aOnsMyYKHHYeRvPxj + IQXmdqgOJGq+vsevG06zW+1xg + YJh9rCIfnm1GX/KMgxLPG2vXT + D/RnLX+D3T3UL7HJYHJhAZD5L + 59VvjSPsZJHeDCUyWYrvPZesZ + DIRvhDD52SKvbheeTJUm6Ehkz + ytNN2SN96QRk8j/iI8ib"; +}; + +options { + ... + dnssec-enable yes; + dnssec-validation yes; +}; +</programlisting> + + <note><simpara> + None of the keys listed in this example are valid. In particular, + the root key is not valid. + </simpara></note> + + <para> + When DNSSEC validation is enabled and properly configured, + the resolver will reject any answers from signed, secure zones + which fail to validate, and will return SERVFAIL to the client. + </para> + + <para> + Responses may fail to validate for any of several reasons, + including missing, expired, or invalid signatures, a key which + does not match the DS RRset in the parent zone, or an insecure + response from a zone which, according to its parent, should have + been secure. + </para> + + <note> + <para> + When the validator receives a response from an unsigned zone + that has a signed parent, it must confirm with the parent + that the zone was intentionally left unsigned. It does + this by verifying, via signed and validated NSEC/NSEC3 records, + that the parent zone contains no DS records for the child. + </para> + <para> + If the validator <emphasis>can</emphasis> prove that the zone + is insecure, then the response is accepted. However, if it + cannot, then it must assume an insecure response to be a + forgery; it rejects the response and logs an error. + </para> + <para> + The logged error reads "insecurity proof failed" and + "got insecure response; parent indicates it should be secure". + </para> + </note> + </section> + </section> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dnssec.xml"/> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="managed-keys.xml"/> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pkcs11.xml"/> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dlz.xml"/> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dyndb.xml"/> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="catz.xml"/> + + <section xml:id="ipv6"><info><title>IPv6 Support in <acronym>BIND</acronym> 9</title></info> + <para> + <acronym>BIND</acronym> 9 fully supports all currently + defined forms of IPv6 name to address and address to name + lookups. It will also use IPv6 addresses to make queries when + running on an IPv6 capable system. + </para> + + <para> + For forward lookups, <acronym>BIND</acronym> 9 supports + only AAAA records. RFC 3363 deprecated the use of A6 records, + and client-side support for A6 records was accordingly removed + from <acronym>BIND</acronym> 9. + However, authoritative <acronym>BIND</acronym> 9 name servers still + load zone files containing A6 records correctly, answer queries + for A6 records, and accept zone transfer for a zone containing A6 + records. + </para> + + <para> + For IPv6 reverse lookups, <acronym>BIND</acronym> 9 supports + the traditional "nibble" format used in the + <emphasis>ip6.arpa</emphasis> domain, as well as the older, deprecated + <emphasis>ip6.int</emphasis> domain. + Older versions of <acronym>BIND</acronym> 9 + supported the "binary label" (also known as "bitstring") format, + but support of binary labels has been completely removed per + RFC 3363. + Many applications in <acronym>BIND</acronym> 9 do not understand + the binary label format at all any more, and will return an + error if given. + In particular, an authoritative <acronym>BIND</acronym> 9 + name server will not load a zone file containing binary labels. + </para> + + <para> + For an overview of the format and structure of IPv6 addresses, + see <xref linkend="ipv6addresses"/>. + </para> + + <section><info><title>Address Lookups Using AAAA Records</title></info> + + <para> + The IPv6 AAAA record is a parallel to the IPv4 A record, + and, unlike the deprecated A6 record, specifies the entire + IPv6 address in a single record. For example, + </para> + +<programlisting> +$ORIGIN example.com. +host 3600 IN AAAA 2001:db8::1 +</programlisting> + + <para> + Use of IPv4-in-IPv6 mapped addresses is not recommended. + If a host has an IPv4 address, use an A record, not + a AAAA, with <literal>::ffff:192.168.42.1</literal> as + the address. + </para> + </section> + <section><info><title>Address to Name Lookups Using Nibble Format</title></info> + + <para> + When looking up an address in nibble format, the address + components are simply reversed, just as in IPv4, and + <literal>ip6.arpa.</literal> is appended to the + resulting name. + For example, the following would provide reverse name lookup for + a host with address + <literal>2001:db8::1</literal>. + </para> + +<programlisting> +$ORIGIN 0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa. +1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0 14400 IN PTR ( + host.example.com. ) +</programlisting> + + </section> + </section> + </chapter> + + <chapter xml:id="Bv9ARM.ch05"><info><title>The <acronym>BIND</acronym> 9 Lightweight Resolver</title></info> + + <section xml:id="lightweight_resolver"><info><title>The Lightweight Resolver Library</title></info> + + <para> + Traditionally applications have been linked with a stub resolver + library that sends recursive DNS queries to a local caching name + server. + </para> + <para> + IPv6 once introduced new complexity into the resolution process, + such as following A6 chains and DNAME records, and simultaneous + lookup of IPv4 and IPv6 addresses. Though most of the complexity was + then removed, these are hard or impossible + to implement in a traditional stub resolver. + </para> + <para> + <acronym>BIND</acronym> 9 therefore can also provide resolution + services to local clients + using a combination of a lightweight resolver library and a resolver + daemon process running on the local host. These communicate using + a simple UDP-based protocol, the "lightweight resolver protocol" + that is distinct from and simpler than the full DNS protocol. + </para> + </section> + <section xml:id="lwresd"><info><title>Running a Resolver Daemon</title></info> + + <para> + To use the lightweight resolver interface, the system must + run the resolver daemon <command>lwresd</command> or a + local + name server configured with a <command>lwres</command> + statement. + </para> + + <para> + By default, applications using the lightweight resolver library will + make + UDP requests to the IPv4 loopback address (127.0.0.1) on port 921. + The + address can be overridden by <command>lwserver</command> + lines in + <filename>/etc/resolv.conf</filename>. + </para> + + <para> + The daemon currently only looks in the DNS, but in the future + it may use other sources such as <filename>/etc/hosts</filename>, + NIS, etc. + </para> + + <para> + The <command>lwresd</command> daemon is essentially a + caching-only name server that responds to requests using the + lightweight + resolver protocol rather than the DNS protocol. Because it needs + to run on each host, it is designed to require no or minimal + configuration. + Unless configured otherwise, it uses the name servers listed on + <command>nameserver</command> lines in <filename>/etc/resolv.conf</filename> + as forwarders, but is also capable of doing the resolution + autonomously if + none are specified. + </para> + <para> + The <command>lwresd</command> daemon may also be + configured with a + <filename>named.conf</filename> style configuration file, + in + <filename>/etc/lwresd.conf</filename> by default. A name + server may also + be configured to act as a lightweight resolver daemon using the + <command>lwres</command> statement in <filename>named.conf</filename>. + </para> + <para> + The number of client queries that the <command>lwresd</command> + daemon is able to serve can be set using the + <option>lwres-tasks</option> and <option>lwres-clients</option> + statements in the configuration. + </para> + </section> + </chapter> + + <chapter xml:id="Bv9ARM.ch06"><info><title><acronym>BIND</acronym> 9 Configuration Reference</title></info> + + <para> + <acronym>BIND</acronym> 9 configuration is broadly similar + to <acronym>BIND</acronym> 8; however, there are a few new + areas + of configuration, such as views. <acronym>BIND</acronym> + 8 configuration files should work with few alterations in <acronym>BIND</acronym> + 9, although more complex configurations should be reviewed to check + if they can be more efficiently implemented using the new features + found in <acronym>BIND</acronym> 9. + </para> + + <para> + <acronym>BIND</acronym> 4 configuration files can be + converted to the new format + using the shell script + <filename>contrib/named-bootconf/named-bootconf.sh</filename>. + </para> + <section xml:id="configuration_file_elements"><info><title>Configuration File Elements</title></info> + + <para> + Following is a list of elements used throughout the <acronym>BIND</acronym> configuration + file documentation: + </para> + <informaltable colsep="0" rowsep="0"> + <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="2Level-table"> + <colspec colname="1" colnum="1" colsep="0" colwidth="1.855in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="3.770in"/> + <tbody> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>acl_name</varname> + </para> + </entry> + <entry colname="2"> + <para> + The name of an <varname>address_match_list</varname> as + defined by the <command>acl</command> statement. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>address_match_list</varname> + </para> + </entry> + <entry colname="2"> + <para> + A list of one or more + <varname>ip_addr</varname>, + <varname>ip_prefix</varname>, <varname>key_id</varname>, + or <varname>acl_name</varname> elements, see + <xref linkend="address_match_lists"/>. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>masters_list</varname> + </para> + </entry> + <entry colname="2"> + <para> + A named list of one or more <varname>ip_addr</varname> + with optional <varname>key_id</varname> and/or + <varname>ip_port</varname>. + A <varname>masters_list</varname> may include other + <varname>masters_lists</varname>. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>domain_name</varname> + </para> + </entry> + <entry colname="2"> + <para> + A quoted string which will be used as + a DNS name, for example "<literal>my.test.domain</literal>". + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>namelist</varname> + </para> + </entry> + <entry colname="2"> + <para> + A list of one or more <varname>domain_name</varname> + elements. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>dotted_decimal</varname> + </para> + </entry> + <entry colname="2"> + <para> + One to four integers valued 0 through + 255 separated by dots (`.'), such as <command>123</command>, + <command>45.67</command> or <command>89.123.45.67</command>. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>ip4_addr</varname> + </para> + </entry> + <entry colname="2"> + <para> + An IPv4 address with exactly four elements + in <varname>dotted_decimal</varname> notation. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>ip6_addr</varname> + </para> + </entry> + <entry colname="2"> + <para> + An IPv6 address, such as <command>2001:db8::1234</command>. + IPv6 scoped addresses that have ambiguity on their + scope zones must be disambiguated by an appropriate + zone ID with the percent character (`%') as + delimiter. It is strongly recommended to use + string zone names rather than numeric identifiers, + in order to be robust against system configuration + changes. However, since there is no standard + mapping for such names and identifier values, + currently only interface names as link identifiers + are supported, assuming one-to-one mapping between + interfaces and links. For example, a link-local + address <command>fe80::1</command> on the link + attached to the interface <command>ne0</command> + can be specified as <command>fe80::1%ne0</command>. + Note that on most systems link-local addresses + always have the ambiguity, and need to be + disambiguated. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>ip_addr</varname> + </para> + </entry> + <entry colname="2"> + <para> + An <varname>ip4_addr</varname> or <varname>ip6_addr</varname>. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>ip_dscp</varname> + </para> + </entry> + <entry colname="2"> + <para> + A <varname>number</varname> between 0 and 63, used + to select a differentiated services code point (DSCP) + value for use with outgoing traffic on operating systems + that support DSCP. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>ip_port</varname> + </para> + </entry> + <entry colname="2"> + <para> + An IP port <varname>number</varname>. + The <varname>number</varname> is limited to 0 + through 65535, with values + below 1024 typically restricted to use by processes running + as root. + In some cases, an asterisk (`*') character can be used as a + placeholder to + select a random high-numbered port. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>ip_prefix</varname> + </para> + </entry> + <entry colname="2"> + <para> + An IP network specified as an <varname>ip_addr</varname>, + followed by a slash (`/') and then the number of bits in the + netmask. + Trailing zeros in a <varname>ip_addr</varname> + may omitted. + For example, <command>127/8</command> is the + network <command>127.0.0.0</command> with + netmask <command>255.0.0.0</command> and <command>1.2.3.0/28</command> is + network <command>1.2.3.0</command> with netmask <command>255.255.255.240</command>. + </para> + <para> + When specifying a prefix involving a IPv6 scoped address + the scope may be omitted. In that case the prefix will + match packets from any scope. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>key_id</varname> + </para> + </entry> + <entry colname="2"> + <para> + A <varname>domain_name</varname> representing + the name of a shared key, to be used for transaction + security. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>key_list</varname> + </para> + </entry> + <entry colname="2"> + <para> + A list of one or more + <varname>key_id</varname>s, + separated by semicolons and ending with a semicolon. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>number</varname> + </para> + </entry> + <entry colname="2"> + <para> + A non-negative 32-bit integer + (i.e., a number between 0 and 4294967295, inclusive). + Its acceptable value might be further + limited by the context in which it is used. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>fixedpoint</varname> + </para> + </entry> + <entry colname="2"> + <para> + A non-negative real number that can be specified to + the nearest one hundredth. Up to five digits can be + specified before a decimal point, and up to two + digits after, so the maximum value is 99999.99. + Acceptable values might be further limited by the + context in which it is used. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>path_name</varname> + </para> + </entry> + <entry colname="2"> + <para> + A quoted string which will be used as + a pathname, such as <filename>zones/master/my.test.domain</filename>. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>port_list</varname> + </para> + </entry> + <entry colname="2"> + <para> + A list of an <varname>ip_port</varname> or a port + range. + A port range is specified in the form of + <userinput>range</userinput> followed by + two <varname>ip_port</varname>s, + <varname>port_low</varname> and + <varname>port_high</varname>, which represents + port numbers from <varname>port_low</varname> through + <varname>port_high</varname>, inclusive. + <varname>port_low</varname> must not be larger than + <varname>port_high</varname>. + For example, + <userinput>range 1024 65535</userinput> represents + ports from 1024 through 65535. + In either case an asterisk (`*') character is not + allowed as a valid <varname>ip_port</varname>. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>size_spec</varname> + </para> + </entry> + <entry colname="2"> + <para> + A 64-bit unsigned integer, or the keywords + <userinput>unlimited</userinput> or + <userinput>default</userinput>. + </para> + <para> + Integers may take values + 0 <= value <= 18446744073709551615, though + certain parameters + (such as <command>max-journal-size</command>) may + use a more limited range within these extremes. + In most cases, setting a value to 0 does not + literally mean zero; it means "undefined" or + "as big as possible", depending on the context. + See the explanations of particular parameters + that use <varname>size_spec</varname> + for details on how they interpret its use. + </para> + <para> + Numeric values can optionally be followed by a + scaling factor: + <userinput>K</userinput> or <userinput>k</userinput> + for kilobytes, + <userinput>M</userinput> or <userinput>m</userinput> + for megabytes, and + <userinput>G</userinput> or <userinput>g</userinput> + for gigabytes, which scale by 1024, 1024*1024, and + 1024*1024*1024 respectively. + </para> + <para> + <varname>unlimited</varname> generally means + "as big as possible", and is usually the best + way to safely set a very large number. + </para> + <para> + <varname>default</varname> + uses the limit that was in force when the server was started. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>size_or_percent</varname> + </para> + </entry> + <entry colname="2"> + <para> + <varname>size_spec</varname> or integer value + followed by '%' to represent percents. + </para> + <para> + The behavior is exactly the same as + <varname>size_spec</varname>, but + <varname>size_or_percent</varname> allows also + to specify a positive integer value followed by + '%' sign to represent percents. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>yes_or_no</varname> + </para> + </entry> + <entry colname="2"> + <para> + Either <userinput>yes</userinput> or <userinput>no</userinput>. + The words <userinput>true</userinput> and <userinput>false</userinput> are + also accepted, as are the numbers <userinput>1</userinput> + and <userinput>0</userinput>. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>dialup_option</varname> + </para> + </entry> + <entry colname="2"> + <para> + One of <userinput>yes</userinput>, + <userinput>no</userinput>, <userinput>notify</userinput>, + <userinput>notify-passive</userinput>, <userinput>refresh</userinput> or + <userinput>passive</userinput>. + When used in a zone, <userinput>notify-passive</userinput>, + <userinput>refresh</userinput>, and <userinput>passive</userinput> + are restricted to slave and stub zones. + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <section xml:id="address_match_lists"><info><title>Address Match Lists</title></info> + + <section><info><title>Syntax</title></info> + +<programlisting><replaceable>address_match_list</replaceable> = <replaceable>address_match_list_element</replaceable> <command>;</command> ... + +<replaceable>address_match_list_element</replaceable> = [ <command>!</command> ] ( <replaceable>ip_address</replaceable> | <replaceable>ip_prefix</replaceable> | + <command>key</command> <replaceable>key_id</replaceable> | <replaceable>acl_name</replaceable> | <command>{</command> <replaceable>address_match_list</replaceable> <command>}</command> ) +</programlisting> + + </section> + <section><info><title>Definition and Usage</title></info> + + <para> + Address match lists are primarily used to determine access + control for various server operations. They are also used in + the <command>listen-on</command> and <command>sortlist</command> + statements. The elements which constitute an address match + list can be any of the following: + </para> + <itemizedlist> + <listitem> + <simpara>an IP address (IPv4 or IPv6)</simpara> + </listitem> + <listitem> + <simpara>an IP prefix (in `/' notation)</simpara> + </listitem> + <listitem> + <simpara> + a key ID, as defined by the <command>key</command> + statement + </simpara> + </listitem> + <listitem> + <simpara>the name of an address match list defined with + the <command>acl</command> statement + </simpara> + </listitem> + <listitem> + <simpara>a nested address match list enclosed in braces</simpara> + </listitem> + </itemizedlist> + + <para> + Elements can be negated with a leading exclamation mark (`!'), + and the match list names "any", "none", "localhost", and + "localnets" are predefined. More information on those names + can be found in the description of the acl statement. + </para> + + <para> + The addition of the key clause made the name of this syntactic + element something of a misnomer, since security keys can be used + to validate access without regard to a host or network address. + Nonetheless, the term "address match list" is still used + throughout the documentation. + </para> + + <para> + When a given IP address or prefix is compared to an address + match list, the comparison takes place in approximately O(1) + time. However, key comparisons require that the list of keys + be traversed until a matching key is found, and therefore may + be somewhat slower. + </para> + + <para> + The interpretation of a match depends on whether the list is being + used for access control, defining <command>listen-on</command> ports, or in a + <command>sortlist</command>, and whether the element was negated. + </para> + + <para> + When used as an access control list, a non-negated match + allows access and a negated match denies access. If + there is no match, access is denied. The clauses + <command>allow-notify</command>, + <command>allow-recursion</command>, + <command>allow-recursion-on</command>, + <command>allow-query</command>, + <command>allow-query-on</command>, + <command>allow-query-cache</command>, + <command>allow-query-cache-on</command>, + <command>allow-transfer</command>, + <command>allow-update</command>, + <command>allow-update-forwarding</command>, + <command>blackhole</command>, and + <command>keep-response-order</command> all use address match + lists. Similarly, the <command>listen-on</command> option will cause the + server to refuse queries on any of the machine's + addresses which do not match the list. + </para> + + <para> + Order of insertion is significant. If more than one element + in an ACL is found to match a given IP address or prefix, + preference will be given to the one that came + <emphasis>first</emphasis> in the ACL definition. + Because of this first-match behavior, an element that + defines a subset of another element in the list should + come before the broader element, regardless of whether + either is negated. For example, in + <command>1.2.3/24; ! 1.2.3.13;</command> + the 1.2.3.13 element is completely useless because the + algorithm will match any lookup for 1.2.3.13 to the 1.2.3/24 + element. Using <command>! 1.2.3.13; 1.2.3/24</command> fixes + that problem by having 1.2.3.13 blocked by the negation, but + all other 1.2.3.* hosts fall through. + </para> + </section> + </section> + + <section xml:id="comment_syntax"><info><title>Comment Syntax</title></info> + + <para> + The <acronym>BIND</acronym> 9 comment syntax allows for + comments to appear + anywhere that whitespace may appear in a <acronym>BIND</acronym> configuration + file. To appeal to programmers of all kinds, they can be written + in the C, C++, or shell/perl style. + </para> + + <section><info><title>Syntax</title></info> + + <para> + <programlisting>/* This is a <acronym>BIND</acronym> comment as in C */</programlisting> + <programlisting>// This is a <acronym>BIND</acronym> comment as in C++</programlisting> + <programlisting># This is a <acronym>BIND</acronym> comment as in common UNIX shells +# and perl</programlisting> + </para> + </section> + <section><info><title>Definition and Usage</title></info> + + <para> + Comments may appear anywhere that whitespace may appear in + a <acronym>BIND</acronym> configuration file. + </para> + <para> + C-style comments start with the two characters /* (slash, + star) and end with */ (star, slash). Because they are completely + delimited with these characters, they can be used to comment only + a portion of a line or to span multiple lines. + </para> + <para> + C-style comments cannot be nested. For example, the following + is not valid because the entire comment ends with the first */: + </para> + <para> + +<programlisting>/* This is the start of a comment. + This is still part of the comment. +/* This is an incorrect attempt at nesting a comment. */ + This is no longer in any comment. */ +</programlisting> + + </para> + + <para> + C++-style comments start with the two characters // (slash, + slash) and continue to the end of the physical line. They cannot + be continued across multiple physical lines; to have one logical + comment span multiple lines, each line must use the // pair. + For example: + </para> + <para> + +<programlisting>// This is the start of a comment. The next line +// is a new comment, even though it is logically +// part of the previous comment. +</programlisting> + + </para> + <para> + Shell-style (or perl-style, if you prefer) comments start + with the character <literal>#</literal> (number sign) + and continue to the end of the + physical line, as in C++ comments. + For example: + </para> + + <para> + +<programlisting># This is the start of a comment. The next line +# is a new comment, even though it is logically +# part of the previous comment. +</programlisting> + + </para> + + <warning> + <para> + You cannot use the semicolon (`;') character + to start a comment such as you would in a zone file. The + semicolon indicates the end of a configuration + statement. + </para> + </warning> + </section> + </section> + </section> + + <section xml:id="Configuration_File_Grammar"><info><title>Configuration File Grammar</title></info> + + <para> + A <acronym>BIND</acronym> 9 configuration consists of + statements and comments. + Statements end with a semicolon. Statements and comments are the + only elements that can appear without enclosing braces. Many + statements contain a block of sub-statements, which are also + terminated with a semicolon. + </para> + + <para> + The following statements are supported: + </para> + + <informaltable colsep="0" rowsep="0"> + <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="2Level-table"> + <colspec colname="1" colnum="1" colsep="0" colwidth="1.336in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="3.778in"/> + <tbody> + <row rowsep="0"> + <entry colname="1"> + <para><command>acl</command></para> + </entry> + <entry colname="2"> + <para> + defines a named IP address + matching list, for access control and other uses. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>controls</command></para> + </entry> + <entry colname="2"> + <para> + declares control channels to be used + by the <command>rndc</command> utility. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>include</command></para> + </entry> + <entry colname="2"> + <para> + includes a file. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>key</command></para> + </entry> + <entry colname="2"> + <para> + specifies key information for use in + authentication and authorization using TSIG. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>logging</command></para> + </entry> + <entry colname="2"> + <para> + specifies what the server logs, and where + the log messages are sent. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>lwres</command></para> + </entry> + <entry colname="2"> + <para> + configures <command>named</command> to + also act as a light-weight resolver daemon (<command>lwresd</command>). + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>masters</command></para> + </entry> + <entry colname="2"> + <para> + defines a named masters list for + inclusion in stub and slave zones' + <command>masters</command> or + <command>also-notify</command> lists. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>options</command></para> + </entry> + <entry colname="2"> + <para> + controls global server configuration + options and sets defaults for other statements. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>server</command></para> + </entry> + <entry colname="2"> + <para> + sets certain configuration options on + a per-server basis. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>statistics-channels</command></para> + </entry> + <entry colname="2"> + <para> + declares communication channels to get access to + <command>named</command> statistics. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>trusted-keys</command></para> + </entry> + <entry colname="2"> + <para> + defines trusted DNSSEC keys. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>managed-keys</command></para> + </entry> + <entry colname="2"> + <para> + lists DNSSEC keys to be kept up to date + using RFC 5011 trust anchor maintenance. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>view</command></para> + </entry> + <entry colname="2"> + <para> + defines a view. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>zone</command></para> + </entry> + <entry colname="2"> + <para> + defines a zone. + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para> + The <command>logging</command> and + <command>options</command> statements may only occur once + per + configuration. + </para> + + <section xml:id="acl_grammar"><info><title><command>acl</command> Statement Grammar</title></info> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="acl.grammar.xml"/> + </section> + <section xml:id="acl"><info><title><command>acl</command> Statement Definition and + Usage</title></info> + + <para> + The <command>acl</command> statement assigns a symbolic + name to an address match list. It gets its name from a primary + use of address match lists: Access Control Lists (ACLs). + </para> + + <para> + The following ACLs are built-in: + </para> + + <informaltable colsep="0" rowsep="0"> + <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="3Level-table"> + <colspec colname="1" colnum="1" colsep="0" colwidth="1.130in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="4.000in"/> + <tbody> + <row rowsep="0"> + <entry colname="1"> + <para><command>any</command></para> + </entry> + <entry colname="2"> + <para> + Matches all hosts. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>none</command></para> + </entry> + <entry colname="2"> + <para> + Matches no hosts. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>localhost</command></para> + </entry> + <entry colname="2"> + <para> + Matches the IPv4 and IPv6 addresses of all network + interfaces on the system. When addresses are + added or removed, the <command>localhost</command> + ACL element is updated to reflect the changes. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>localnets</command></para> + </entry> + <entry colname="2"> + <para> + Matches any host on an IPv4 or IPv6 network + for which the system has an interface. + When addresses are added or removed, + the <command>localnets</command> + ACL element is updated to reflect the changes. + Some systems do not provide a way to determine the prefix + lengths of + local IPv6 addresses. + In such a case, <command>localnets</command> + only matches the local + IPv6 addresses, just like <command>localhost</command>. + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </section> + <section xml:id="controls_grammar"><info><title><command>controls</command> Statement Grammar</title></info> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="controls.grammar.xml"/> + </section> + + <section xml:id="controls_statement_definition_and_usage"><info><title><command>controls</command> Statement Definition and + Usage</title></info> + + <para> + The <command>controls</command> statement declares control + channels to be used by system administrators to control the + operation of the name server. These control channels are + used by the <command>rndc</command> utility to send + commands to and retrieve non-DNS results from a name server. + </para> + + <para> + An <command>inet</command> control channel is a TCP socket + listening at the specified <command>ip_port</command> on the + specified <command>ip_addr</command>, which can be an IPv4 or IPv6 + address. An <command>ip_addr</command> of <literal>*</literal> (asterisk) is + interpreted as the IPv4 wildcard address; connections will be + accepted on any of the system's IPv4 addresses. + To listen on the IPv6 wildcard address, + use an <command>ip_addr</command> of <literal>::</literal>. + If you will only use <command>rndc</command> on the local host, + using the loopback address (<literal>127.0.0.1</literal> + or <literal>::1</literal>) is recommended for maximum security. + </para> + + <para> + If no port is specified, port 953 is used. The asterisk + "<literal>*</literal>" cannot be used for <command>ip_port</command>. + </para> + + <para> + The ability to issue commands over the control channel is + restricted by the <command>allow</command> and + <command>keys</command> clauses. + Connections to the control channel are permitted based on the + <command>address_match_list</command>. This is for simple + IP address based filtering only; any <command>key_id</command> + elements of the <command>address_match_list</command> + are ignored. + </para> + + <para> + A <command>unix</command> control channel is a UNIX domain + socket listening at the specified path in the file system. + Access to the socket is specified by the <command>perm</command>, + <command>owner</command> and <command>group</command> clauses. + Note on some platforms (SunOS and Solaris) the permissions + (<command>perm</command>) are applied to the parent directory + as the permissions on the socket itself are ignored. + </para> + + <para> + The primary authorization mechanism of the command + channel is the <command>key_list</command>, which + contains a list of <command>key_id</command>s. + Each <command>key_id</command> in the <command>key_list</command> + is authorized to execute commands over the control channel. + See <xref linkend="rndc"/> in <xref linkend="admin_tools"/>) + for information about configuring keys in <command>rndc</command>. + </para> + + <para> + If the <command>read-only</command> clause is enabled, the + control channel is limited to the following set of read-only + commands: <command>nta -dump</command>, + <command>null</command>, <command>status</command>, + <command>showzone</command>, <command>testgen</command>, and + <command>zonestatus</command>. By default, + <command>read-only</command> is not enabled and the control + channel allows read-write access. + </para> + + <para> + If no <command>controls</command> statement is present, + <command>named</command> will set up a default + control channel listening on the loopback address 127.0.0.1 + and its IPv6 counterpart ::1. + In this case, and also when the <command>controls</command> statement + is present but does not have a <command>keys</command> clause, + <command>named</command> will attempt to load the command channel key + from the file <filename>rndc.key</filename> in + <filename>/etc</filename> (or whatever <varname>sysconfdir</varname> + was specified as when <acronym>BIND</acronym> was built). + To create a <filename>rndc.key</filename> file, run + <userinput>rndc-confgen -a</userinput>. + </para> + + <para> + The <filename>rndc.key</filename> feature was created to + ease the transition of systems from <acronym>BIND</acronym> 8, + which did not have digital signatures on its command channel + messages and thus did not have a <command>keys</command> clause. + + It makes it possible to use an existing <acronym>BIND</acronym> 8 + configuration file in <acronym>BIND</acronym> 9 unchanged, + and still have <command>rndc</command> work the same way + <command>ndc</command> worked in BIND 8, simply by executing the + command <userinput>rndc-confgen -a</userinput> after BIND 9 is + installed. + </para> + + <para> + Since the <filename>rndc.key</filename> feature + is only intended to allow the backward-compatible usage of + <acronym>BIND</acronym> 8 configuration files, this + feature does not + have a high degree of configurability. You cannot easily change + the key name or the size of the secret, so you should make a + <filename>rndc.conf</filename> with your own key if you + wish to change + those things. The <filename>rndc.key</filename> file + also has its + permissions set such that only the owner of the file (the user that + <command>named</command> is running as) can access it. + If you + desire greater flexibility in allowing other users to access + <command>rndc</command> commands, then you need to create + a + <filename>rndc.conf</filename> file and make it group + readable by a group + that contains the users who should have access. + </para> + + <para> + To disable the command channel, use an empty + <command>controls</command> statement: + <command>controls { };</command>. + </para> + + </section> + <section xml:id="include_grammar"><info><title><command>include</command> Statement Grammar</title></info> + + <programlisting><command>include</command> <replaceable>filename</replaceable><command>;</command></programlisting> + </section> + <section xml:id="include_statement"><info><title><command>include</command> Statement Definition and Usage</title></info> + + <para> + The <command>include</command> statement inserts the + specified file at the point where the <command>include</command> + statement is encountered. The <command>include</command> + statement facilitates the administration of configuration + files + by permitting the reading or writing of some things but not + others. For example, the statement could include private keys + that are readable only by the name server. + </para> + + </section> + <section xml:id="key_grammar"><info><title><command>key</command> Statement Grammar</title></info> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="key.grammar.xml"/> + </section> + + <section xml:id="key_statement"><info><title><command>key</command> Statement Definition and Usage</title></info> + + <para> + The <command>key</command> statement defines a shared + secret key for use with TSIG (see <xref linkend="tsig"/>) + or the command channel + (see <xref linkend="controls_statement_definition_and_usage"/>). + </para> + + <para> + The <command>key</command> statement can occur at the + top level + of the configuration file or inside a <command>view</command> + statement. Keys defined in top-level <command>key</command> + statements can be used in all views. Keys intended for use in + a <command>controls</command> statement + (see <xref linkend="controls_statement_definition_and_usage"/>) + must be defined at the top level. + </para> + + <para> + The <replaceable>key_id</replaceable>, also known as the + key name, is a domain name uniquely identifying the key. It can + be used in a <command>server</command> + statement to cause requests sent to that + server to be signed with this key, or in address match lists to + verify that incoming requests have been signed with a key + matching this name, algorithm, and secret. + </para> + + <para> + The <replaceable>algorithm_id</replaceable> is a string + that specifies a security/authentication algorithm. The + <command>named</command> server supports <literal>hmac-md5</literal>, + <literal>hmac-sha1</literal>, <literal>hmac-sha224</literal>, + <literal>hmac-sha256</literal>, <literal>hmac-sha384</literal> + and <literal>hmac-sha512</literal> TSIG authentication. + Truncated hashes are supported by appending the minimum + number of required bits preceded by a dash, e.g. + <literal>hmac-sha1-80</literal>. The + <replaceable>secret_string</replaceable> is the secret + to be used by the algorithm, and is treated as a Base64 + encoded string. + </para> + + </section> + <section xml:id="logging_grammar"><info><title><command>logging</command> Statement Grammar</title></info> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="logging.grammar.xml"/> + </section> + + <section xml:id="logging_statement"><info><title><command>logging</command> Statement Definition and Usage</title></info> + + <para> + The <command>logging</command> statement configures a + wide + variety of logging options for the name server. Its <command>channel</command> phrase + associates output methods, format options and severity levels with + a name that can then be used with the <command>category</command> phrase + to select how various classes of messages are logged. + </para> + <para> + Only one <command>logging</command> statement is used to + define + as many channels and categories as are wanted. If there is no <command>logging</command> statement, + the logging configuration will be: + </para> + +<programlisting>logging { + category default { default_syslog; default_debug; }; + category unmatched { null; }; +}; +</programlisting> + + <para> + If <command>named</command> is started with the + <option>-L</option> option, it logs to the specified file + at startup, instead of using syslog. In this case the logging + configuration will be: + </para> + +<programlisting>logging { + category default { default_logfile; default_debug; }; + category unmatched { null; }; +}; +</programlisting> + + <para> + In <acronym>BIND</acronym> 9, the logging configuration + is only established when + the entire configuration file has been parsed. In <acronym>BIND</acronym> 8, it was + established as soon as the <command>logging</command> + statement + was parsed. When the server is starting up, all logging messages + regarding syntax errors in the configuration file go to the default + channels, or to standard error if the <option>-g</option> option + was specified. + </para> + + <section xml:id="channel"><info><title>The <command>channel</command> Phrase</title></info> + + <para> + All log output goes to one or more <emphasis>channels</emphasis>; + you can make as many of them as you want. + </para> + + <para> + Every channel definition must include a destination clause that + says whether messages selected for the channel go to a file, to a + particular syslog facility, to the standard error stream, or are + discarded. It can optionally also limit the message severity level + that will be accepted by the channel (the default is + <command>info</command>), and whether to include a + <command>named</command>-generated time stamp, the + category name + and/or severity level (the default is not to include any). + </para> + + <para> + The <command>null</command> destination clause + causes all messages sent to the channel to be discarded; + in that case, other options for the channel are meaningless. + </para> + + <para> + The <command>file</command> destination clause directs + the channel + to a disk file. It can include limitations + both on how large the file is allowed to become, and how many + versions + of the file will be saved each time the file is opened. + </para> + + <para> + If you use the <command>versions</command> log file + option, then + <command>named</command> will retain that many backup + versions of the file by + renaming them when opening. For example, if you choose to keep + three old versions + of the file <filename>lamers.log</filename>, then just + before it is opened + <filename>lamers.log.1</filename> is renamed to + <filename>lamers.log.2</filename>, <filename>lamers.log.0</filename> is renamed + to <filename>lamers.log.1</filename>, and <filename>lamers.log</filename> is + renamed to <filename>lamers.log.0</filename>. + You can say <command>versions unlimited</command> to + not limit + the number of versions. + If a <command>size</command> option is associated with + the log file, + then renaming is only done when the file being opened exceeds the + indicated size. No backup versions are kept by default; any + existing + log file is simply appended. + </para> + + <para> + The <command>size</command> option for files is used + to limit log + growth. If the file ever exceeds the size, then <command>named</command> will + stop writing to the file unless it has a <command>versions</command> option + associated with it. If backup versions are kept, the files are + rolled as + described above and a new one begun. If there is no + <command>versions</command> option, no more data will + be written to the log + until some out-of-band mechanism removes or truncates the log to + less than the + maximum size. The default behavior is not to limit the size of + the + file. + </para> + + <para> + Example usage of the <command>size</command> and + <command>versions</command> options: + </para> + +<programlisting>channel an_example_channel { + file "example.log" versions 3 size 20m; + print-time yes; + print-category yes; +}; +</programlisting> + + <para> + The <command>syslog</command> destination clause + directs the + channel to the system log. Its argument is a + syslog facility as described in the <command>syslog</command> man + page. Known facilities are <command>kern</command>, <command>user</command>, + <command>mail</command>, <command>daemon</command>, <command>auth</command>, + <command>syslog</command>, <command>lpr</command>, <command>news</command>, + <command>uucp</command>, <command>cron</command>, <command>authpriv</command>, + <command>ftp</command>, <command>local0</command>, <command>local1</command>, + <command>local2</command>, <command>local3</command>, <command>local4</command>, + <command>local5</command>, <command>local6</command> and + <command>local7</command>, however not all facilities + are supported on + all operating systems. + How <command>syslog</command> will handle messages + sent to + this facility is described in the <command>syslog.conf</command> man + page. If you have a system which uses a very old version of <command>syslog</command> that + only uses two arguments to the <command>openlog()</command> function, + then this clause is silently ignored. + </para> + <para> + On Windows machines syslog messages are directed to the EventViewer. + </para> + <para> + The <command>severity</command> clause works like <command>syslog</command>'s + "priorities", except that they can also be used if you are writing + straight to a file rather than using <command>syslog</command>. + Messages which are not at least of the severity level given will + not be selected for the channel; messages of higher severity + levels + will be accepted. + </para> + <para> + If you are using <command>syslog</command>, then the <command>syslog.conf</command> priorities + will also determine what eventually passes through. For example, + defining a channel facility and severity as <command>daemon</command> and <command>debug</command> but + only logging <command>daemon.warning</command> via <command>syslog.conf</command> will + cause messages of severity <command>info</command> and + <command>notice</command> to + be dropped. If the situation were reversed, with <command>named</command> writing + messages of only <command>warning</command> or higher, + then <command>syslogd</command> would + print all messages it received from the channel. + </para> + + <para> + The <command>stderr</command> destination clause + directs the + channel to the server's standard error stream. This is intended + for + use when the server is running as a foreground process, for + example + when debugging a configuration. + </para> + + <para> + The server can supply extensive debugging information when + it is in debugging mode. If the server's global debug level is + greater + than zero, then debugging mode will be active. The global debug + level is set either by starting the <command>named</command> server + with the <option>-d</option> flag followed by a positive integer, + or by running <command>rndc trace</command>. + The global debug level + can be set to zero, and debugging mode turned off, by running <command>rndc +notrace</command>. All debugging messages in the server have a debug + level, and higher debug levels give more detailed output. Channels + that specify a specific debug severity, for example: + </para> + +<programlisting>channel specific_debug_level { + file "foo"; + severity debug 3; +}; +</programlisting> + + <para> + will get debugging output of level 3 or less any time the + server is in debugging mode, regardless of the global debugging + level. Channels with <command>dynamic</command> + severity use the + server's global debug level to determine what messages to print. + </para> + <para> + If <command>print-time</command> has been turned on, + then + the date and time will be logged. <command>print-time</command> may + be specified for a <command>syslog</command> channel, + but is usually + pointless since <command>syslog</command> also logs + the date and + time. If <command>print-category</command> is + requested, then the + category of the message will be logged as well. Finally, if <command>print-severity</command> is + on, then the severity level of the message will be logged. The <command>print-</command> options may + be used in any combination, and will always be printed in the + following + order: time, category, severity. Here is an example where all + three <command>print-</command> options + are on: + </para> + + <para> + <computeroutput>28-Feb-2000 15:05:32.863 general: notice: running</computeroutput> + </para> + + <para> + If <command>buffered</command> has been turned on the output + to files will not be flushed after each log entry. By default + all log messages are flushed. + </para> + + <para> + There are four predefined channels that are used for + <command>named</command>'s default logging as follows. + If <command>named</command> is started with the + <option>-L</option> then a + fifth channel <command>default_logfile</command> is added. + How they are + used is described in <xref linkend="the_category_phrase"/>. + </para> + +<programlisting>channel default_syslog { + // send to syslog's daemon facility + syslog daemon; + // only send priority info and higher + severity info; +}; + +channel default_debug { + // write to named.run in the working directory + // Note: stderr is used instead of "named.run" if + // the server is started with the '-g' option. + file "named.run"; + // log at the server's current debug level + severity dynamic; +}; + +channel default_stderr { + // writes to stderr + stderr; + // only send priority info and higher + severity info; +}; + +channel null { + // toss anything sent to this channel + null; +}; + +channel default_logfile { + // this channel is only present if named is + // started with the -L option, whose argument + // provides the file name + file "..."; + // log at the server's current debug level + severity dynamic; +}; +</programlisting> + + <para> + The <command>default_debug</command> channel has the + special + property that it only produces output when the server's debug + level is + nonzero. It normally writes to a file called <filename>named.run</filename> + in the server's working directory. + </para> + + <para> + For security reasons, when the <option>-u</option> + command line option is used, the <filename>named.run</filename> file + is created only after <command>named</command> has + changed to the + new UID, and any debug output generated while <command>named</command> is + starting up and still running as root is discarded. If you need + to capture this output, you must run the server with the <option>-L</option> + option to specify a default logfile, or the <option>-g</option> + option to log to standard error which you can redirect to a file. + </para> + + <para> + Once a channel is defined, it cannot be redefined. Thus you + cannot alter the built-in channels directly, but you can modify + the default logging by pointing categories at channels you have + defined. + </para> + </section> + + <section xml:id="the_category_phrase"><info><title>The <command>category</command> Phrase</title></info> + + <para> + There are many categories, so you can send the logs you want + to see wherever you want, without seeing logs you don't want. If + you don't specify a list of channels for a category, then log + messages + in that category will be sent to the <command>default</command> category + instead. If you don't specify a default category, the following + "default default" is used: + </para> + +<programlisting>category default { default_syslog; default_debug; }; +</programlisting> + + <para> + If you start <command>named</command> with the + <option>-L</option> option then the default category is: + </para> + +<programlisting>category default { default_logfile; default_debug; }; +</programlisting> + + <para> + As an example, let's say you want to log security events to + a file, but you also want keep the default logging behavior. You'd + specify the following: + </para> + +<programlisting>channel my_security_channel { + file "my_security_file"; + severity info; +}; +category security { + my_security_channel; + default_syslog; + default_debug; +};</programlisting> + + <para> + To discard all messages in a category, specify the <command>null</command> channel: + </para> + +<programlisting>category xfer-out { null; }; +category notify { null; }; +</programlisting> + + <para> + Following are the available categories and brief descriptions + of the types of log information they contain. More + categories may be added in future <acronym>BIND</acronym> releases. + </para> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="logging-categories.xml"/> + </section> + <section xml:id="query_errors"><info><title>The <command>query-errors</command> Category</title></info> + <para> + The <command>query-errors</command> category is + specifically intended for debugging purposes: To identify + why and how specific queries result in responses which + indicate an error. + Messages of this category are therefore only logged + with <command>debug</command> levels. + </para> + + <para> + At the debug levels of 1 or higher, each response with the + rcode of SERVFAIL is logged as follows: + </para> + <para> + <computeroutput>client 127.0.0.1#61502: query failed (SERVFAIL) for www.example.com/IN/AAAA at query.c:3880</computeroutput> + </para> + <para> + This means an error resulting in SERVFAIL was + detected at line 3880 of source file + <filename>query.c</filename>. + Log messages of this level will particularly + help identify the cause of SERVFAIL for an + authoritative server. + </para> + <para> + At the debug levels of 2 or higher, detailed context + information of recursive resolutions that resulted in + SERVFAIL is logged. + The log message will look like as follows: + </para> + <para> +<!-- NOTE: newlines and some spaces added so this would fit on page --> + <programlisting> +fetch completed at resolver.c:2970 for www.example.com/A +in 30.000183: timed out/success [domain:example.com, +referral:2,restart:7,qrysent:8,timeout:5,lame:0,neterr:0, +badresp:1,adberr:0,findfail:0,valfail:0] + </programlisting> + </para> + <para> + The first part before the colon shows that a recursive + resolution for AAAA records of www.example.com completed + in 30.000183 seconds and the final result that led to the + SERVFAIL was determined at line 2970 of source file + <filename>resolver.c</filename>. + </para> + <para> + The following part shows the detected final result and the + latest result of DNSSEC validation. + The latter is always success when no validation attempt + is made. + In this example, this query resulted in SERVFAIL probably + because all name servers are down or unreachable, leading + to a timeout in 30 seconds. + DNSSEC validation was probably not attempted. + </para> + <para> + The last part enclosed in square brackets shows statistics + information collected for this particular resolution + attempt. + The <varname>domain</varname> field shows the deepest zone + that the resolver reached; + it is the zone where the error was finally detected. + The meaning of the other fields is summarized in the + following table. + </para> + + <informaltable colsep="0" rowsep="0"> + <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="4Level-table"> + <colspec colname="1" colnum="1" colsep="0" colwidth="1.150in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="3.350in"/> + <tbody> + <row rowsep="0"> + <entry colname="1"> + <para><varname>referral</varname></para> + </entry> + <entry colname="2"> + <para> + The number of referrals the resolver received + throughout the resolution process. + In the above example this is 2, which are most + likely com and example.com. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><varname>restart</varname></para> + </entry> + <entry colname="2"> + <para> + The number of cycles that the resolver tried + remote servers at the <varname>domain</varname> + zone. + In each cycle the resolver sends one query + (possibly resending it, depending on the response) + to each known name server of + the <varname>domain</varname> zone. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><varname>qrysent</varname></para> + </entry> + <entry colname="2"> + <para> + The number of queries the resolver sent at the + <varname>domain</varname> zone. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><varname>timeout</varname></para> + </entry> + <entry colname="2"> + <para> + The number of timeouts since the resolver + received the last response. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><varname>lame</varname></para> + </entry> + <entry colname="2"> + <para> + The number of lame servers the resolver detected + at the <varname>domain</varname> zone. + A server is detected to be lame either by an + invalid response or as a result of lookup in + BIND9's address database (ADB), where lame + servers are cached. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><varname>neterr</varname></para> + </entry> + <entry colname="2"> + <para> + The number of erroneous results that the + resolver encountered in sending queries + at the <varname>domain</varname> zone. + One common case is the remote server is + unreachable and the resolver receives an ICMP + unreachable error message. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><varname>badresp</varname></para> + </entry> + <entry colname="2"> + <para> + The number of unexpected responses (other than + <varname>lame</varname>) to queries sent by the + resolver at the <varname>domain</varname> zone. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><varname>adberr</varname></para> + </entry> + <entry colname="2"> + <para> + Failures in finding remote server addresses + of the <varname>domain</varname> zone in the ADB. + One common case of this is that the remote + server's name does not have any address records. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><varname>findfail</varname></para> + </entry> + <entry colname="2"> + <para> + Failures of resolving remote server addresses. + This is a total number of failures throughout + the resolution process. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><varname>valfail</varname></para> + </entry> + <entry colname="2"> + <para> + Failures of DNSSEC validation. + Validation failures are counted throughout + the resolution process (not limited to + the <varname>domain</varname> zone), but should + only happen in <varname>domain</varname>. + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <para> + At the debug levels of 3 or higher, the same messages + as those at the debug 1 level are logged for other errors + than SERVFAIL. + Note that negative responses such as NXDOMAIN are not + regarded as errors here. + </para> + <para> + At the debug levels of 4 or higher, the same messages + as those at the debug 2 level are logged for other errors + than SERVFAIL. + Unlike the above case of level 3, messages are logged for + negative responses. + This is because any unexpected results can be difficult to + debug in the recursion case. + </para> + </section> + </section> + + <section xml:id="lwres_grammar"><info><title><command>lwres</command> Statement Grammar</title></info> + + <para> + This is the grammar of the <command>lwres</command> + statement in the <filename>named.conf</filename> file: + </para> + +<programlisting><command>lwres {</command> + [ <command>listen-on {</command> + ( <replaceable>ip_addr</replaceable> [ <command>port</command> <replaceable>ip_port</replaceable> ] [ <command>dscp</command> <replaceable>ip_dscp</replaceable> ] <command>;</command> ) + ... + <command>};</command> ] + [ <command>view</command> <replaceable>view_name</replaceable><command>;</command> ] + [ <command>search {</command> <replaceable>domain_name</replaceable> <command>;</command> ... <command>};</command> ] + [ <command>ndots</command> <replaceable>number</replaceable><command>;</command> ] + [ <command>lwres-tasks</command> <replaceable>number</replaceable><command>;</command> ] + [ <command>lwres-clients</command> <replaceable>number</replaceable><command>;</command> ] +<command>};</command> +</programlisting> + + </section> + <section xml:id="lwres_statement"><info><title><command>lwres</command> Statement Definition and Usage</title></info> + + <para> + The <command>lwres</command> statement configures the + name + server to also act as a lightweight resolver server. (See + <xref linkend="lwresd"/>.) There may be multiple + <command>lwres</command> statements configuring + lightweight resolver servers with different properties. + </para> + + <para> + The <command>listen-on</command> statement specifies a + list of + IPv4 addresses (and ports) that this instance of a lightweight + resolver daemon + should accept requests on. If no port is specified, port 921 is + used. + If this statement is omitted, requests will be accepted on + 127.0.0.1, + port 921. + </para> + + <para> + The <command>view</command> statement binds this + instance of a + lightweight resolver daemon to a view in the DNS namespace, so that + the + response will be constructed in the same manner as a normal DNS + query + matching this view. If this statement is omitted, the default view + is + used, and if there is no default view, an error is triggered. + </para> + + <para> + The <command>search</command> statement is equivalent to + the + <command>search</command> statement in + <filename>/etc/resolv.conf</filename>. It provides a + list of domains + which are appended to relative names in queries. + </para> + + <para> + The <command>ndots</command> statement is equivalent to + the + <command>ndots</command> statement in + <filename>/etc/resolv.conf</filename>. It indicates the + minimum + number of dots in a relative domain name that should result in an + exact match lookup before search path elements are appended. + </para> + <para> + The <option>lwres-tasks</option> statement specifies the number + of worker threads the lightweight resolver will dedicate to serving + clients. By default the number is the same as the number of CPUs on + the system; this can be overridden using the <option>-n</option> + command line option when starting the server. + </para> + <para> + The <option>lwres-clients</option> specifies + the number of client objects per thread the lightweight + resolver should create to serve client queries. + By default, if the lightweight resolver runs as a part + of <command>named</command>, 256 client objects are + created for each task; if it runs as <command>lwresd</command>, + 1024 client objects are created for each thread. The maximum + value is 32768; higher values will be silently ignored and + the maximum will be used instead. + Note that setting too high a value may overconsume + system resources. + </para> + <para> + The maximum number of client queries that the lightweight + resolver can handle at any one time equals + <option>lwres-tasks</option> times <option>lwres-clients</option>. + </para> + </section> + <section xml:id="masters_grammar"><info><title><command>masters</command> Statement Grammar</title></info> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="masters.grammar.xml"/> + </section> + + <section xml:id="masters_statement"><info><title><command>masters</command> Statement Definition and + Usage</title></info> + + <para><command>masters</command> + lists allow for a common set of masters to be easily used by + multiple stub and slave zones in their <command>masters</command> + or <command>also-notify</command> lists. + </para> + </section> + + <section xml:id="options_grammar"><info><title><command>options</command> Statement Grammar</title></info> + + <para> + This is the grammar of the <command>options</command> + statement in the <filename>named.conf</filename> file: + </para> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="options.grammar.xml"/> + </section> + + <section xml:id="options"><info><title><command>options</command> Statement Definition and + Usage</title></info> + + <para> + The <command>options</command> statement sets up global + options + to be used by <acronym>BIND</acronym>. This statement + may appear only + once in a configuration file. If there is no <command>options</command> + statement, an options block with each option set to its default will + be used. + </para> + + <variablelist> + + <varlistentry> + <term><command>attach-cache</command></term> + <listitem> + <para> + Allows multiple views to share a single cache + database. + Each view has its own cache database by default, but + if multiple views have the same operational policy + for name resolution and caching, those views can + share a single cache to save memory and possibly + improve resolution efficiency by using this option. + </para> + + <para> + The <command>attach-cache</command> option + may also be specified in <command>view</command> + statements, in which case it overrides the + global <command>attach-cache</command> option. + </para> + + <para> + The <replaceable>cache_name</replaceable> specifies + the cache to be shared. + When the <command>named</command> server configures + views which are supposed to share a cache, it + creates a cache with the specified name for the + first view of these sharing views. + The rest of the views will simply refer to the + already created cache. + </para> + + <para> + One common configuration to share a cache would be to + allow all views to share a single cache. + This can be done by specifying + the <command>attach-cache</command> as a global + option with an arbitrary name. + </para> + + <para> + Another possible operation is to allow a subset of + all views to share a cache while the others to + retain their own caches. + For example, if there are three views A, B, and C, + and only A and B should share a cache, specify the + <command>attach-cache</command> option as a view A (or + B)'s option, referring to the other view name: + </para> + +<programlisting> + view "A" { + // this view has its own cache + ... + }; + view "B" { + // this view refers to A's cache + attach-cache "A"; + }; + view "C" { + // this view has its own cache + ... + }; +</programlisting> + + <para> + Views that share a cache must have the same policy + on configurable parameters that may affect caching. + The current implementation requires the following + configurable options be consistent among these + views: + <command>check-names</command>, + <command>cleaning-interval</command>, + <command>dnssec-accept-expired</command>, + <command>dnssec-validation</command>, + <command>max-cache-ttl</command>, + <command>max-ncache-ttl</command>, + <command>max-cache-size</command>, and + <command>zero-no-soa-ttl</command>. + </para> + + <para> + Note that there may be other parameters that may + cause confusion if they are inconsistent for + different views that share a single cache. + For example, if these views define different sets of + forwarders that can return different answers for the + same question, sharing the answer does not make + sense or could even be harmful. + It is administrator's responsibility to ensure + configuration differences in different views do + not cause disruption with a shared cache. + </para> + </listitem> + + </varlistentry> + + <varlistentry> + <term><command>directory</command></term> + <listitem> + <para> + The working directory of the server. + Any non-absolute pathnames in the configuration file will + be taken as relative to this directory. The default + location for most server output files + (e.g. <filename>named.run</filename>) is this directory. + If a directory is not specified, the working directory + defaults to `<filename>.</filename>', the directory from + which the server was started. The directory specified + should be an absolute path. It is + <emphasis>strongly recommended</emphasis> + that the directory be writable by the effective user + ID of the <command>named</command> process. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>dnstap</command></term> + <listitem> + <para> + <command>dnstap</command> is a fast, flexible method + for capturing and logging DNS traffic. Developed by + Robert Edmonds at Farsight Security, Inc., and supported + by multiple DNS implementations, <command>dnstap</command> + uses + <command>libfstrm</command> (a lightweight high-speed + framing library, see + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://github.com/farsightsec/fstrm">https://github.com/farsightsec/fstrm</link>) to send + event payloads which are encoded using Protocol Buffers + (<command>libprotobuf-c</command>, a mechanism for + serializing structured data developed + by Google, Inc.; see + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://developers.google.com/protocol-buffers/">https://developers.google.com/protocol-buffers</link>). + </para> + <para> + To enable <command>dnstap</command> at compile time, + the <command>fstrm</command> and <command>protobuf-c</command> + libraries must be available, and BIND must be configured with + <option>--enable-dnstap</option>. + </para> + <para> + The <command>dnstap</command> option is a bracketed list + of message types to be logged. These may be set differently + for each view. Supported types are <literal>client</literal>, + <literal>auth</literal>, <literal>resolver</literal>, and + <literal>forwarder</literal>. Specifying type + <literal>all</literal> will cause all <command>dnstap</command> + messages to be logged, regardless of type. + </para> + <para> + Each type may take an additional argument to indicate whether + to log <literal>query</literal> messages or + <literal>response</literal> messages; if not specified, + both queries and responses are logged. + </para> + <para> + Example: To log all authoritative queries and responses, + recursive client responses, and upstream queries sent by + the resolver, use: +<programlisting>dnstap { + auth; + client response; + resolver query; +}; +</programlisting> + </para> + <para> + Logged <command>dnstap</command> messages can be parsed + using the <command>dnstap-read</command> utility (see + <xref linkend="man.dnstap-read"/> for details). + </para> + <para> + For more information on <command>dnstap</command>, see + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://dnstap.info">http://dnstap.info</link>. + </para> + <para> + The fstrm library has a number of tunables that are exposed + in <filename>named.conf</filename>, and can be modified + if necessary to improve performance or prevent loss of data. + These are: + </para> + <itemizedlist> + <listitem> + <simpara> + <command>fstrm-set-buffer-hint</command>: The + threshold number of bytes to accumulate in the output + buffer before forcing a buffer flush. The minimum is + 1024, the maximum is 65536, and the default is 8192. + </simpara> + </listitem> + <listitem> + <simpara> + <command>fstrm-set-flush-timeout</command>: The number + of seconds to allow unflushed data to remain in the + output buffer. The minimum is 1 second, the maximum is + 600 seconds (10 minutes), and the default is 1 second. + </simpara> + </listitem> + <listitem> + <simpara> + <command>fstrm-set-output-notify-threshold</command>: + The number of outstanding queue entries to allow on + an input queue before waking the I/O thread. + The minimum is 1 and the default is 32. + </simpara> + </listitem> + <listitem> + <simpara> + <command>fstrm-set-output-queue-model</command>: + Controls the queuing semantics to use for queue + objects. The default is <literal>mpsc</literal> + (multiple producer, single consumer); the other + option is <literal>spsc</literal> (single producer, + single consumer). + </simpara> + </listitem> + <listitem> + <simpara> + <command>fstrm-set-input-queue-size</command>: The + number of queue entries to allocate for each + input queue. This value must be a power of 2. + The minimum is 2, the maximum is 16384, and + the default is 512. + </simpara> + </listitem> + <listitem> + <simpara> + <command>fstrm-set-output-queue-size</command>: + The number of queue entries to allocate for each + output queue. The minimum is 2, the maximum is + system-dependent and based on <option>IOV_MAX</option>, + and the default is 64. + </simpara> + </listitem> + <listitem> + <simpara> + <command>fstrm-set-reopen-interval</command>: + The number of seconds to wait between attempts to + reopen a closed output stream. The minimum is 1 second, + the maximum is 600 seconds (10 minutes), and the default + is 5 seconds. + </simpara> + </listitem> + </itemizedlist> + <para> + Note that all of the above minimum, maximum, and default + values are set by the <command>libfstrm</command> library, + and may be subject to change in future versions of the + library. See the <command>libfstrm</command> documentation + for more information. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>dnstap-output</command></term> + <listitem> + <para> + Configures the path to which the <command>dnstap</command> + frame stream will be sent if <command>dnstap</command> + is enabled at compile time and active. + </para> + <para> + The first argument is either <literal>file</literal> or + <literal>unix</literal>, indicating whether the destination + is a file or a UNIX domain socket. The second argument + is the path of the file or socket. (Note: when using a + socket, <command>dnstap</command> messages will + only be sent if another process such as + <command>fstrm_capture</command> + (provided with <command>libfstrm</command>) is listening on + the socket.) + </para> + <para> + <command>dnstap-output</command> can only be set globally + in <command>options</command>. Currently, it can only be + set once while <command>named</command> is running; + once set, it cannot be changed by + <command>rndc reload</command> or + <command>rndc reconfig</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>dnstap-identity</command></term> + <listitem> + <para> + Specifies an <command>identity</command> string to send in + <command>dnstap</command> messages. If set to + <literal>hostname</literal>, which is the default, the + server's hostname will be sent. If set to + <literal>none</literal>, no identity string will be sent. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>dnstap-version</command></term> + <listitem> + <para> + Specifies a <command>version</command> string to send in + <command>dnstap</command> messages. The default is the + version number of the BIND release. If set to + <literal>none</literal>, no version string will be sent. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>geoip-directory</command></term> + <listitem> + <para> + Specifies the directory containing GeoIP + <filename>.dat</filename> database files for GeoIP + initialization. By default, this option is unset + and the GeoIP support will use libGeoIP's + built-in directory. + (For details, see <xref linkend="acl"/> about the + <command>geoip</command> ACL.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>key-directory</command></term> + <listitem> + <para> + When performing dynamic update of secure zones, the + directory where the public and private DNSSEC key files + should be found, if different than the current working + directory. (Note that this option has no effect on the + paths for files containing non-DNSSEC keys such as + <filename>bind.keys</filename>, + <filename>rndc.key</filename> or + <filename>session.key</filename>.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>lmdb-mapsize</command></term> + <listitem> + <para> + When <command>named</command> is built with liblmdb, + this option sets a maximum size for the memory map of + the new-zone database (NZD) in LMDB database format. + This database is used to store configuration information + for zones added using <command>rndc addzone</command>. + Note that this is not the NZD database file size, but + the largest size that the database may grow to. + </para> + <para> + Because the database file is memory mapped, its size is + limited by the address space of the named process. The + default of 32 megabytes was chosen to be usable with + 32-bit <command>named</command> builds. The largest + permitted value is 1 terabyte. Given typical zone + configurations without elaborate ACLs, a 32 MB NZD file + ought to be able to hold configurations of about 100,000 + zones. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>managed-keys-directory</command></term> + <listitem> + <para> + Specifies the directory in which to store the files that + track managed DNSSEC keys. By default, this is the working + directory. The directory <emphasis>must</emphasis> + be writable by the effective user ID of the + <command>named</command> process. + </para> + <para> + If <command>named</command> is not configured to use views, + then managed keys for the server will be tracked in a single + file called <filename>managed-keys.bind</filename>. + Otherwise, managed keys will be tracked in separate files, + one file per view; each file name will be the view name + (or, if it contains characters that are incompatible with + use as a file name, the SHA256 hash of the view name), + followed by the extension + <filename>.mkeys</filename>. + </para> + <para> + (Note: in previous releases, file names for views + always used the SHA256 hash of the view name. To ensure + compatibility after upgrade, if a file using the old + name format is found to exist, it will be used instead + of the new format.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>named-xfer</command></term> + <listitem> + <para> + <emphasis>This option is obsolete.</emphasis> It + was used in <acronym>BIND</acronym> 8 to specify + the pathname to the <command>named-xfer</command> + program. In <acronym>BIND</acronym> 9, no separate + <command>named-xfer</command> program is needed; + its functionality is built into the name server. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>tkey-gssapi-keytab</command></term> + <listitem> + <para> + The KRB5 keytab file to use for GSS-TSIG updates. If + this option is set and tkey-gssapi-credential is not + set, then updates will be allowed with any key + matching a principal in the specified keytab. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>tkey-gssapi-credential</command></term> + <listitem> + <para> + The security credential with which the server should + authenticate keys requested by the GSS-TSIG protocol. + Currently only Kerberos 5 authentication is available + and the credential is a Kerberos principal which the + server can acquire through the default system key + file, normally <filename>/etc/krb5.keytab</filename>. + The location keytab file can be overridden using the + tkey-gssapi-keytab option. Normally this principal is + of the form "<userinput>DNS/</userinput><varname>server.domain</varname>". + To use GSS-TSIG, <command>tkey-domain</command> must + also be set if a specific keytab is not set with + tkey-gssapi-keytab. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>tkey-domain</command></term> + <listitem> + <para> + The domain appended to the names of all shared keys + generated with <command>TKEY</command>. When a + client requests a <command>TKEY</command> exchange, + it may or may not specify the desired name for the + key. If present, the name of the shared key will + be <varname>client specified part</varname> + + <varname>tkey-domain</varname>. Otherwise, the + name of the shared key will be <varname>random hex + digits</varname> + <varname>tkey-domain</varname>. + In most cases, the <command>domainname</command> + should be the server's domain name, or an otherwise + non-existent subdomain like + "_tkey.<varname>domainname</varname>". If you are + using GSS-TSIG, this variable must be defined, unless + you specify a specific keytab using tkey-gssapi-keytab. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>tkey-dhkey</command></term> + <listitem> + <para> + The Diffie-Hellman key used by the server + to generate shared keys with clients using the Diffie-Hellman + mode + of <command>TKEY</command>. The server must be + able to load the + public and private keys from files in the working directory. + In + most cases, the <varname>key_name</varname> should be the server's host name. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>cache-file</command></term> + <listitem> + <para> + This is for testing only. Do not use. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>dump-file</command></term> + <listitem> + <para> + The pathname of the file the server dumps + the database to when instructed to do so with + <command>rndc dumpdb</command>. + If not specified, the default is <filename>named_dump.db</filename>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>memstatistics-file</command></term> + <listitem> + <para> + The pathname of the file the server writes memory + usage statistics to on exit. If not specified, + the default is <filename>named.memstats</filename>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>lock-file</command></term> + <listitem> + <para> + The pathname of a file on which <command>named</command> will + attempt to acquire a file lock when starting up for + the first time; if unsuccessful, the server will + will terminate, under the assumption that another + server is already running. If not specified, the default is + <filename>/var/run/named/named.lock</filename>. + </para> + <para> + Specifying <command>lock-file none</command> disables the + use of a lock file. <command>lock-file</command> is + ignored if <command>named</command> was run using the <option>-X</option> + option, which overrides it. Changes to + <command>lock-file</command> are ignored if + <command>named</command> is being reloaded or + reconfigured; it is only effective when the server is + first started up. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>pid-file</command></term> + <listitem> + <para> + The pathname of the file the server writes its process ID + in. If not specified, the default is + <filename>/var/run/named/named.pid</filename>. + The PID file is used by programs that want to send signals to + the running + name server. Specifying <command>pid-file none</command> disables the + use of a PID file — no file will be written and any + existing one will be removed. Note that <command>none</command> + is a keyword, not a filename, and therefore is not enclosed + in + double quotes. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>recursing-file</command></term> + <listitem> + <para> + The pathname of the file the server dumps + the queries that are currently recursing when instructed + to do so with <command>rndc recursing</command>. + If not specified, the default is <filename>named.recursing</filename>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>statistics-file</command></term> + <listitem> + <para> + The pathname of the file the server appends statistics + to when instructed to do so using <command>rndc stats</command>. + If not specified, the default is <filename>named.stats</filename> in the + server's current directory. The format of the file is + described + in <xref linkend="statsfile"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>bindkeys-file</command></term> + <listitem> + <para> + The pathname of a file to override the built-in trusted + keys provided by <command>named</command>. + See the discussion of <command>dnssec-validation</command> + for details. If not specified, the default is + <filename>/etc/bind.keys</filename>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>secroots-file</command></term> + <listitem> + <para> + The pathname of the file the server dumps + security roots to when instructed to do so with + <command>rndc secroots</command>. + If not specified, the default is + <filename>named.secroots</filename>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>session-keyfile</command></term> + <listitem> + <para> + The pathname of the file into which to write a TSIG + session key generated by <command>named</command> for use by + <command>nsupdate -l</command>. If not specified, the + default is <filename>/var/run/named/session.key</filename>. + (See <xref linkend="dynamic_update_policies"/>, and in + particular the discussion of the + <command>update-policy</command> statement's + <userinput>local</userinput> option for more + information about this feature.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>session-keyname</command></term> + <listitem> + <para> + The key name to use for the TSIG session key. + If not specified, the default is "local-ddns". + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>session-keyalg</command></term> + <listitem> + <para> + The algorithm to use for the TSIG session key. + Valid values are hmac-sha1, hmac-sha224, hmac-sha256, + hmac-sha384, hmac-sha512 and hmac-md5. If not + specified, the default is hmac-sha256. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>port</command></term> + <listitem> + <para> + The UDP/TCP port number the server uses for + receiving and sending DNS protocol traffic. + The default is 53. This option is mainly intended for server + testing; + a server using a port other than 53 will not be able to + communicate with + the global DNS. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>dscp</command></term> + <listitem> + <para> + The global Differentiated Services Code Point (DSCP) + value to classify outgoing DNS traffic on operating + systems that support DSCP. Valid values are 0 through 63. + It is not configured by default. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>random-device</command></term> + <listitem> + <para> + The source of entropy to be used by the server. Entropy is + primarily needed + for DNSSEC operations, such as TKEY transactions and dynamic + update of signed + zones. This options specifies the device (or file) from which + to read + entropy. If this is a file, operations requiring entropy will + fail when the + file has been exhausted. If not specified, the default value + is + <filename>/dev/random</filename> + (or equivalent) when present, and none otherwise. The + <command>random-device</command> option takes + effect during + the initial configuration load at server startup time and + is ignored on subsequent reloads. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>preferred-glue</command></term> + <listitem> + <para> + If specified, the listed type (A or AAAA) will be emitted + before other glue + in the additional section of a query response. + The default is to prefer A records when responding + to queries that arrived via IPv4 and AAAA when + responding to queries that arrived via IPv6. + </para> + </listitem> + </varlistentry> + + <varlistentry xml:id="root_delegation_only"> + <term><command>root-delegation-only</command></term> + <listitem> + <para> + Turn on enforcement of delegation-only in TLDs + (top level domains) and root zones with an optional + exclude list. + </para> + <para> + DS queries are expected to be made to and be answered by + delegation only zones. Such queries and responses are + treated as an exception to delegation-only processing + and are not converted to NXDOMAIN responses provided + a CNAME is not discovered at the query name. + </para> + <para> + If a delegation only zone server also serves a child + zone it is not always possible to determine whether + an answer comes from the delegation only zone or the + child zone. SOA NS and DNSKEY records are apex + only records and a matching response that contains + these records or DS is treated as coming from a + child zone. RRSIG records are also examined to see + if they are signed by a child zone or not. The + authority section is also examined to see if there + is evidence that the answer is from the child zone. + Answers that are determined to be from a child zone + are not converted to NXDOMAIN responses. Despite + all these checks there is still a possibility of + false negatives when a child zone is being served. + </para> + <para> + Similarly false positives can arise from empty nodes + (no records at the name) in the delegation only zone + when the query type is not ANY. + </para> + <para> + Note some TLDs are not delegation only (e.g. "DE", "LV", + "US" and "MUSEUM"). This list is not exhaustive. + </para> + +<programlisting> +options { + root-delegation-only exclude { "de"; "lv"; "us"; "museum"; }; +}; +</programlisting> + + </listitem> + </varlistentry> + + <varlistentry> + <term><command>disable-algorithms</command></term> + <listitem> + <para> + Disable the specified DNSSEC algorithms at and below the + specified name. + Multiple <command>disable-algorithms</command> + statements are allowed. + Only the best match <command>disable-algorithms</command> + clause will be used to determine which algorithms are used. + </para> + <para> + If all supported algorithms are disabled, the zones covered + by the <command>disable-algorithms</command> will be treated + as insecure. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>disable-ds-digests</command></term> + <listitem> + <para> + Disable the specified DS/DLV digest types at and below the + specified name. + Multiple <command>disable-ds-digests</command> + statements are allowed. + Only the best match <command>disable-ds-digests</command> + clause will be used to determine which digest types are used. + </para> + <para> + If all supported digest types are disabled, the zones covered + by the <command>disable-ds-digests</command> will be treated + as insecure. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>dnssec-lookaside</command></term> + <listitem> + <para> + When set, <command>dnssec-lookaside</command> provides the + validator with an alternate method to validate DNSKEY + records at the top of a zone. When a DNSKEY is at or + below a domain specified by the deepest + <command>dnssec-lookaside</command>, and the normal DNSSEC + validation has left the key untrusted, the trust-anchor + will be appended to the key name and a DLV record will be + looked up to see if it can validate the key. If the DLV + record validates a DNSKEY (similarly to the way a DS + record does) the DNSKEY RRset is deemed to be trusted. + </para> + <para> + If <command>dnssec-lookaside</command> is set to + <userinput>no</userinput>, then dnssec-lookaside + is not used. + </para> + <para> + NOTE: The ISC-provided DLV service at + <literal>dlv.isc.org</literal>, has been shut down. + The <command>dnssec-lookaside auto;</command> + configuration option, which set <command>named</command> + up to use ISC DLV with minimal configuration, has + accordingly been removed. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>dnssec-must-be-secure</command></term> + <listitem> + <para> + Specify hierarchies which must be or may not be secure + (signed and validated). If <userinput>yes</userinput>, + then <command>named</command> will only accept answers if + they are secure. If <userinput>no</userinput>, then normal + DNSSEC validation applies allowing for insecure answers to + be accepted. The specified domain must be under a + <command>trusted-keys</command> or + <command>managed-keys</command> statement, or + <command>dnssec-validation auto</command> must be active. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>dns64</command></term> + <listitem> + <para> + This directive instructs <command>named</command> to + return mapped IPv4 addresses to AAAA queries when + there are no AAAA records. It is intended to be + used in conjunction with a NAT64. Each + <command>dns64</command> defines one DNS64 prefix. + Multiple DNS64 prefixes can be defined. + </para> + <para> + Compatible IPv6 prefixes have lengths of 32, 40, 48, 56, + 64 and 96 as per RFC 6052. + </para> + <para> + Additionally a reverse IP6.ARPA zone will be created for + the prefix to provide a mapping from the IP6.ARPA names + to the corresponding IN-ADDR.ARPA names using synthesized + CNAMEs. <command>dns64-server</command> and + <command>dns64-contact</command> can be used to specify + the name of the server and contact for the zones. These + are settable at the view / options level. These are + not settable on a per-prefix basis. + </para> + <para> + Each <command>dns64</command> supports an optional + <command>clients</command> ACL that determines which + clients are affected by this directive. If not defined, + it defaults to <userinput>any;</userinput>. + </para> + <para> + Each <command>dns64</command> supports an optional + <command>mapped</command> ACL that selects which + IPv4 addresses are to be mapped in the corresponding + A RRset. If not defined it defaults to + <userinput>any;</userinput>. + </para> + <para> + Normally, DNS64 won't apply to a domain name that + owns one or more AAAA records; these records will + simply be returned. The optional + <command>exclude</command> ACL allows specification + of a list of IPv6 addresses that will be ignored + if they appear in a domain name's AAAA records, and + DNS64 will be applied to any A records the domain + name owns. If not defined, <command>exclude</command> + defaults to ::ffff:0.0.0.0/96. + </para> + <para> + A optional <command>suffix</command> can also + be defined to set the bits trailing the mapped + IPv4 address bits. By default these bits are + set to <userinput>::</userinput>. The bits + matching the prefix and mapped IPv4 address + must be zero. + </para> + <para> + If <command>recursive-only</command> is set to + <command>yes</command> the DNS64 synthesis will + only happen for recursive queries. The default + is <command>no</command>. + </para> + <para> + If <command>break-dnssec</command> is set to + <command>yes</command> the DNS64 synthesis will + happen even if the result, if validated, would + cause a DNSSEC validation failure. If this option + is set to <command>no</command> (the default), the DO + is set on the incoming query, and there are RRSIGs on + the applicable records, then synthesis will not happen. + </para> +<programlisting> + acl rfc1918 { 10/8; 192.168/16; 172.16/12; }; + + dns64 64:FF9B::/96 { + clients { any; }; + mapped { !rfc1918; any; }; + exclude { 64:FF9B::/96; ::ffff:0000:0000/96; }; + suffix ::; + }; +</programlisting> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>dnssec-loadkeys-interval</command></term> + <listitem> + <para> + When a zone is configured with <command>auto-dnssec + maintain;</command> its key repository must be checked + periodically to see if any new keys have been added + or any existing keys' timing metadata has been updated + (see <xref linkend="man.dnssec-keygen"/> and + <xref linkend="man.dnssec-settime"/>). The + <command>dnssec-loadkeys-interval</command> option + sets the frequency of automatic repository checks, in + minutes. The default is <literal>60</literal> (1 hour), + the minimum is <literal>1</literal> (1 minute), and the + maximum is <literal>1440</literal> (24 hours); any higher + value is silently reduced. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>dnssec-update-mode</command></term> + <listitem> + <para> + If this option is set to its default value of + <literal>maintain</literal> in a zone of type + <literal>master</literal> which is DNSSEC-signed + and configured to allow dynamic updates (see + <xref linkend="dynamic_update_policies"/>), and + if <command>named</command> has access to the + private signing key(s) for the zone, then + <command>named</command> will automatically sign all new + or changed records and maintain signatures for the zone + by regenerating RRSIG records whenever they approach + their expiration date. + </para> + <para> + If the option is changed to <literal>no-resign</literal>, + then <command>named</command> will sign all new or + changed records, but scheduled maintenance of + signatures is disabled. + </para> + <para> + With either of these settings, <command>named</command> + will reject updates to a DNSSEC-signed zone when the + signing keys are inactive or unavailable to + <command>named</command>. (A planned third option, + <literal>external</literal>, will disable all automatic + signing and allow DNSSEC data to be submitted into a zone + via dynamic update; this is not yet implemented.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>nta-lifetime</command></term> + <listitem> + <para> + Species the default lifetime, in seconds, + that will be used for negative trust anchors added + via <command>rndc nta</command>. + </para> + <para> + A negative trust anchor selectively disables + DNSSEC validation for zones that are known to be + failing because of misconfiguration rather than + an attack. When data to be validated is + at or below an active NTA (and above any other + configured trust anchors), <command>named</command> will + abort the DNSSEC validation process and treat the data as + insecure rather than bogus. This continues until the + NTA's lifetime is elapsed. NTAs persist + across <command>named</command> restarts. + </para> + <para> + For convenience, TTL-style time unit suffixes can be + used to specify the NTA lifetime in seconds, minutes + or hours. <option>nta-lifetime</option> defaults to + one hour. It cannot exceed one week. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>nta-recheck</command></term> + <listitem> + <para> + Species how often to check whether negative + trust anchors added via <command>rndc nta</command> + are still necessary. + </para> + <para> + A negative trust anchor is normally used when a + domain has stopped validating due to operator error; + it temporarily disables DNSSEC validation for that + domain. In the interest of ensuring that DNSSEC + validation is turned back on as soon as possible, + <command>named</command> will periodically send a + query to the domain, ignoring negative trust anchors, + to find out whether it can now be validated. If so, + the negative trust anchor is allowed to expire early. + </para> + <para> + Validity checks can be disabled for an individual + NTA by using <command>rndc nta -f</command>, or + for all NTAs by setting <option>nta-recheck</option> + to zero. + </para> + <para> + For convenience, TTL-style time unit suffixes can be + used to specify the NTA recheck interval in seconds, + minutes or hours. The default is five minutes. It + cannot be longer than <option>nta-lifetime</option> + (which cannot be longer than a week). + </para> + </listitem> + </varlistentry> + + + <varlistentry> + <term><command>max-zone-ttl</command></term> + <listitem> + <para> + Specifies a maximum permissible TTL value in seconds. + For convenience, TTL-style time unit suffixes may be + used to specify the maximum value. + When loading a zone file using a + <option>masterfile-format</option> of + <constant>text</constant> or <constant>raw</constant>, + any record encountered with a TTL higher than + <option>max-zone-ttl</option> will cause the zone to + be rejected. + </para> + <para> + This is useful in DNSSEC-signed zones because when + rolling to a new DNSKEY, the old key needs to remain + available until RRSIG records have expired from + caches. The <option>max-zone-ttl</option> option guarantees + that the largest TTL in the zone will be no higher + than the set value. + </para> + <para> + (NOTE: Because <constant>map</constant>-format files + load directly into memory, this option cannot be + used with them.) + </para> + <para> + The default value is <constant>unlimited</constant>. + A <option>max-zone-ttl</option> of zero is treated as + <constant>unlimited</constant>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>serial-update-method</command></term> + <listitem> + <para> + Zones configured for dynamic DNS may use this + option to set the update method that will be used for + the zone serial number in the SOA record. + </para> + <para> + With the default setting of + <command>serial-update-method increment;</command>, the + SOA serial number will be incremented by one each time + the zone is updated. + </para> + <para> + When set to + <command>serial-update-method unixtime;</command>, the + SOA serial number will be set to the number of seconds + since the UNIX epoch, unless the serial number is + already greater than or equal to that value, in which + case it is simply incremented by one. + </para> + <para> + When set to + <command>serial-update-method date;</command>, the + new SOA serial number will be the current date + in the form "YYYYMMDD", followed by two zeroes, + unless the existing serial number is already greater + than or equal to that value, in which case it is + incremented by one. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>zone-statistics</command></term> + <listitem> + <para> + If <userinput>full</userinput>, the server will collect + statistical data on all zones (unless specifically + turned off on a per-zone basis by specifying + <command>zone-statistics terse</command> or + <command>zone-statistics none</command> + in the <command>zone</command> statement). + The default is <userinput>terse</userinput>, providing + minimal statistics on zones (including name and + current serial number, but not query type + counters). + </para> + <para> + These statistics may be accessed via the + <command>statistics-channel</command> or + using <command>rndc stats</command>, which + will dump them to the file listed + in the <command>statistics-file</command>. See + also <xref linkend="statsfile"/>. + </para> + <para> + For backward compatibility with earlier versions + of BIND 9, the <command>zone-statistics</command> + option can also accept <userinput>yes</userinput> + or <userinput>no</userinput>; <userinput>yes</userinput> + has the same meaning as <userinput>full</userinput>. + As of <acronym>BIND</acronym> 9.10, + <userinput>no</userinput> has the same meaning + as <userinput>none</userinput>; previously, it + was the same as <userinput>terse</userinput>. + </para> + </listitem> + </varlistentry> + </variablelist> + + <section xml:id="boolean_options"><info><title>Boolean Options</title></info> + + <variablelist> + + <varlistentry> + <term><command>automatic-interface-scan</command></term> + <listitem> + <para> + If <userinput>yes</userinput> and supported by the OS, + automatically rescan network interfaces when the interface + addresses are added or removed. The default is + <userinput>yes</userinput>. + </para> + <para> + Currently the OS needs to support routing sockets for + <command>automatic-interface-scan</command> to be + supported. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>allow-new-zones</command></term> + <listitem> + <para> + If <userinput>yes</userinput>, then zones can be + added at runtime via <command>rndc addzone</command>. + The default is <userinput>no</userinput>. + </para> + <para> + Newly added zones' configuration parameters + are stored so that they can persist after the + server is restarted. The configuration information + is saved in a file called + <filename><replaceable>viewname</replaceable>.nzf</filename> + (or, if <command>named</command> is compiled with + liblmdb, in an LMDB database file called + <filename><replaceable>viewname</replaceable>.nzd</filename>). + <replaceable>viewname</replaceable> is the name of the + view, unless the view name contains characters that are + incompatible with use as a file name, in which case a + cryptographic hash of the view name is used instead. + </para> + <para> + Zones added at runtime will have their configuration + stored either in a new-zone file (NZF) or a new-zone + database (NZD) depending on whether + <command>named</command> was linked with + liblmdb at compile time. + See <xref linkend="man.rndc"/> for further details + about <command>rndc addzone</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>auth-nxdomain</command></term> + <listitem> + <para> + If <userinput>yes</userinput>, then the <command>AA</command> bit + is always set on NXDOMAIN responses, even if the server is + not actually + authoritative. The default is <userinput>no</userinput>; + this is + a change from <acronym>BIND</acronym> 8. If you + are using very old DNS software, you + may need to set it to <userinput>yes</userinput>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>deallocate-on-exit</command></term> + <listitem> + <para> + This option was used in <acronym>BIND</acronym> + 8 to enable checking + for memory leaks on exit. <acronym>BIND</acronym> 9 ignores the option and always performs + the checks. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>memstatistics</command></term> + <listitem> + <para> + Write memory statistics to the file specified by + <command>memstatistics-file</command> at exit. + The default is <userinput>no</userinput> unless + '-m record' is specified on the command line in + which case it is <userinput>yes</userinput>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>dialup</command></term> + <listitem> + <para> + If <userinput>yes</userinput>, then the + server treats all zones as if they are doing zone transfers + across + a dial-on-demand dialup link, which can be brought up by + traffic + originating from this server. This has different effects + according + to zone type and concentrates the zone maintenance so that + it all + happens in a short interval, once every <command>heartbeat-interval</command> and + hopefully during the one call. It also suppresses some of + the normal + zone maintenance traffic. The default is <userinput>no</userinput>. + </para> + <para> + The <command>dialup</command> option + may also be specified in the <command>view</command> and + <command>zone</command> statements, + in which case it overrides the global <command>dialup</command> + option. + </para> + <para> + If the zone is a master zone, then the server will send out a + NOTIFY + request to all the slaves (default). This should trigger the + zone serial + number check in the slave (providing it supports NOTIFY) + allowing the slave + to verify the zone while the connection is active. + The set of servers to which NOTIFY is sent can be controlled + by + <command>notify</command> and <command>also-notify</command>. + </para> + <para> + If the + zone is a slave or stub zone, then the server will suppress + the regular + "zone up to date" (refresh) queries and only perform them + when the + <command>heartbeat-interval</command> expires in + addition to sending + NOTIFY requests. + </para> + <para> + Finer control can be achieved by using + <userinput>notify</userinput> which only sends NOTIFY + messages, + <userinput>notify-passive</userinput> which sends NOTIFY + messages and + suppresses the normal refresh queries, <userinput>refresh</userinput> + which suppresses normal refresh processing and sends refresh + queries + when the <command>heartbeat-interval</command> + expires, and + <userinput>passive</userinput> which just disables normal + refresh + processing. + </para> + + <informaltable colsep="0" rowsep="0"> + <tgroup cols="4" colsep="0" rowsep="0" tgroupstyle="4Level-table"> + <colspec colname="1" colnum="1" colsep="0" colwidth="1.150in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="1.150in"/> + <colspec colname="3" colnum="3" colsep="0" colwidth="1.150in"/> + <colspec colname="4" colnum="4" colsep="0" colwidth="1.150in"/> + <tbody> + <row rowsep="0"> + <entry colname="1"> + <para> + dialup mode + </para> + </entry> + <entry colname="2"> + <para> + normal refresh + </para> + </entry> + <entry colname="3"> + <para> + heart-beat refresh + </para> + </entry> + <entry colname="4"> + <para> + heart-beat notify + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>no</command> (default)</para> + </entry> + <entry colname="2"> + <para> + yes + </para> + </entry> + <entry colname="3"> + <para> + no + </para> + </entry> + <entry colname="4"> + <para> + no + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>yes</command></para> + </entry> + <entry colname="2"> + <para> + no + </para> + </entry> + <entry colname="3"> + <para> + yes + </para> + </entry> + <entry colname="4"> + <para> + yes + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>notify</command></para> + </entry> + <entry colname="2"> + <para> + yes + </para> + </entry> + <entry colname="3"> + <para> + no + </para> + </entry> + <entry colname="4"> + <para> + yes + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>refresh</command></para> + </entry> + <entry colname="2"> + <para> + no + </para> + </entry> + <entry colname="3"> + <para> + yes + </para> + </entry> + <entry colname="4"> + <para> + no + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>passive</command></para> + </entry> + <entry colname="2"> + <para> + no + </para> + </entry> + <entry colname="3"> + <para> + no + </para> + </entry> + <entry colname="4"> + <para> + no + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>notify-passive</command></para> + </entry> + <entry colname="2"> + <para> + no + </para> + </entry> + <entry colname="3"> + <para> + no + </para> + </entry> + <entry colname="4"> + <para> + yes + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para> + Note that normal NOTIFY processing is not affected by + <command>dialup</command>. + </para> + + </listitem> + </varlistentry> + + <varlistentry> + <term><command>fake-iquery</command></term> + <listitem> + <para> + In <acronym>BIND</acronym> 8, this option + enabled simulating the obsolete DNS query type + IQUERY. <acronym>BIND</acronym> 9 never does + IQUERY simulation. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>fetch-glue</command></term> + <listitem> + <para> + This option is obsolete. + In BIND 8, <userinput>fetch-glue yes</userinput> + caused the server to attempt to fetch glue resource records + it + didn't have when constructing the additional + data section of a response. This is now considered a bad + idea + and BIND 9 never does it. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>flush-zones-on-shutdown</command></term> + <listitem> + <para> + When the nameserver exits due receiving SIGTERM, + flush or do not flush any pending zone writes. The default + is + <command>flush-zones-on-shutdown</command> <userinput>no</userinput>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>geoip-use-ecs</command></term> + <listitem> + <para> + When BIND is compiled with GeoIP support and configured + with "geoip" ACL elements, this option indicates whether + the EDNS Client Subnet option, if present in a request, + should be used for matching against the GeoIP database. + The default is + <command>geoip-use-ecs</command> <userinput>yes</userinput>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>has-old-clients</command></term> + <listitem> + <para> + This option was incorrectly implemented + in <acronym>BIND</acronym> 8, and is ignored by <acronym>BIND</acronym> 9. + To achieve the intended effect + of + <command>has-old-clients</command> <userinput>yes</userinput>, specify + the two separate options <command>auth-nxdomain</command> <userinput>yes</userinput> + and <command>rfc2308-type1</command> <userinput>no</userinput> instead. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>host-statistics</command></term> + <listitem> + <para> + In BIND 8, this enabled keeping of + statistics for every host that the name server interacts + with. + Not implemented in BIND 9. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>root-key-sentinel</command></term> + <listitem> + <para> + Respond to root key sentinel probes as described in + draft-ietf-dnsop-kskroll-sentinel-08. The default is + <userinput>yes</userinput>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>maintain-ixfr-base</command></term> + <listitem> + <para> + <emphasis>This option is obsolete</emphasis>. + It was used in <acronym>BIND</acronym> 8 to + determine whether a transaction log was + kept for Incremental Zone Transfer. <acronym>BIND</acronym> 9 maintains a transaction + log whenever possible. If you need to disable outgoing + incremental zone + transfers, use <command>provide-ixfr</command> <userinput>no</userinput>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>message-compression</command></term> <listitem> + <para> + If <userinput>yes</userinput>, DNS name compression is + used in responses to regular queries (not including + AXFR or IXFR, which always uses compression). Setting + this option to <userinput>no</userinput> reduces CPU + usage on servers and may improve throughput. However, + it increases response size, which may cause more queries + to be processed using TCP; a server with compression + disabled is out of compliance with RFC 1123 Section + 6.1.3.2. The default is <userinput>yes</userinput>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>minimal-responses</command></term> + <listitem> + <para> + If set to <userinput>yes</userinput>, then when generating + responses the server will only add records to the authority + and additional data sections when they are required (e.g. + delegations, negative responses). This may improve the + performance of the server. + </para> + <para> + When set to <userinput>no-auth</userinput>, the + server will omit records from the authority section + unless they are required, but it may still add + records to the additional section. When set to + <userinput>no-auth-recursive</userinput>, this + is only done if the query is recursive. These + settings are useful when answering stub clients, + which usually ignore the authority section. + <userinput>no-auth-recursive</userinput> is + designed for mixed-mode servers which handle + both authoritative and recursive queries. + </para> + <para> + The default is <userinput>no</userinput>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>minimal-any</command></term> + <listitem> + <para> + If set to <userinput>yes</userinput>, then when + generating a positive response to a query of type + ANY over UDP, the server will reply with only one + of the RRsets for the query name, and its covering + RRSIGs if any, instead of replying with all known + RRsets for the name. Similarly, a query for type + RRSIG will be answered with the RRSIG records covering + only one type. This can reduce the impact of some kinds + of attack traffic, without harming legitimate + clients. (Note, however, that the RRset returned is the + first one found in the database; it is not necessarily + the smallest available RRset.) + Additionally, <option>minimal-responses</option> is + turned on for these queries, so no unnecessary records + will be added to the authority or additional sections. + The default is <userinput>no</userinput>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>multiple-cnames</command></term> + <listitem> + <para> + This option was used in <acronym>BIND</acronym> 8 to allow + a domain name to have multiple CNAME records in violation of + the DNS standards. <acronym>BIND</acronym> 9.2 onwards + always strictly enforces the CNAME rules both in master + files and dynamic updates. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>notify</command></term> + <listitem> + <para> + If <userinput>yes</userinput> (the default), + DNS NOTIFY messages are sent when a zone the server is + authoritative for + changes, see <xref linkend="notify"/>. The messages are + sent to the + servers listed in the zone's NS records (except the master + server identified + in the SOA MNAME field), and to any servers listed in the + <command>also-notify</command> option. + </para> + <para> + If <userinput>master-only</userinput>, notifies are only + sent + for master zones. + If <userinput>explicit</userinput>, notifies are sent only + to + servers explicitly listed using <command>also-notify</command>. + If <userinput>no</userinput>, no notifies are sent. + </para> + <para> + The <command>notify</command> option may also be + specified in the <command>zone</command> + statement, + in which case it overrides the <command>options notify</command> statement. + It would only be necessary to turn off this option if it + caused slaves + to crash. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>notify-to-soa</command></term> + <listitem> + <para> + If <userinput>yes</userinput> do not check the nameservers + in the NS RRset against the SOA MNAME. Normally a NOTIFY + message is not sent to the SOA MNAME (SOA ORIGIN) as it is + supposed to contain the name of the ultimate master. + Sometimes, however, a slave is listed as the SOA MNAME in + hidden master configurations and in that case you would + want the ultimate master to still send NOTIFY messages to + all the nameservers listed in the NS RRset. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>recursion</command></term> + <listitem> + <para> + If <userinput>yes</userinput>, and a + DNS query requests recursion, then the server will attempt + to do + all the work required to answer the query. If recursion is + off + and the server does not already know the answer, it will + return a + referral response. The default is + <userinput>yes</userinput>. + Note that setting <command>recursion no</command> does not prevent + clients from getting data from the server's cache; it only + prevents new data from being cached as an effect of client + queries. + Caching may still occur as an effect the server's internal + operation, such as NOTIFY address lookups. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>request-nsid</command></term> + <listitem> + <para> + If <userinput>yes</userinput>, then an empty EDNS(0) + NSID (Name Server Identifier) option is sent with all + queries to authoritative name servers during iterative + resolution. If the authoritative server returns an NSID + option in its response, then its contents are logged in + the <command>resolver</command> category at level + <command>info</command>. + The default is <userinput>no</userinput>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>request-sit</command></term> + <listitem> + <para> + This experimental option is obsolete. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>require-server-cookie</command></term> + <listitem> + <para> + Require a valid server cookie before sending a full + response to a UDP request from a cookie aware client. + BADCOOKIE is sent if there is a bad or no existent + server cookie. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>answer-cookie</command></term> + <listitem> + <para> + When set to the default value of <userinput>yes</userinput>, + COOKIE EDNS options will be sent when applicable in + replies to client queries. If set to + <userinput>no</userinput>, COOKIE EDNS options will not + be sent in replies. This can only be set at the global + options level, not per-view. + </para> + <para> + <command>answer-cookie no</command> is only intended as a + temporary measure, for use when <command>named</command> + shares an IP address with other servers that do not yet + support DNS COOKIE. A mismatch between servers on the + same address is not expected to cause operational + problems, but the option to disable COOKIE responses so + that all servers have the same behavior is provided out + of an abundance of caution. DNS COOKIE is an important + security mechanism, and should not be disabled unless + absolutely necessary. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>send-cookie</command></term> + <listitem> + <para> + If <userinput>yes</userinput>, then a COOKIE EDNS + option is sent along with the query. If the + resolver has previously talked to the server, the + COOKIE returned in the previous transaction is sent. + This is used by the server to determine whether + the resolver has talked to it before. A resolver + sending the correct COOKIE is assumed not to be an + off-path attacker sending a spoofed-source query; + the query is therefore unlikely to be part of a + reflection/amplification attack, so resolvers + sending a correct COOKIE option are not subject to + response rate limiting (RRL). Resolvers which + do not send a correct COOKIE option may be limited + to receiving smaller responses via the + <command>nocookie-udp-size</command> option. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>nocookie-udp-size</command></term> + <listitem> + <para> + Sets the maximum size of UDP responses that will be + sent to queries without a valid server COOKIE. A value + below 128 will be silently raised to 128. The default + value is 4096, but the <command>max-udp-size</command> + option may further limit the response size. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>sit-secret</command></term> + <listitem> + <para> + This experimental option is obsolete. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>cookie-algorithm</command></term> + <listitem> + <para> + Set the algorithm to be used when generating the + server cookie. One of "aes", "sha1" or "sha256". + The default is "aes" if supported by the cryptographic + library or otherwise "sha256". + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>cookie-secret</command></term> + <listitem> + <para> + If set, this is a shared secret used for generating + and verifying EDNS COOKIE options + within an anycast cluster. If not set, the system + will generate a random secret at startup. The + shared secret is encoded as a hex string and needs + to be 128 bits for AES128, 160 bits for SHA1 and + 256 bits for SHA256. + </para> + <para> + If there are multiple secrets specified, the first + one listed in <filename>named.conf</filename> is + used to generate new server cookies. The others + will only be used to verify returned cookies. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>rfc2308-type1</command></term> + <listitem> + <para> + Setting this to <userinput>yes</userinput> will + cause the server to send NS records along with the SOA + record for negative + answers. The default is <userinput>no</userinput>. + </para> + <note> + <simpara> + Not yet implemented in <acronym>BIND</acronym> + 9. + </simpara> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>trust-anchor-telemetry</command></term> + <listitem> + <para> + Causes <command>named</command> to send specially-formed + queries once per day to domains for which trust anchors + have been configured via <command>trusted-keys</command>, + <command>managed-keys</command>, or + <command>dnssec-validation auto</command>. + </para> + <para> + The query name used for these queries has the + form "_ta-xxxx(-xxxx)(...)".<domain>, where + each "xxxx" is a group of four hexadecimal digits + representing the key ID of a trusted DNSSEC key. + The key IDs for each domain are sorted smallest + to largest prior to encoding. The query type is NULL. + </para> + <para> + By monitoring these queries, zone operators will + be able to see which resolvers have been updated to + trust a new key; this may help them decide when it + is safe to remove an old one. + </para> + <para> + The default is <userinput>yes</userinput>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>use-id-pool</command></term> + <listitem> + <para> + <emphasis>This option is obsolete</emphasis>. + <acronym>BIND</acronym> 9 always allocates query + IDs from a pool. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>use-ixfr</command></term> + <listitem> + <para> + <emphasis>This option is obsolete</emphasis>. + If you need to disable IXFR to a particular server or + servers, see + the information on the <command>provide-ixfr</command> option + in <xref linkend="server_statement_definition_and_usage"/>. + See also + <xref linkend="incremental_zone_transfers"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>provide-ixfr</command></term> + <listitem> + <para> + See the description of + <command>provide-ixfr</command> in + <xref linkend="server_statement_definition_and_usage"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>request-ixfr</command></term> + <listitem> + <para> + See the description of + <command>request-ixfr</command> in + <xref linkend="server_statement_definition_and_usage"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>request-expire</command></term> + <listitem> + <para> + See the description of + <command>request-expire</command> in + <xref linkend="server_statement_definition_and_usage"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>treat-cr-as-space</command></term> + <listitem> + <para> + This option was used in <acronym>BIND</acronym> + 8 to make + the server treat carriage return ("<command>\r</command>") characters the same way + as a space or tab character, + to facilitate loading of zone files on a UNIX system that + were generated + on an NT or DOS machine. In <acronym>BIND</acronym> 9, both UNIX "<command>\n</command>" + and NT/DOS "<command>\r\n</command>" newlines + are always accepted, + and the option is ignored. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>additional-from-auth</command></term> + <term><command>additional-from-cache</command></term> + <listitem> + + <para> + These options control the behavior of an authoritative + server when + answering queries which have additional data, or when + following CNAME + and DNAME chains. + </para> + + <para> + When both of these options are set to <userinput>yes</userinput> + (the default) and a + query is being answered from authoritative data (a zone + configured into the server), the additional data section of + the + reply will be filled in using data from other authoritative + zones + and from the cache. In some situations this is undesirable, + such + as when there is concern over the correctness of the cache, + or + in servers where slave zones may be added and modified by + untrusted third parties. Also, avoiding + the search for this additional data will speed up server + operations + at the possible expense of additional queries to resolve + what would + otherwise be provided in the additional section. + </para> + + <para> + For example, if a query asks for an MX record for host <literal>foo.example.com</literal>, + and the record found is "<literal>MX 10 mail.example.net</literal>", normally the address + records (A and AAAA) for <literal>mail.example.net</literal> will be provided as well, + if known, even though they are not in the example.com zone. + Setting these options to <command>no</command> + disables this behavior and makes + the server only search for additional data in the zone it + answers from. + </para> + + <para> + These options are intended for use in authoritative-only + servers, or in authoritative-only views. Attempts to set + them to <command>no</command> without also + specifying + <command>recursion no</command> will cause the + server to + ignore the options and log a warning message. + </para> + + <para> + Specifying <command>additional-from-cache no</command> actually + disables the use of the cache not only for additional data + lookups + but also when looking up the answer. This is usually the + desired + behavior in an authoritative-only server where the + correctness of + the cached data is an issue. + </para> + + <para> + When a name server is non-recursively queried for a name + that is not + below the apex of any served zone, it normally answers with + an + "upwards referral" to the root servers or the servers of + some other + known parent of the query name. Since the data in an + upwards referral + comes from the cache, the server will not be able to provide + upwards + referrals when <command>additional-from-cache no</command> + has been specified. Instead, it will respond to such + queries + with REFUSED. This should not cause any problems since + upwards referrals are not required for the resolution + process. + </para> + + </listitem> + </varlistentry> + + <varlistentry> + <term><command>match-mapped-addresses</command></term> + <listitem> + <para> + If <userinput>yes</userinput>, then an + IPv4-mapped IPv6 address will match any address match + list entries that match the corresponding IPv4 address. + </para> + <para> + This option was introduced to work around a kernel quirk + in some operating systems that causes IPv4 TCP + connections, such as zone transfers, to be accepted on an + IPv6 socket using mapped addresses. This caused address + match lists designed for IPv4 to fail to match. However, + <command>named</command> now solves this problem + internally. The use of this option is discouraged. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>filter-aaaa-on-v4</command></term> + <listitem> + <para> + This option is only available when + <acronym>BIND</acronym> 9 is compiled with the + <userinput>--enable-filter-aaaa</userinput> option on the + "configure" command line. It is intended to help the + transition from IPv4 to IPv6 by not giving IPv6 addresses + to DNS clients unless they have connections to the IPv6 + Internet. This is not recommended unless absolutely + necessary. The default is <userinput>no</userinput>. + The <command>filter-aaaa-on-v4</command> option + may also be specified in <command>view</command> statements + to override the global <command>filter-aaaa-on-v4</command> + option. + </para> + <para> + If <userinput>yes</userinput>, + the DNS client is at an IPv4 address, in <command>filter-aaaa</command>, + and if the response does not include DNSSEC signatures, + then all AAAA records are deleted from the response. + This filtering applies to all responses and not only + authoritative responses. + </para> + <para> + If <userinput>break-dnssec</userinput>, + then AAAA records are deleted even when DNSSEC is enabled. + As suggested by the name, this makes the response not verify, + because the DNSSEC protocol is designed detect deletions. + </para> + <para> + This mechanism can erroneously cause other servers to + not give AAAA records to their clients. + A recursing server with both IPv6 and IPv4 network connections + that queries an authoritative server using this mechanism + via IPv4 will be denied AAAA records even if its client is + using IPv6. + </para> + <para> + This mechanism is applied to authoritative as well as + non-authoritative records. + A client using IPv4 that is not allowed recursion can + erroneously be given AAAA records because the server is not + allowed to check for A records. + </para> + <para> + Some AAAA records are given to IPv4 clients in glue records. + IPv4 clients that are servers can then erroneously + answer requests for AAAA records received via IPv4. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>filter-aaaa-on-v6</command></term> + <listitem> + <para> + Identical to <command>filter-aaaa-on-v4</command>, + except it filters AAAA responses to queries from IPv6 + clients instead of IPv4 clients. To filter all + responses, set both options to <userinput>yes</userinput>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>ixfr-from-differences</command></term> + <listitem> + <para> + When <userinput>yes</userinput> and the server loads a new + version of a master zone from its zone file or receives a + new version of a slave file via zone transfer, it will + compare the new version to the previous one and calculate + a set of differences. The differences are then logged in + the zone's journal file such that the changes can be + transmitted to downstream slaves as an incremental zone + transfer. + </para> + <para> + By allowing incremental zone transfers to be used for + non-dynamic zones, this option saves bandwidth at the + expense of increased CPU and memory consumption at the + master. + In particular, if the new version of a zone is completely + different from the previous one, the set of differences + will be of a size comparable to the combined size of the + old and new zone version, and the server will need to + temporarily allocate memory to hold this complete + difference set. + </para> + <para><command>ixfr-from-differences</command> + also accepts <command>master</command> and + <command>slave</command> at the view and options + levels which causes + <command>ixfr-from-differences</command> to be enabled for + all <command>master</command> or + <command>slave</command> zones respectively. + It is off by default. + </para> + <para> + Note: if inline signing is enabled for a zone, the + user-provided <command>ixfr-from-differences</command> + setting is ignored for that zone. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>multi-master</command></term> + <listitem> + <para> + This should be set when you have multiple masters for a zone + and the + addresses refer to different machines. If <userinput>yes</userinput>, <command>named</command> will + not log + when the serial number on the master is less than what <command>named</command> + currently + has. The default is <userinput>no</userinput>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>auto-dnssec</command></term> + <listitem> + <para> + Zones configured for dynamic DNS may use this + option to allow varying levels of automatic DNSSEC key + management. There are three possible settings: + </para> + <para> + <command>auto-dnssec allow;</command> permits + keys to be updated and the zone fully re-signed + whenever the user issues the command <command>rndc sign + <replaceable>zonename</replaceable></command>. + </para> + <para> + <command>auto-dnssec maintain;</command> includes the + above, but also automatically adjusts the zone's DNSSEC + keys on schedule, according to the keys' timing metadata + (see <xref linkend="man.dnssec-keygen"/> and + <xref linkend="man.dnssec-settime"/>). The command + <command>rndc sign + <replaceable>zonename</replaceable></command> causes + <command>named</command> to load keys from the key + repository and sign the zone with all keys that are + active. + <command>rndc loadkeys + <replaceable>zonename</replaceable></command> causes + <command>named</command> to load keys from the key + repository and schedule key maintenance events to occur + in the future, but it does not sign the full zone + immediately. Note: once keys have been loaded for a + zone the first time, the repository will be searched + for changes periodically, regardless of whether + <command>rndc loadkeys</command> is used. The recheck + interval is defined by + <command>dnssec-loadkeys-interval</command>.) + </para> + <para> + The default setting is <command>auto-dnssec off</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>dnssec-enable</command></term> + <listitem> + <para> + This indicates whether DNSSEC-related resource + records are to be returned by <command>named</command>. + If set to <userinput>no</userinput>, + <command>named</command> will not return DNSSEC-related + resource records unless specifically queried for. + The default is <userinput>yes</userinput>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>dnssec-validation</command></term> + <listitem> + <para> + Enable DNSSEC validation in <command>named</command>. + Note <command>dnssec-enable</command> also needs to be + set to <userinput>yes</userinput> to be effective. + If set to <userinput>no</userinput>, DNSSEC validation + is disabled. + </para> + <para> + If set to <userinput>auto</userinput>, DNSSEC validation + is enabled, and a default trust anchor for the DNS root + zone is used. If set to <userinput>yes</userinput>, + DNSSEC validation is enabled, but a trust anchor must be + manually configured using a <command>trusted-keys</command> + or <command>managed-keys</command> statement. The default + is <userinput>yes</userinput>. + </para> + <para> + The default root trust anchor is stored in the file + <filename>bind.keys</filename>. + <command>named</command> will load that key at + startup if <command>dnssec-validation</command> is + set to <constant>auto</constant>. A copy of the file is + installed along with BIND 9, and is current as of the + release date. If the root key expires, a new copy of + <filename>bind.keys</filename> can be downloaded + 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>. + </para> + <para> + To prevent problems if <filename>bind.keys</filename> is + not found, the current trust anchor is also compiled in + to <command>named</command>. Relying on this is not + recommended, however, as it requires <command>named</command> + to be recompiled with a new key when the root key expires.) + </para> + <note> + <para> + <command>named</command> <emphasis>only</emphasis> + loads the root key from <filename>bind.keys</filename>. + The file cannot be used to store keys for other zones. + The root key in <filename>bind.keys</filename> is ignored + if <command>dnssec-validation auto</command> is not in + use. + </para> + <para> + Whenever the resolver sends out queries to an + EDNS-compliant server, it always sets the DO bit + indicating it can support DNSSEC responses even if + <command>dnssec-validation</command> is off. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>dnssec-accept-expired</command></term> + <listitem> + <para> + Accept expired signatures when verifying DNSSEC signatures. + The default is <userinput>no</userinput>. + Setting this option to <userinput>yes</userinput> + leaves <command>named</command> vulnerable to + replay attacks. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>querylog</command></term> + <listitem> + <para> + Specify whether query logging should be started when <command>named</command> + starts. + If <command>querylog</command> is not specified, + then the query logging + is determined by the presence of the logging category <command>queries</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>check-names</command></term> + <listitem> + <para> + This option is used to restrict the character set and syntax + of + certain domain names in master files and/or DNS responses + received + from the network. The default varies according to usage + area. For + <command>master</command> zones the default is <command>fail</command>. + For <command>slave</command> zones the default + is <command>warn</command>. + For answers received from the network (<command>response</command>) + the default is <command>ignore</command>. + </para> + <para> + The rules for legal hostnames and mail domains are derived + from RFC 952 and RFC 821 as modified by RFC 1123. + </para> + <para><command>check-names</command> + applies to the owner names of A, AAAA and MX records. + It also applies to the domain names in the RDATA of NS, SOA, + MX, and SRV records. + It also applies to the RDATA of PTR records where the owner + name indicated that it is a reverse lookup of a hostname + (the owner name ends in IN-ADDR.ARPA, IP6.ARPA, or IP6.INT). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>check-dup-records</command></term> + <listitem> + <para> + Check master zones for records that are treated as different + by DNSSEC but are semantically equal in plain DNS. The + default is to <command>warn</command>. Other possible + values are <command>fail</command> and + <command>ignore</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>check-mx</command></term> + <listitem> + <para> + Check whether the MX record appears to refer to a IP address. + The default is to <command>warn</command>. Other possible + values are <command>fail</command> and + <command>ignore</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>check-wildcard</command></term> + <listitem> + <para> + This option is used to check for non-terminal wildcards. + The use of non-terminal wildcards is almost always as a + result of a failure + to understand the wildcard matching algorithm (RFC 1034). + This option + affects master zones. The default (<command>yes</command>) is to check + for non-terminal wildcards and issue a warning. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>check-integrity</command></term> + <listitem> + <para> + Perform post load zone integrity checks on master + zones. This checks that MX and SRV records refer + to address (A or AAAA) records and that glue + address records exist for delegated zones. For + MX and SRV records only in-zone hostnames are + checked (for out-of-zone hostnames use + <command>named-checkzone</command>). + For NS records only names below top of zone are + checked (for out-of-zone names and glue consistency + checks use <command>named-checkzone</command>). + The default is <command>yes</command>. + </para> + <para> + The use of the SPF record for publishing Sender + Policy Framework is deprecated as the migration + from using TXT records to SPF records was abandoned. + Enabling this option also checks that a TXT Sender + Policy Framework record exists (starts with "v=spf1") + if there is an SPF record. Warnings are emitted if the + TXT record does not exist and can be suppressed with + <command>check-spf</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>check-mx-cname</command></term> + <listitem> + <para> + If <command>check-integrity</command> is set then + fail, warn or ignore MX records that refer + to CNAMES. The default is to <command>warn</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>check-srv-cname</command></term> + <listitem> + <para> + If <command>check-integrity</command> is set then + fail, warn or ignore SRV records that refer + to CNAMES. The default is to <command>warn</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>check-sibling</command></term> + <listitem> + <para> + When performing integrity checks, also check that + sibling glue exists. The default is <command>yes</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>check-spf</command></term> + <listitem> + <para> + If <command>check-integrity</command> is set then + check that there is a TXT Sender Policy Framework + record present (starts with "v=spf1") if there is an + SPF record present. The default is + <command>warn</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>zero-no-soa-ttl</command></term> + <listitem> + <para> + When returning authoritative negative responses to + SOA queries set the TTL of the SOA record returned in + the authority section to zero. + The default is <command>yes</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>zero-no-soa-ttl-cache</command></term> + <listitem> + <para> + When caching a negative response to a SOA query + set the TTL to zero. + The default is <command>no</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>update-check-ksk</command></term> + <listitem> + <para> + When set to the default value of <literal>yes</literal>, + check the KSK bit in each key to determine how the key + should be used when generating RRSIGs for a secure zone. + </para> + <para> + Ordinarily, zone-signing keys (that is, keys without the + KSK bit set) are used to sign the entire zone, while + key-signing keys (keys with the KSK bit set) are only + used to sign the DNSKEY RRset at the zone apex. + However, if this option is set to <literal>no</literal>, + then the KSK bit is ignored; KSKs are treated as if they + were ZSKs and are used to sign the entire zone. This is + similar to the <command>dnssec-signzone -z</command> + command line option. + </para> + <para> + When this option is set to <literal>yes</literal>, there + must be at least two active keys for every algorithm + represented in the DNSKEY RRset: at least one KSK and one + ZSK per algorithm. If there is any algorithm for which + this requirement is not met, this option will be ignored + for that algorithm. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>dnssec-dnskey-kskonly</command></term> + <listitem> + <para> + When this option and <command>update-check-ksk</command> + are both set to <literal>yes</literal>, only key-signing + keys (that is, keys with the KSK bit set) will be used + to sign the DNSKEY RRset at the zone apex. Zone-signing + keys (keys without the KSK bit set) will be used to sign + the remainder of the zone, but not the DNSKEY RRset. + This is similar to the + <command>dnssec-signzone -x</command> command line option. + </para> + <para> + The default is <command>no</command>. If + <command>update-check-ksk</command> is set to + <literal>no</literal>, this option is ignored. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>try-tcp-refresh</command></term> + <listitem> + <para> + Try to refresh the zone using TCP if UDP queries fail. + For BIND 8 compatibility, the default is + <command>yes</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>dnssec-secure-to-insecure</command></term> + <listitem> + <para> + Allow a dynamic zone to transition from secure to + insecure (i.e., signed to unsigned) by deleting all + of the DNSKEY records. The default is <command>no</command>. + If set to <command>yes</command>, and if the DNSKEY RRset + at the zone apex is deleted, all RRSIG and NSEC records + will be removed from the zone as well. + </para> + <para> + If the zone uses NSEC3, then it is also necessary to + delete the NSEC3PARAM RRset from the zone apex; this will + cause the removal of all corresponding NSEC3 records. + (It is expected that this requirement will be eliminated + in a future release.) + </para> + <para> + Note that if a zone has been configured with + <command>auto-dnssec maintain</command> and the + private keys remain accessible in the key repository, + then the zone will be automatically signed again the + next time <command>named</command> is started. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </section> + + <section xml:id="forwarding"><info><title>Forwarding</title></info> + + <para> + The forwarding facility can be used to create a large site-wide + cache on a few servers, reducing traffic over links to external + name servers. It can also be used to allow queries by servers that + do not have direct access to the Internet, but wish to look up + exterior + names anyway. Forwarding occurs only on those queries for which + the server is not authoritative and does not have the answer in + its cache. + </para> + + <variablelist> + <varlistentry> + <term><command>forward</command></term> + <listitem> + <para> + This option is only meaningful if the + forwarders list is not empty. A value of <varname>first</varname>, + the default, causes the server to query the forwarders + first — and + if that doesn't answer the question, the server will then + look for + the answer itself. If <varname>only</varname> is + specified, the + server will only query the forwarders. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>forwarders</command></term> + <listitem> + <para> + Specifies the IP addresses to be used + for forwarding. The default is the empty list (no + forwarding). + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + Forwarding can also be configured on a per-domain basis, allowing + for the global forwarding options to be overridden in a variety + of ways. You can set particular domains to use different + forwarders, + or have a different <command>forward only/first</command> behavior, + or not forward at all, see <xref linkend="zone_statement_grammar"/>. + </para> + </section> + + <section xml:id="dual_stack"><info><title>Dual-stack Servers</title></info> + + <para> + Dual-stack servers are used as servers of last resort to work + around + problems in reachability due the lack of support for either IPv4 + or IPv6 + on the host machine. + </para> + + <variablelist> + <varlistentry> + <term><command>dual-stack-servers</command></term> + <listitem> + <para> + Specifies host names or addresses of machines with access to + both IPv4 and IPv6 transports. If a hostname is used, the + server must be able + to resolve the name using only the transport it has. If the + machine is dual + stacked, then the <command>dual-stack-servers</command> have no effect unless + access to a transport has been disabled on the command line + (e.g. <command>named -4</command>). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section xml:id="access_control"><info><title>Access Control</title></info> + + + <para> + Access to the server can be restricted based on the IP address + of the requesting system. See <xref linkend="address_match_lists"/> for + details on how to specify IP address lists. + </para> + + <variablelist> + + <varlistentry> + <term><command>allow-notify</command></term> + <listitem> + <para> + Specifies which hosts are allowed to + notify this server, a slave, of zone changes in addition + to the zone masters. + <command>allow-notify</command> may also be + specified in the + <command>zone</command> statement, in which case + it overrides the + <command>options allow-notify</command> + statement. It is only meaningful + for a slave zone. If not specified, the default is to + process notify messages + only from a zone's master. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>allow-query</command></term> + <listitem> + <para> + Specifies which hosts are allowed to ask ordinary + DNS questions. <command>allow-query</command> may + also be specified in the <command>zone</command> + statement, in which case it overrides the + <command>options allow-query</command> statement. + If not specified, the default is to allow queries + from all hosts. + </para> + <note> + <para> + <command>allow-query-cache</command> is now + used to specify access to the cache. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>allow-query-on</command></term> + <listitem> + <para> + Specifies which local addresses can accept ordinary + DNS questions. This makes it possible, for instance, + to allow queries on internal-facing interfaces but + disallow them on external-facing ones, without + necessarily knowing the internal network's addresses. + </para> + <para> + Note that <command>allow-query-on</command> is only + checked for queries that are permitted by + <command>allow-query</command>. A query must be + allowed by both ACLs, or it will be refused. + </para> + <para> + <command>allow-query-on</command> may + also be specified in the <command>zone</command> + statement, in which case it overrides the + <command>options allow-query-on</command> statement. + </para> + <para> + If not specified, the default is to allow queries + on all addresses. + </para> + <note> + <para> + <command>allow-query-cache</command> is + used to specify access to the cache. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>allow-query-cache</command></term> + <listitem> + <para> + Specifies which hosts are allowed to get answers + from the cache. If <command>allow-query-cache</command> + is not set then <command>allow-recursion</command> + is used if set, otherwise <command>allow-query</command> + is used if set unless <command>recursion no;</command> is + set in which case <command>none;</command> is used, + otherwise the default (<command>localnets;</command> + <command>localhost;</command>) is used. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>allow-query-cache-on</command></term> + <listitem> + <para> + Specifies which local addresses can give answers + from the cache. If not specified, the default is + to allow cache queries on any address, + <command>localnets</command> and + <command>localhost</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>allow-recursion</command></term> + <listitem> + <para> + Specifies which hosts are allowed to make recursive + queries through this server. If + <command>allow-recursion</command> is not set + then <command>allow-query-cache</command> is + used if set, otherwise <command>allow-query</command> + is used if set, otherwise the default + (<command>localnets;</command> + <command>localhost;</command>) is used. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>allow-recursion-on</command></term> + <listitem> + <para> + Specifies which local addresses can accept recursive + queries. If not specified, the default is to allow + recursive queries on all addresses. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>allow-update</command></term> + <listitem> + <para> + Specifies which hosts are allowed to + submit Dynamic DNS updates for master zones. The default is + to deny + updates from all hosts. Note that allowing updates based + on the requestor's IP address is insecure; see + <xref linkend="dynamic_update_security"/> for details. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>allow-update-forwarding</command></term> + <listitem> + <para> + Specifies which hosts are allowed to + submit Dynamic DNS updates to slave zones to be forwarded to + the + master. The default is <userinput>{ none; }</userinput>, + which + means that no update forwarding will be performed. To + enable + update forwarding, specify + <userinput>allow-update-forwarding { any; };</userinput>. + Specifying values other than <userinput>{ none; }</userinput> or + <userinput>{ any; }</userinput> is usually + counterproductive, since + the responsibility for update access control should rest + with the + master server, not the slaves. + </para> + <para> + Note that enabling the update forwarding feature on a slave + server + may expose master servers relying on insecure IP address + based + access control to attacks; see <xref linkend="dynamic_update_security"/> + for more details. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>allow-v6-synthesis</command></term> + <listitem> + <para> + This option was introduced for the smooth transition from + AAAA + to A6 and from "nibble labels" to binary labels. + However, since both A6 and binary labels were then + deprecated, + this option was also deprecated. + It is now ignored with some warning messages. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>allow-transfer</command></term> + <listitem> + <para> + Specifies which hosts are allowed to + receive zone transfers from the server. <command>allow-transfer</command> may + also be specified in the <command>zone</command> + statement, in which + case it overrides the <command>options allow-transfer</command> statement. + If not specified, the default is to allow transfers to all + hosts. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>blackhole</command></term> + <listitem> + <para> + Specifies a list of addresses that the + server will not accept queries from or use to resolve a + query. Queries + from these addresses will not be responded to. The default + is <userinput>none</userinput>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>filter-aaaa</command></term> + <listitem> + <para> + Specifies a list of addresses to which + <command>filter-aaaa-on-v4</command> + and <command>filter-aaaa-on-v6</command> + apply. The default is <userinput>any</userinput>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>keep-response-order</command></term> + <listitem> + <para> + Specifies a list of addresses to which the server + will send responses to TCP queries in the same order + in which they were received. This disables the + processing of TCP queries in parallel. The default + is <userinput>none</userinput>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>no-case-compress</command></term> <listitem> + <para> + Specifies a list of addresses which require responses + to use case-insensitive compression. This ACL can be + used when <command>named</command> needs to work with + clients that do not comply with the requirement in RFC + 1034 to use case-insensitive name comparisons when + checking for matching domain names. + </para> + <para> + If left undefined, the ACL defaults to + <command>none</command>: case-insensitive compression + will be used for all clients. If the ACL is defined and + matches a client, then case will be ignored when + compressing domain names in DNS responses sent to that + client. + </para> + <para> + This can result in slightly smaller responses: if + a response contains the names "example.com" and + "example.COM", case-insensitive compression would treat + the second one as a duplicate. It also ensures + that the case of the query name exactly matches the + case of the owner names of returned records, rather + than matching the case of the records entered in + the zone file. This allows responses to exactly + match the query, which is required by some clients + due to incorrect use of case-sensitive comparisons. + </para> + <para> + Case-insensitive compression is <emphasis>always</emphasis> + used in AXFR and IXFR responses, regardless of whether + the client matches this ACL. + </para> + <para> + There are circumstances in which <command>named</command> + will not preserve the case of owner names of records: + if a zone file defines records of different types with + the same name, but the capitalization of the name is + different (e.g., "www.example.com/A" and + "WWW.EXAMPLE.COM/AAAA"), then all responses for that + name will use the <emphasis>first</emphasis> version + of the name that was used in the zone file. This + limitation may be addressed in a future release. However, + domain names specified in the rdata of resource records + (i.e., records of type NS, MX, CNAME, etc) will always + have their case preserved unless the client matches this + ACL. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>resolver-query-timeout</command></term> + <listitem> + <para> + The amount of time in seconds that the resolver + will spend attempting to resolve a recursive + query before failing. The default and minimum + is <literal>10</literal> and the maximum is + <literal>30</literal>. Setting it to + <literal>0</literal> will result in the default + being used. + </para> + </listitem> + </varlistentry> + </variablelist> + + </section> + + <section xml:id="interfaces"><info><title>Interfaces</title></info> + + <para> + The interfaces and ports that the server will answer queries + from may be specified using the <command>listen-on</command> option. <command>listen-on</command> takes + an optional port and an <varname>address_match_list</varname> + of IPv4 addresses. (IPv6 addresses are ignored, with a + logged warning.) + The server will listen on all interfaces allowed by the address + match list. If a port is not specified, port 53 will be used. + </para> + <para> + Multiple <command>listen-on</command> statements are + allowed. + For example, + </para> + +<programlisting>listen-on { 5.6.7.8; }; +listen-on port 1234 { !1.2.3.4; 1.2/16; }; +</programlisting> + + <para> + will enable the name server on port 53 for the IP address + 5.6.7.8, and on port 1234 of an address on the machine in net + 1.2 that is not 1.2.3.4. + </para> + + <para> + If no <command>listen-on</command> is specified, the + server will listen on port 53 on all IPv4 interfaces. + </para> + + <para> + The <command>listen-on-v6</command> option is used to + specify the interfaces and the ports on which the server will + listen for incoming queries sent using IPv6. If not specified, + the server will listen on port 53 on all IPv6 interfaces. + </para> + + <para> + When <programlisting>{ any; }</programlisting> is + specified + as the <varname>address_match_list</varname> for the + <command>listen-on-v6</command> option, + the server does not bind a separate socket to each IPv6 interface + address as it does for IPv4 if the operating system has enough API + support for IPv6 (specifically if it conforms to RFC 3493 and RFC + 3542). + Instead, it listens on the IPv6 wildcard address. + If the system only has incomplete API support for IPv6, however, + the behavior is the same as that for IPv4. + </para> + + <para> + A list of particular IPv6 addresses can also be specified, in + which case + the server listens on a separate socket for each specified + address, + regardless of whether the desired API is supported by the system. + IPv4 addresses specified in <command>listen-on-v6</command> + will be ignored, with a logged warning. + </para> + + <para> + Multiple <command>listen-on-v6</command> options can + be used. + For example, + </para> + +<programlisting>listen-on-v6 { any; }; +listen-on-v6 port 1234 { !2001:db8::/32; any; }; +</programlisting> + + <para> + will enable the name server on port 53 for any IPv6 addresses + (with a single wildcard socket), + and on port 1234 of IPv6 addresses that is not in the prefix + 2001:db8::/32 (with separate sockets for each matched address.) + </para> + + <para> + To make the server not listen on any IPv6 address, use + </para> + +<programlisting>listen-on-v6 { none; }; +</programlisting> + + </section> + + <section xml:id="query_address"><info><title>Query Address</title></info> + + <para> + If the server doesn't know the answer to a question, it will + query other name servers. <command>query-source</command> specifies + the address and port used for such queries. For queries sent over + IPv6, there is a separate <command>query-source-v6</command> option. + If <command>address</command> is <command>*</command> (asterisk) or is omitted, + a wildcard IP address (<command>INADDR_ANY</command>) + will be used. + </para> + + <para> + If <command>port</command> is <command>*</command> or is omitted, + a random port number from a pre-configured + range is picked up and will be used for each query. + The port range(s) is that specified in + the <command>use-v4-udp-ports</command> (for IPv4) + and <command>use-v6-udp-ports</command> (for IPv6) + options, excluding the ranges specified in + the <command>avoid-v4-udp-ports</command> + and <command>avoid-v6-udp-ports</command> options, respectively. + </para> + + <para> + The defaults of the <command>query-source</command> and + <command>query-source-v6</command> options + are: + </para> + +<programlisting>query-source address * port *; +query-source-v6 address * port *; +</programlisting> + + <para> + If <command>use-v4-udp-ports</command> or + <command>use-v6-udp-ports</command> is unspecified, + <command>named</command> will check if the operating + system provides a programming interface to retrieve the + system's default range for ephemeral ports. + If such an interface is available, + <command>named</command> will use the corresponding system + default range; otherwise, it will use its own defaults: + </para> + +<programlisting>use-v4-udp-ports { range 1024 65535; }; +use-v6-udp-ports { range 1024 65535; }; +</programlisting> + + <para> + Note: make sure the ranges be sufficiently large for + security. A desirable size depends on various parameters, + but we generally recommend it contain at least 16384 ports + (14 bits of entropy). + Note also that the system's default range when used may be + too small for this purpose, and that the range may even be + changed while <command>named</command> is running; the new + range will automatically be applied when <command>named</command> + is reloaded. + It is encouraged to + configure <command>use-v4-udp-ports</command> and + <command>use-v6-udp-ports</command> explicitly so that the + ranges are sufficiently large and are reasonably + independent from the ranges used by other applications. + </para> + + <para> + Note: the operational configuration + where <command>named</command> runs may prohibit the use + of some ports. For example, UNIX systems will not allow + <command>named</command> running without a root privilege + to use ports less than 1024. + If such ports are included in the specified (or detected) + set of query ports, the corresponding query attempts will + fail, resulting in resolution failures or delay. + It is therefore important to configure the set of ports + that can be safely used in the expected operational environment. + </para> + + <para> + The defaults of the <command>avoid-v4-udp-ports</command> and + <command>avoid-v6-udp-ports</command> options + are: + </para> + +<programlisting>avoid-v4-udp-ports {}; +avoid-v6-udp-ports {}; +</programlisting> + + <para> + Note: BIND 9.5.0 introduced + the <command>use-queryport-pool</command> + option to support a pool of such random ports, but this + option is now obsolete because reusing the same ports in + the pool may not be sufficiently secure. + For the same reason, it is generally strongly discouraged to + specify a particular port for the + <command>query-source</command> or + <command>query-source-v6</command> options; + it implicitly disables the use of randomized port numbers. + </para> + + <variablelist> + <varlistentry> + <term><command>use-queryport-pool</command></term> + <listitem> + <para> + This option is obsolete. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>queryport-pool-ports</command></term> + <listitem> + <para> + This option is obsolete. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>queryport-pool-updateinterval</command></term> + <listitem> + <para> + This option is obsolete. + </para> + </listitem> + </varlistentry> + + </variablelist> + <note> + <para> + The address specified in the <command>query-source</command> option + is used for both UDP and TCP queries, but the port applies only + to UDP queries. TCP queries always use a random + unprivileged port. + </para> + </note> + <note> + <para> + Solaris 2.5.1 and earlier does not support setting the source + address for TCP sockets. + </para> + </note> + <note> + <para> + See also <command>transfer-source</command> and + <command>notify-source</command>. + </para> + </note> + </section> + + <section xml:id="zone_transfers"><info><title>Zone Transfers</title></info> + + <para> + <acronym>BIND</acronym> has mechanisms in place to + facilitate zone transfers + and set limits on the amount of load that transfers place on the + system. The following options apply to zone transfers. + </para> + + <variablelist> + + <varlistentry> + <term><command>also-notify</command></term> + <listitem> + <para> + Defines a global list of IP addresses of name servers + that are also sent NOTIFY messages whenever a fresh copy of + the + zone is loaded, in addition to the servers listed in the + zone's NS records. + This helps to ensure that copies of the zones will + quickly converge on stealth servers. + Optionally, a port may be specified with each + <command>also-notify</command> address to send + the notify messages to a port other than the + default of 53. + An optional TSIG key can also be specified with each + address to cause the notify messages to be signed; this + can be useful when sending notifies to multiple views. + In place of explicit addresses, one or more named + <command>masters</command> lists can be used. + </para> + <para> + If an <command>also-notify</command> list + is given in a <command>zone</command> statement, + it will override + the <command>options also-notify</command> + statement. When a <command>zone notify</command> + statement + is set to <command>no</command>, the IP + addresses in the global <command>also-notify</command> list will + not be sent NOTIFY messages for that zone. The default is + the empty + list (no global notification list). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>max-transfer-time-in</command></term> + <listitem> + <para> + Inbound zone transfers running longer than + this many minutes will be terminated. The default is 120 + minutes + (2 hours). The maximum value is 28 days (40320 minutes). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>max-transfer-idle-in</command></term> + <listitem> + <para> + Inbound zone transfers making no progress + in this many minutes will be terminated. The default is 60 + minutes + (1 hour). The maximum value is 28 days (40320 minutes). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>max-transfer-time-out</command></term> + <listitem> + <para> + Outbound zone transfers running longer than + this many minutes will be terminated. The default is 120 + minutes + (2 hours). The maximum value is 28 days (40320 minutes). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>max-transfer-idle-out</command></term> + <listitem> + <para> + Outbound zone transfers making no progress + in this many minutes will be terminated. The default is 60 + minutes (1 + hour). The maximum value is 28 days (40320 minutes). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>notify-rate</command></term> + <listitem> + <para> + The rate at which NOTIFY requests will be sent + during normal zone maintenance operations. (NOTIFY + requests due to initial zone loading are subject + to a separate rate limit; see below.) The default is + 20 per second. + The lowest possible rate is one per second; when set + to zero, it will be silently raised to one. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>startup-notify-rate</command></term> + <listitem> + <para> + The rate at which NOTIFY requests will be sent + when the name server is first starting up, or when + zones have been newly added to the nameserver. + The default is 20 per second. + The lowest possible rate is one per second; when set + to zero, it will be silently raised to one. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>serial-query-rate</command></term> + <listitem> + <para> + Slave servers will periodically query master + servers to find out if zone serial numbers have + changed. Each such query uses a minute amount of + the slave server's network bandwidth. To limit + the amount of bandwidth used, BIND 9 limits the + rate at which queries are sent. The value of the + <command>serial-query-rate</command> option, an + integer, is the maximum number of queries sent + per second. The default is 20 per second. + The lowest possible rate is one per second; when set + to zero, it will be silently raised to one. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>serial-queries</command></term> + <listitem> + <para> + In BIND 8, the <command>serial-queries</command> + option + set the maximum number of concurrent serial number queries + allowed to be outstanding at any given time. + BIND 9 does not limit the number of outstanding + serial queries and ignores the <command>serial-queries</command> option. + Instead, it limits the rate at which the queries are sent + as defined using the <command>serial-query-rate</command> option. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>transfer-format</command></term> + <listitem> + + <para> + Zone transfers can be sent using two different formats, + <command>one-answer</command> and + <command>many-answers</command>. + The <command>transfer-format</command> option is used + on the master server to determine which format it sends. + <command>one-answer</command> uses one DNS message per + resource record transferred. + <command>many-answers</command> packs as many resource + records as possible into a message. + <command>many-answers</command> is more efficient, but is + only supported by relatively new slave servers, + such as <acronym>BIND</acronym> 9, <acronym>BIND</acronym> + 8.x and <acronym>BIND</acronym> 4.9.5 onwards. + The <command>many-answers</command> format is also supported by + recent Microsoft Windows nameservers. + The default is <command>many-answers</command>. + <command>transfer-format</command> may be overridden on a + per-server basis by using the <command>server</command> + statement. + </para> + + </listitem> + </varlistentry> + + <varlistentry> + <term><command>transfer-message-size</command></term> + <listitem> + <para> + This is an upper bound on the uncompressed size of DNS + messages used in zone transfers over TCP. If a message + grows larger than this size, additional messages will be + used to complete the zone transfer. (Note, however, + that this is a hint, not a hard limit; if a message + contains a single resource record whose RDATA does not + fit within the size limit, a larger message will be + permitted so the record can be transferred.) + </para> + <para> + Valid values are between 512 and 65535 octets, and any + values outside that range will be adjusted to the nearest + value within it. The default is <literal>20480</literal>, + which was selected to improve message compression: + most DNS messages of this size will compress to less + than 16536 bytes. Larger messages cannot be compressed + as effectively, because 16536 is the largest permissible + compression offset pointer in a DNS message. + </para> + <para> + This option is mainly intended for server testing; + there is rarely any benefit in setting a value other + than the default. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>transfers-in</command></term> + <listitem> + <para> + The maximum number of inbound zone transfers + that can be running concurrently. The default value is <literal>10</literal>. + Increasing <command>transfers-in</command> may + speed up the convergence + of slave zones, but it also may increase the load on the + local system. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>transfers-out</command></term> + <listitem> + <para> + The maximum number of outbound zone transfers + that can be running concurrently. Zone transfer requests in + excess + of the limit will be refused. The default value is <literal>10</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>transfers-per-ns</command></term> + <listitem> + <para> + The maximum number of inbound zone transfers + that can be concurrently transferring from a given remote + name server. + The default value is <literal>2</literal>. + Increasing <command>transfers-per-ns</command> + may + speed up the convergence of slave zones, but it also may + increase + the load on the remote name server. <command>transfers-per-ns</command> may + be overridden on a per-server basis by using the <command>transfers</command> phrase + of the <command>server</command> statement. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>transfer-source</command></term> + <listitem> + <para><command>transfer-source</command> + determines which local address will be bound to IPv4 + TCP connections used to fetch zones transferred + inbound by the server. It also determines the + source IPv4 address, and optionally the UDP port, + used for the refresh queries and forwarded dynamic + updates. If not set, it defaults to a system + controlled value which will usually be the address + of the interface "closest to" the remote end. This + address must appear in the remote end's + <command>allow-transfer</command> option for the + zone being transferred, if one is specified. This + statement sets the + <command>transfer-source</command> for all zones, + but can be overridden on a per-view or per-zone + basis by including a + <command>transfer-source</command> statement within + the <command>view</command> or + <command>zone</command> block in the configuration + file. + </para> + <note> + <para> + Solaris 2.5.1 and earlier does not support setting the + source address for TCP sockets. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>transfer-source-v6</command></term> + <listitem> + <para> + The same as <command>transfer-source</command>, + except zone transfers are performed using IPv6. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>alt-transfer-source</command></term> + <listitem> + <para> + An alternate transfer source if the one listed in + <command>transfer-source</command> fails and + <command>use-alt-transfer-source</command> is + set. + </para> + <note><simpara> + If you do not wish the alternate transfer source + to be used, you should set + <command>use-alt-transfer-source</command> + appropriately and you should not depend upon + getting an answer back to the first refresh + query. + </simpara></note> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>alt-transfer-source-v6</command></term> + <listitem> + <para> + An alternate transfer source if the one listed in + <command>transfer-source-v6</command> fails and + <command>use-alt-transfer-source</command> is + set. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>use-alt-transfer-source</command></term> + <listitem> + <para> + Use the alternate transfer sources or not. If views are + specified this defaults to <command>no</command> + otherwise it defaults to + <command>yes</command> (for BIND 8 + compatibility). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>notify-source</command></term> + <listitem> + <para><command>notify-source</command> + determines which local source address, and + optionally UDP port, will be used to send NOTIFY + messages. This address must appear in the slave + server's <command>masters</command> zone clause or + in an <command>allow-notify</command> clause. This + statement sets the <command>notify-source</command> + for all zones, but can be overridden on a per-zone or + per-view basis by including a + <command>notify-source</command> statement within + the <command>zone</command> or + <command>view</command> block in the configuration + file. + </para> + <note> + <para> + Solaris 2.5.1 and earlier does not support setting the + source address for TCP sockets. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>notify-source-v6</command></term> + <listitem> + <para> + Like <command>notify-source</command>, + but applies to notify messages sent to IPv6 addresses. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </section> + + <section xml:id="port_lists"><info><title>UDP Port Lists</title></info> + + <para> + <command>use-v4-udp-ports</command>, + <command>avoid-v4-udp-ports</command>, + <command>use-v6-udp-ports</command>, and + <command>avoid-v6-udp-ports</command> + specify a list of IPv4 and IPv6 UDP ports that will be + used or not used as source ports for UDP messages. + See <xref linkend="query_address"/> about how the + available ports are determined. + For example, with the following configuration + </para> + +<programlisting> +use-v6-udp-ports { range 32768 65535; }; +avoid-v6-udp-ports { 40000; range 50000 60000; }; +</programlisting> + + <para> + UDP ports of IPv6 messages sent + from <command>named</command> will be in one + of the following ranges: 32768 to 39999, 40001 to 49999, + and 60001 to 65535. + </para> + + <para> + <command>avoid-v4-udp-ports</command> and + <command>avoid-v6-udp-ports</command> can be used + to prevent <command>named</command> from choosing as its random source port a + port that is blocked by your firewall or a port that is + used by other applications; + if a query went out with a source port blocked by a + firewall, the + answer would not get by the firewall and the name server would + have to query again. + Note: the desired range can also be represented only with + <command>use-v4-udp-ports</command> and + <command>use-v6-udp-ports</command>, and the + <command>avoid-</command> options are redundant in that + sense; they are provided for backward compatibility and + to possibly simplify the port specification. + </para> + </section> + + <section xml:id="resource_limits"><info><title>Operating System Resource Limits</title></info> + + <para> + The server's usage of many system resources can be limited. + Scaled values are allowed when specifying resource limits. For + example, <command>1G</command> can be used instead of + <command>1073741824</command> to specify a limit of + one + gigabyte. <command>unlimited</command> requests + unlimited use, or the + maximum available amount. <command>default</command> + uses the limit + that was in force when the server was started. See the description + of <command>size_spec</command> in <xref linkend="configuration_file_elements"/>. + </para> + + <para> + The following options set operating system resource limits for + the name server process. Some operating systems don't support + some or + any of the limits. On such systems, a warning will be issued if + the + unsupported limit is used. + </para> + + <variablelist> + + <varlistentry> + <term><command>coresize</command></term> + <listitem> + <para> + The maximum size of a core dump. The default + is <literal>default</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>datasize</command></term> + <listitem> + <para> + The maximum amount of data memory the server + may use. The default is <literal>default</literal>. + This is a hard limit on server memory usage. + If the server attempts to allocate memory in excess of this + limit, the allocation will fail, which may in turn leave + the server unable to perform DNS service. Therefore, + this option is rarely useful as a way of limiting the + amount of memory used by the server, but it can be used + to raise an operating system data size limit that is + too small by default. If you wish to limit the amount + of memory used by the server, use the + <command>max-cache-size</command> and + <command>recursive-clients</command> + options instead. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>files</command></term> + <listitem> + <para> + The maximum number of files the server + may have open concurrently. The default is <literal>unlimited</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>stacksize</command></term> + <listitem> + <para> + The maximum amount of stack memory the server + may use. The default is <literal>default</literal>. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </section> + + <section xml:id="server_resource_limits"><info><title>Server Resource Limits</title></info> + + <para> + The following options set limits on the server's + resource consumption that are enforced internally by the + server rather than the operating system. + </para> + + <variablelist> + + <varlistentry> + <term><command>max-ixfr-log-size</command></term> + <listitem> + <para> + This option is obsolete; it is accepted + and ignored for BIND 8 compatibility. The option + <command>max-journal-size</command> performs a + similar function in BIND 9. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>max-journal-size</command></term> + <listitem> + <para> + Sets a maximum size for each journal file + (see <xref linkend="journal"/>). When the journal file + approaches + the specified size, some of the oldest transactions in the + journal + will be automatically removed. The largest permitted + value is 2 gigabytes. The default is + <literal>unlimited</literal>, which also + means 2 gigabytes. + This may also be set on a per-zone basis. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>max-records</command></term> + <listitem> + <para> + The maximum number of records permitted in a zone. + The default is zero which means unlimited. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>host-statistics-max</command></term> + <listitem> + <para> + In BIND 8, specifies the maximum number of host statistics + entries to be kept. + Not implemented in BIND 9. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>recursive-clients</command></term> + <listitem> + <para> + The maximum number ("hard quota") of simultaneous + recursive lookups the server will perform on behalf + of clients. The default is + <literal>1000</literal>. Because each recursing + client uses a fair + bit of memory (on the order of 20 kilobytes), the + value of the + <command>recursive-clients</command> option may + have to be decreased on hosts with limited memory. + </para> + <para> + <option>recursive-clients</option> defines a "hard + quota" limit for pending recursive clients: when more + clients than this are pending, new incoming requests + will not be accepted, and for each incoming request + a previous pending request will also be dropped. + </para> + <para> + A "soft quota" is also set. When this lower + quota is exceeded, incoming requests are accepted, but + for each one, a pending request will be dropped. + If <option>recursive-clients</option> is greater than + 1000, the soft quota is set to + <option>recursive-clients</option> minus 100; + otherwise it is set to 90% of + <option>recursive-clients</option>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>tcp-clients</command></term> + <listitem> + <para> + The maximum number of simultaneous client TCP + connections that the server will accept. + The default is <literal>150</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry xml:id="clients-per-query"> + <term xml:id="cpq_term"><command>clients-per-query</command></term> + <term><command>max-clients-per-query</command></term> + <listitem> + <para>These set the + initial value (minimum) and maximum number of recursive + simultaneous clients for any given query + (<qname,qtype,qclass>) that the server will accept + before dropping additional clients. <command>named</command> will attempt to + self tune this value and changes will be logged. The + default values are 10 and 100. + </para> + <para> + This value should reflect how many queries come in for + a given name in the time it takes to resolve that name. + If the number of queries exceed this value, <command>named</command> will + assume that it is dealing with a non-responsive zone + and will drop additional queries. If it gets a response + after dropping queries, it will raise the estimate. The + estimate will then be lowered in 20 minutes if it has + remained unchanged. + </para> + <para> + If <command>clients-per-query</command> is set to zero, + then there is no limit on the number of clients per query + and no queries will be dropped. + </para> + <para> + If <command>max-clients-per-query</command> is set to zero, + then there is no upper bound other than imposed by + <command>recursive-clients</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry xml:id="fetches-per-zone"> + <term><command>fetches-per-zone</command></term> + <listitem> + <para> + The maximum number of simultaneous iterative + queries to any one domain that the server will + permit before blocking new queries for data + in or beneath that zone. + This value should reflect how many fetches would + normally be sent to any one zone in the time it + would take to resolve them. It should be smaller + than <option>recursive-clients</option>. + </para> + <para> + When many clients simultaneously query for the + same name and type, the clients will all be attached + to the same fetch, up to the + <option>max-clients-per-query</option> limit, + and only one iterative query will be sent. + However, when clients are simultaneously + querying for <emphasis>different</emphasis> names + or types, multiple queries will be sent and + <option>max-clients-per-query</option> is not + effective as a limit. + </para> + <para> + Optionally, this value may be followed by the keyword + <literal>drop</literal> or <literal>fail</literal>, + indicating whether queries which exceed the fetch + quota for a zone will be dropped with no response, + or answered with SERVFAIL. The default is + <literal>drop</literal>. + </para> + <para> + If <command>fetches-per-zone</command> is set to zero, + then there is no limit on the number of fetches per query + and no queries will be dropped. The default is zero. + </para> + <para> + The current list of active fetches can be dumped by + running <command>rndc recursing</command>. The list + includes the number of active fetches for each + domain and the number of queries that have been + passed or dropped as a result of the + <option>fetches-per-zone</option> limit. (Note: + these counters are not cumulative over time; whenever + the number of active fetches for a domain drops to + zero, the counter for that domain is deleted, and the + next time a fetch is sent to that domain, it is + recreated with the counters set to zero.) + </para> + </listitem> + </varlistentry> + + <varlistentry xml:id="fetches-per-server"> + <term><command>fetches-per-server</command></term> + <listitem> + <para> + The maximum number of simultaneous iterative + queries that the server will allow to be sent to + a single upstream name server before blocking + additional queries. + This value should reflect how many fetches would + normally be sent to any one server in the time it + would take to resolve them. It should be smaller + than <option>recursive-clients</option>. + </para> + <para> + Optionally, this value may be followed by the keyword + <literal>drop</literal> or <literal>fail</literal>, + indicating whether queries will be dropped with no + response, or answered with SERVFAIL, when all of the + servers authoritative for a zone are found to have + exceeded the per-server quota. The default is + <literal>fail</literal>. + </para> + <para> + If <command>fetches-per-server</command> is set to zero, + then there is no limit on the number of fetches per query + and no queries will be dropped. The default is zero. + </para> + <para> + The <command>fetches-per-server</command> quota is + dynamically adjusted in response to detected + congestion. As queries are sent to a server + and are either answered or time out, an + exponentially weighted moving average is calculated + of the ratio of timeouts to responses. If the + current average timeout ratio rises above a "high" + threshold, then <command>fetches-per-server</command> + is reduced for that server. If the timeout ratio + drops below a "low" threshold, then + <command>fetches-per-server</command> is increased. + The <command>fetch-quota-params</command> options + can be used to adjust the parameters for this + calculation. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>fetch-quota-params</command></term> + <listitem> + <para> + Sets the parameters to use for dynamic resizing of + the <option>fetches-per-server</option> quota in + response to detected congestion. + </para> + <para> + The first argument is an integer value indicating + how frequently to recalculate the moving average + of the ratio of timeouts to responses for each + server. The default is 100, meaning we recalculate + the average ratio after every 100 queries have either + been answered or timed out. + </para> + <para> + The remaining three arguments represent the "low" + threshold (defaulting to a timeout ratio of 0.1), + the "high" threshold (defaulting to a timeout + ratio of 0.3), and the discount rate for + the moving average (defaulting to 0.7). + A higher discount rate causes recent events to + weigh more heavily when calculating the moving + average; a lower discount rate causes past + events to weigh more heavily, smoothing out + short-term blips in the timeout ratio. + These arguments are all fixed-point numbers with + precision of 1/100: at most two places after + the decimal point are significant. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>reserved-sockets</command></term> + <listitem> + <para> + The number of file descriptors reserved for TCP, stdio, + etc. This needs to be big enough to cover the number of + interfaces <command>named</command> listens on, <command>tcp-clients</command> as well as + to provide room for outgoing TCP queries and incoming zone + transfers. The default is <literal>512</literal>. + The minimum value is <literal>128</literal> and the + maximum value is <literal>128</literal> less than + maxsockets (-S). This option may be removed in the future. + </para> + <para> + This option has little effect on Windows. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>max-cache-size</command></term> + <listitem> + <para> + The maximum amount of memory to use for the + server's cache, in bytes or % of total physical memory. + When the amount of data in the cache + reaches this limit, the server will cause records to + expire prematurely based on an LRU based strategy so + that the limit is not exceeded. + The keyword <userinput>unlimited</userinput>, + or the value 0, will place no limit on cache size; + records will be purged from the cache only when their + TTLs expire. + Any positive values less than 2MB will be ignored + and reset to 2MB. + In a server with multiple views, the limit applies + separately to the cache of each view. + The default is <userinput>90%</userinput>. + On systems where detection of amount of physical + memory is not supported values represented as % + fall back to unlimited. + Note that the detection of physical memory is done only + once at startup, so <command>named</command> will not + adjust the cache size if the amount of physical memory + is changed during runtime. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>tcp-listen-queue</command></term> + <listitem> + <para> + The listen queue depth. The default and minimum is 10. + If the kernel supports the accept filter "dataready" this + also controls how + many TCP connections that will be queued in kernel space + waiting for + some data before being passed to accept. Nonzero values + less than 10 will be silently raised. A value of 0 may also + be used; on most platforms this sets the listen queue + length to a system-defined default value. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </section> + + <section xml:id="intervals"><info><title>Periodic Task Intervals</title></info> + + <variablelist> + + <varlistentry> + <term><command>cleaning-interval</command></term> + <listitem> + <para> + This interval is effectively obsolete. Previously, + the server would remove expired resource records + from the cache every <command>cleaning-interval</command> minutes. + <acronym>BIND</acronym> 9 now manages cache + memory in a more sophisticated manner and does not + rely on the periodic cleaning any more. + Specifying this option therefore has no effect on + the server's behavior. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>heartbeat-interval</command></term> + <listitem> + <para> + The server will perform zone maintenance tasks + for all zones marked as <command>dialup</command> whenever this + interval expires. The default is 60 minutes. Reasonable + values are up + to 1 day (1440 minutes). The maximum value is 28 days + (40320 minutes). + If set to 0, no zone maintenance for these zones will occur. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>interface-interval</command></term> + <listitem> + <para> + The server will scan the network interface list + every <command>interface-interval</command> + minutes. The default + is 60 minutes. The maximum value is 28 days (40320 minutes). + If set to 0, interface scanning will only occur when + the configuration file is loaded. After the scan, the + server will + begin listening for queries on any newly discovered + interfaces (provided they are allowed by the + <command>listen-on</command> configuration), and + will + stop listening on interfaces that have gone away. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>statistics-interval</command></term> + <listitem> + <para> + Name server statistics will be logged + every <command>statistics-interval</command> + minutes. The default is + 60. The maximum value is 28 days (40320 minutes). + If set to 0, no statistics will be logged. + </para><note> + <simpara> + Not yet implemented in + <acronym>BIND</acronym> 9. + </simpara> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>topology</command></term> + <listitem> + <para> + In BIND 8, this option indicated network topology + so that preferential treatment could be given to + the topologicaly closest name servers when sending + queries. It is not implemented in BIND 9. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </section> + + <section xml:id="the_sortlist_statement"><info><title>The <command>sortlist</command> Statement</title></info> + + <para> + The response to a DNS query may consist of multiple resource + records (RRs) forming a resource record set (RRset). The name + server will normally return the RRs within the RRset in an + indeterminate order (but see the <command>rrset-order</command> + statement in <xref linkend="rrset_ordering"/>). The client + resolver code should rearrange the RRs as appropriate, that is, + using any addresses on the local net in preference to other + addresses. However, not all resolvers can do this or are + correctly configured. When a client is using a local server, + the sorting can be performed in the server, based on the + client's address. This only requires configuring the name + servers, not all the clients. + </para> + + <para> + The <command>sortlist</command> statement (see below) takes an + <command>address_match_list</command> and interprets it in a + special way. Each top level statement in the + <command>sortlist</command> must itself be an explicit + <command>address_match_list</command> with one or two elements. + The first element (which may be an IP address, an IP prefix, an + ACL name or a nested <command>address_match_list</command>) of + each top level list is checked against the source address of + the query until a match is found. + </para> + <para> + Once the source address of the query has been matched, if the + top level statement contains only one element, the actual + primitive element that matched the source address is used to + select the address in the response to move to the beginning of + the response. If the statement is a list of two elements, then + the second element is interpreted as a topology preference + list. Each top level element is assigned a distance and the + address in the response with the minimum distance is moved to + the beginning of the response. + </para> + <para> + In the following example, any queries received from any of the + addresses of the host itself will get responses preferring + addresses on any of the locally connected networks. Next most + preferred are addresses on the 192.168.1/24 network, and after + that either the 192.168.2/24 or 192.168.3/24 network with no + preference shown between these two networks. Queries received + from a host on the 192.168.1/24 network will prefer other + addresses on that network to the 192.168.2/24 and 192.168.3/24 + networks. Queries received from a host on the 192.168.4/24 or + the 192.168.5/24 network will only prefer other addresses on + their directly connected networks. + </para> + +<programlisting>sortlist { + // IF the local host + // THEN first fit on the following nets + { localhost; + { localnets; + 192.168.1/24; + { 192.168.2/24; 192.168.3/24; }; }; }; + // IF on class C 192.168.1 THEN use .1, or .2 or .3 + { 192.168.1/24; + { 192.168.1/24; + { 192.168.2/24; 192.168.3/24; }; }; }; + // IF on class C 192.168.2 THEN use .2, or .1 or .3 + { 192.168.2/24; + { 192.168.2/24; + { 192.168.1/24; 192.168.3/24; }; }; }; + // IF on class C 192.168.3 THEN use .3, or .1 or .2 + { 192.168.3/24; + { 192.168.3/24; + { 192.168.1/24; 192.168.2/24; }; }; }; + // IF .4 or .5 THEN prefer that net + { { 192.168.4/24; 192.168.5/24; }; + }; +};</programlisting> + + <para> + The following example will give reasonable behavior for the + local host and hosts on directly connected networks. It is + similar to the behavior of the address sort in + <acronym>BIND</acronym> 4.9.x. Responses sent to queries from + the local host will favor any of the directly connected + networks. Responses sent to queries from any other hosts on a + directly connected network will prefer addresses on that same + network. Responses to other queries will not be sorted. + </para> + +<programlisting>sortlist { + { localhost; localnets; }; + { localnets; }; +}; +</programlisting> + + </section> + <section xml:id="rrset_ordering"><info><title xml:id="rrset_ordering_title">RRset Ordering</title></info> + + <para> + When multiple records are returned in an answer it may be + useful to configure the order of the records placed into the + response. + The <command>rrset-order</command> statement permits + configuration + of the ordering of the records in a multiple record response. + See also the <command>sortlist</command> statement, + <xref linkend="the_sortlist_statement"/>. + </para> + + <para> + An <command>order_spec</command> is defined as + follows: + </para> + <para> + <optional>class <replaceable>class_name</replaceable></optional> + <optional>type <replaceable>type_name</replaceable></optional> + <optional>name <replaceable>"domain_name"</replaceable></optional> + order <replaceable>ordering</replaceable> + </para> + <para> + If no class is specified, the default is <command>ANY</command>. + If no type is specified, the default is <command>ANY</command>. + If no name is specified, the default is "<command>*</command>" (asterisk). + </para> + <para> + The legal values for <command>ordering</command> are: + </para> + <informaltable colsep="0" rowsep="0"> + <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="4Level-table"> + <colspec colname="1" colnum="1" colsep="0" colwidth="0.750in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="3.750in"/> + <tbody> + <row rowsep="0"> + <entry colname="1"> + <para><command>fixed</command></para> + </entry> + <entry colname="2"> + <para> + Records are returned in the order they + are defined in the zone file. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>random</command></para> + </entry> + <entry colname="2"> + <para> + Records are returned in some random order. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>cyclic</command></para> + </entry> + <entry colname="2"> + <para> + Records are returned in a cyclic round-robin order. + </para> + <para> + If <acronym>BIND</acronym> is configured with the + "--enable-fixed-rrset" option at compile time, then + the initial ordering of the RRset will match the + one specified in the zone file. + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <para> + For example: + </para> + +<programlisting>rrset-order { + class IN type A name "host.example.com" order random; + order cyclic; +}; +</programlisting> + + <para> + will cause any responses for type A records in class IN that + have "<literal>host.example.com</literal>" as a + suffix, to always be returned + in random order. All other records are returned in cyclic order. + </para> + <para> + If multiple <command>rrset-order</command> statements + appear, they are not combined — the last one applies. + </para> + <para> + By default, all records are returned in random order. + </para> + + <note> + <simpara> + In this release of <acronym>BIND</acronym> 9, the + <command>rrset-order</command> statement does not support + "fixed" ordering by default. Fixed ordering can be enabled + at compile time by specifying "--enable-fixed-rrset" on + the "configure" command line. + </simpara> + </note> + </section> + + <section xml:id="tuning"><info><title>Tuning</title></info> + + <variablelist> + + <varlistentry> + <term><command>lame-ttl</command></term> + <listitem> + <para> + Sets the number of seconds to cache a + lame server indication. 0 disables caching. (This is + <emphasis role="bold">NOT</emphasis> recommended.) + The default is <literal>600</literal> (10 minutes) and the + maximum value is + <literal>1800</literal> (30 minutes). + </para> + + </listitem> + </varlistentry> + + <varlistentry> + <term><command>servfail-ttl</command></term> + <listitem> + <para> + Sets the number of seconds to cache a + SERVFAIL response due to DNSSEC validation failure or + other general server failure. If set to + <literal>0</literal>, SERVFAIL caching is disabled. + The SERVFAIL cache is not consulted if a query has + the CD (Checking Disabled) bit set; this allows a + query that failed due to DNSSEC validation to be retried + without waiting for the SERVFAIL TTL to expire. + </para> + <para> + The maximum value is <literal>30</literal> + seconds; any higher value will be silently + reduced. The default is <literal>1</literal> + second. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>max-ncache-ttl</command></term> + <listitem> + <para> + To reduce network traffic and increase performance, + the server stores negative answers. <command>max-ncache-ttl</command> is + used to set a maximum retention time for these answers in + the server + in seconds. The default + <command>max-ncache-ttl</command> is <literal>10800</literal> seconds (3 hours). + <command>max-ncache-ttl</command> cannot exceed + 7 days and will + be silently truncated to 7 days if set to a greater value. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>max-cache-ttl</command></term> + <listitem> + <para> + Sets the maximum time for which the server will + cache ordinary (positive) answers in seconds. + The default is 604800 (one week). + A value of zero may cause all queries to return + SERVFAIL, because of lost caches of intermediate + RRsets (such as NS and glue AAAA/A records) in the + resolution process. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>min-roots</command></term> + <listitem> + <para> + The minimum number of root servers that + is required for a request for the root servers to be + accepted. The default + is <userinput>2</userinput>. + </para> + <note> + <simpara> + Not implemented in <acronym>BIND</acronym> 9. + </simpara> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>sig-validity-interval</command></term> + <listitem> + <para> + Specifies the number of days into the future when + DNSSEC signatures automatically generated as a + result of dynamic updates (<xref linkend="dynamic_update"/>) will expire. There + is an optional second field which specifies how + long before expiry that the signatures will be + regenerated. If not specified, the signatures will + be regenerated at 1/4 of base interval. The second + field is specified in days if the base interval is + greater than 7 days otherwise it is specified in hours. + The default base interval is <literal>30</literal> days + giving a re-signing interval of 7 1/2 days. The maximum + values are 10 years (3660 days). + </para> + <para> + The signature inception time is unconditionally + set to one hour before the current time to allow + for a limited amount of clock skew. + </para> + <para> + The <command>sig-validity-interval</command> + should be, at least, several multiples of the SOA + expire interval to allow for reasonable interaction + between the various timer and expiry dates. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>sig-signing-nodes</command></term> + <listitem> + <para> + Specify the maximum number of nodes to be + examined in each quantum when signing a zone with + a new DNSKEY. The default is + <literal>100</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>sig-signing-signatures</command></term> + <listitem> + <para> + Specify a threshold number of signatures that + will terminate processing a quantum when signing + a zone with a new DNSKEY. The default is + <literal>10</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>sig-signing-type</command></term> + <listitem> + <para> + Specify a private RDATA type to be used when generating + signing state records. The default is + <literal>65534</literal>. + </para> + <para> + It is expected that this parameter may be removed + in a future version once there is a standard type. + </para> + <para> + Signing state records are used to internally by + <command>named</command> to track the current state of + a zone-signing process, i.e., whether it is still active + or has been completed. The records can be inspected + using the command + <command>rndc signing -list <replaceable>zone</replaceable></command>. + Once <command>named</command> has finished signing + a zone with a particular key, the signing state + record associated with that key can be removed from + the zone by running + <command>rndc signing -clear <replaceable>keyid/algorithm</replaceable> <replaceable>zone</replaceable></command>. + To clear all of the completed signing state + records for a zone, use + <command>rndc signing -clear all <replaceable>zone</replaceable></command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>min-refresh-time</command></term> + <term><command>max-refresh-time</command></term> + <term><command>min-retry-time</command></term> + <term><command>max-retry-time</command></term> + <listitem> + <para> + These options control the server's behavior on refreshing a + zone (querying for SOA changes) or retrying failed + transfers. Usually the SOA values for the zone are used, + up to a hard-coded maximum expiry of 24 weeks. However, + these values are set by the master, giving slave server + administrators little control over their contents. + </para> + <para> + These options allow the administrator to set a minimum and + maximum refresh and retry time in seconds per-zone, + per-view, or globally. These options are valid for + slave and stub zones, and clamp the SOA refresh and + retry times to the specified values. + </para> + <para> + The following defaults apply. + <command>min-refresh-time</command> 300 seconds, + <command>max-refresh-time</command> 2419200 seconds + (4 weeks), <command>min-retry-time</command> 500 seconds, + and <command>max-retry-time</command> 1209600 seconds + (2 weeks). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>edns-udp-size</command></term> + <listitem> + <para> + Sets the maximum advertised EDNS UDP buffer size in + bytes, to control the size of packets received from + authoritative servers in response to recursive queries. + Valid values are 512 to 4096 (values outside this range + will be silently adjusted to the nearest value within + it). The default value is 4096. + </para> + <para> + The usual reason for setting + <command>edns-udp-size</command> to a non-default value + is to get UDP answers to pass through broken firewalls + that block fragmented packets and/or block UDP DNS + packets that are greater than 512 bytes. + </para> + <para> + When <command>named</command> first queries a remote + server, it will advertise a UDP buffer size of 512, as + this has the greatest chance of success on the first try. + </para> + <para> + If the initial response times out, <command>named</command> + will try again with plain DNS, and if that is successful, + it will be taken as evidence that the server does not + support EDNS. After enough failures using EDNS and + successes using plain DNS, <command>named</command> + will default to plain DNS for future communications + with that server. (Periodically, <command>named</command> + will send an EDNS query to see if the situation has + improved.) + </para> + <para> + However, if the initial query is successful with + EDNS advertising a buffer size of 512, then + <command>named</command> will advertise progressively + larger buffer sizes on successive queries, until + responses begin timing out or + <command>edns-udp-size</command> is reached. + </para> + <para> + The default buffer sizes used by <command>named</command> + are 512, 1232, 1432, and 4096, but never exceeding + <command>edns-udp-size</command>. (The values 1232 and + 1432 are chosen to allow for an IPv4/IPv6 encapsulated + UDP message to be sent without fragmentation at the + minimum MTU sizes for Ethernet and IPv6 networks.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>max-udp-size</command></term> + <listitem> + <para> + Sets the maximum EDNS UDP message size + <command>named</command> will send in bytes. + Valid values are 512 to 4096 (values outside this + range will be silently adjusted to the nearest + value within it). The default value is 4096. + </para> + <para> + This value applies to responses sent by a server; to + set the advertised buffer size in queries, see + <command>edns-udp-size</command>. + </para> + <para> + The usual reason for setting + <command>max-udp-size</command> to a non-default + value is to get UDP answers to pass through broken + firewalls that block fragmented packets and/or + block UDP packets that are greater than 512 bytes. + This is independent of the advertised receive + buffer (<command>edns-udp-size</command>). + </para> + <para> + Setting this to a low value will encourage additional + TCP traffic to the nameserver. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>masterfile-format</command></term> + <listitem> + <para>Specifies + the file format of zone files (see + <xref linkend="zonefile_format"/>). + The default value is <constant>text</constant>, which is the + standard textual representation, except for slave zones, + in which the default value is <constant>raw</constant>. + Files in other formats than <constant>text</constant> are + typically expected to be generated by the + <command>named-compilezone</command> tool, or dumped by + <command>named</command>. + </para> + <para> + Note that when a zone file in a different format than + <constant>text</constant> is loaded, <command>named</command> + may omit some of the checks which would be performed for a + file in the <constant>text</constant> format. In particular, + <command>check-names</command> checks do not apply + for the <constant>raw</constant> format. This means + a zone file in the <constant>raw</constant> format + must be generated with the same check level as that + specified in the <command>named</command> configuration + file. Also, <constant>map</constant> format files are + loaded directly into memory via memory mapping, with only + minimal checking. + </para> + <para> + This statement sets the + <command>masterfile-format</command> for all zones, + but can be overridden on a per-zone or per-view basis + by including a <command>masterfile-format</command> + statement within the <command>zone</command> or + <command>view</command> block in the configuration + file. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>masterfile-style</command></term> + <listitem> + <para> + Specifies the formatting of zone files during dump + when the <option>masterfile-format</option> is + <constant>text</constant>. (This option is ignored + with any other <option>masterfile-format</option>.) + </para> + <para> + When set to <constant>relative</constant>, + records are printed in a multi-line format with owner + names expressed relative to a shared origin. When set + to <constant>full</constant>, records are printed in + a single-line format with absolute owner names. + The <constant>full</constant> format is most suitable + when a zone file needs to be processed automatically + by a script. The <constant>relative</constant> format + is more human-readable, and is thus suitable when a + zone is to be edited by hand. The default is + <constant>relative</constant>. + </para> + </listitem> + </varlistentry> + + <varlistentry xml:id="max-recursion-depth"> + <term><command>max-recursion-depth</command></term> + <listitem> + <para> + Sets the maximum number of levels of recursion + that are permitted at any one time while servicing + a recursive query. Resolving a name may require + looking up a name server address, which in turn + requires resolving another name, etc; if the number + of indirections exceeds this value, the recursive + query is terminated and returns SERVFAIL. The + default is 7. + </para> + </listitem> + </varlistentry> + + <varlistentry xml:id="max-recursion-queries"> + <term><command>max-recursion-queries</command></term> + <listitem> + <para> + Sets the maximum number of iterative queries that + may be sent while servicing a recursive query. + If more queries are sent, the recursive query + is terminated and returns SERVFAIL. Queries to + look up top level domains such as "com" and "net" + and the DNS root zone are exempt from this limitation. + The default is 75. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>notify-delay</command></term> + <listitem> + <para> + The delay, in seconds, between sending sets of notify + messages for a zone. The default is five (5) seconds. + </para> + <para> + The overall rate that NOTIFY messages are sent for all + zones is controlled by <command>serial-query-rate</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>max-rsa-exponent-size</command></term> + <listitem> + <para> + The maximum RSA exponent size, in bits, that will + be accepted when validating. Valid values are 35 + to 4096 bits. The default zero (0) is also accepted + and is equivalent to 4096. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>prefetch</command></term> + <listitem> + <para> + When a query is received for cached data which + is to expire shortly, <command>named</command> can + refresh the data from the authoritative server + immediately, ensuring that the cache always has an + answer available. + </para> + <para> + The <option>prefetch</option> specifies the + "trigger" TTL value at which prefetch of the current + query will take place: when a cache record with a + lower TTL value is encountered during query processing, + it will be refreshed. Valid trigger TTL values are 1 to + 10 seconds. Values larger than 10 seconds will be silently + reduced to 10. + Setting a trigger TTL to zero (0) causes + prefetch to be disabled. + The default trigger TTL is <literal>2</literal>. + </para> + <para> + An optional second argument specifies the "eligibility" + TTL: the smallest <emphasis>original</emphasis> + TTL value that will be accepted for a record to be + eligible for prefetching. The eligibility TTL must + be at least six seconds longer than the trigger TTL; + if it isn't, <command>named</command> will silently + adjust it upward. + The default eligibility TTL is <literal>9</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>v6-bias</command></term> + <listitem> + <para> + When determining the next nameserver to try + preference IPv6 nameservers by this many milliseconds. + The default is <literal>50</literal> milliseconds. + </para> + </listitem> + </varlistentry> + </variablelist> + + </section> + + <section xml:id="builtin"><info><title>Built-in server information zones</title></info> + + <para> + The server provides some helpful diagnostic information + through a number of built-in zones under the + pseudo-top-level-domain <literal>bind</literal> in the + <command>CHAOS</command> class. These zones are part + of a + built-in view (see <xref linkend="view_statement_grammar"/>) of + class + <command>CHAOS</command> which is separate from the + default view of class <command>IN</command>. Most global + configuration options (<command>allow-query</command>, + etc) will apply to this view, but some are locally + overridden: <command>notify</command>, + <command>recursion</command> and + <command>allow-new-zones</command> are + always set to <userinput>no</userinput>, and + <command>rate-limit</command> is set to allow + three responses per second. + </para> + <para> + If you need to disable these zones, use the options + below, or hide the built-in <command>CHAOS</command> + view by + defining an explicit view of class <command>CHAOS</command> + that matches all clients. + </para> + + <variablelist> + + <varlistentry> + <term><command>version</command></term> + <listitem> + <para> + The version the server should report + via a query of the name <literal>version.bind</literal> + with type <command>TXT</command>, class <command>CHAOS</command>. + The default is the real version number of this server. + Specifying <command>version none</command> + disables processing of the queries. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>hostname</command></term> + <listitem> + <para> + The hostname the server should report via a query of + the name <filename>hostname.bind</filename> + with type <command>TXT</command>, class <command>CHAOS</command>. + This defaults to the hostname of the machine hosting the + name server as + found by the gethostname() function. The primary purpose of such queries + is to + identify which of a group of anycast servers is actually + answering your queries. Specifying <command>hostname none;</command> + disables processing of the queries. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>server-id</command></term> + <listitem> + <para> + The ID the server should report when receiving a Name + Server Identifier (NSID) query, or a query of the name + <filename>ID.SERVER</filename> with type + <command>TXT</command>, class <command>CHAOS</command>. + The primary purpose of such queries is to + identify which of a group of anycast servers is actually + answering your queries. Specifying <command>server-id none;</command> + disables processing of the queries. + Specifying <command>server-id hostname;</command> will cause <command>named</command> to + use the hostname as found by the gethostname() function. + The default <command>server-id</command> is <command>none</command>. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </section> + + <section xml:id="empty"><info><title>Built-in Empty Zones</title></info> + + <para> + The <command>named</command> server has some built-in + empty zones (SOA and NS records only). + These are for zones that should normally be answered locally + and which queries should not be sent to the Internet's root + servers. The official servers which cover these namespaces + return NXDOMAIN responses to these queries. In particular, + these cover the reverse namespaces for addresses from + RFC 1918, RFC 4193, RFC 5737 and RFC 6598. They also include the + reverse namespace for IPv6 local address (locally assigned), + IPv6 link local addresses, the IPv6 loopback address and the + IPv6 unknown address. + </para> + <para> + The server will attempt to determine if a built-in zone + already exists or is active (covered by a forward-only + forwarding declaration) and will not create an empty + zone in that case. + </para> + <para> + The current list of empty zones is: + <itemizedlist> + <listitem>10.IN-ADDR.ARPA</listitem> + <listitem>16.172.IN-ADDR.ARPA</listitem> + <listitem>17.172.IN-ADDR.ARPA</listitem> + <listitem>18.172.IN-ADDR.ARPA</listitem> + <listitem>19.172.IN-ADDR.ARPA</listitem> + <listitem>20.172.IN-ADDR.ARPA</listitem> + <listitem>21.172.IN-ADDR.ARPA</listitem> + <listitem>22.172.IN-ADDR.ARPA</listitem> + <listitem>23.172.IN-ADDR.ARPA</listitem> + <listitem>24.172.IN-ADDR.ARPA</listitem> + <listitem>25.172.IN-ADDR.ARPA</listitem> + <listitem>26.172.IN-ADDR.ARPA</listitem> + <listitem>27.172.IN-ADDR.ARPA</listitem> + <listitem>28.172.IN-ADDR.ARPA</listitem> + <listitem>29.172.IN-ADDR.ARPA</listitem> + <listitem>30.172.IN-ADDR.ARPA</listitem> + <listitem>31.172.IN-ADDR.ARPA</listitem> + <listitem>168.192.IN-ADDR.ARPA</listitem> + <listitem>64.100.IN-ADDR.ARPA</listitem> + <listitem>65.100.IN-ADDR.ARPA</listitem> + <listitem>66.100.IN-ADDR.ARPA</listitem> + <listitem>67.100.IN-ADDR.ARPA</listitem> + <listitem>68.100.IN-ADDR.ARPA</listitem> + <listitem>69.100.IN-ADDR.ARPA</listitem> + <listitem>70.100.IN-ADDR.ARPA</listitem> + <listitem>71.100.IN-ADDR.ARPA</listitem> + <listitem>72.100.IN-ADDR.ARPA</listitem> + <listitem>73.100.IN-ADDR.ARPA</listitem> + <listitem>74.100.IN-ADDR.ARPA</listitem> + <listitem>75.100.IN-ADDR.ARPA</listitem> + <listitem>76.100.IN-ADDR.ARPA</listitem> + <listitem>77.100.IN-ADDR.ARPA</listitem> + <listitem>78.100.IN-ADDR.ARPA</listitem> + <listitem>79.100.IN-ADDR.ARPA</listitem> + <listitem>80.100.IN-ADDR.ARPA</listitem> + <listitem>81.100.IN-ADDR.ARPA</listitem> + <listitem>82.100.IN-ADDR.ARPA</listitem> + <listitem>83.100.IN-ADDR.ARPA</listitem> + <listitem>84.100.IN-ADDR.ARPA</listitem> + <listitem>85.100.IN-ADDR.ARPA</listitem> + <listitem>86.100.IN-ADDR.ARPA</listitem> + <listitem>87.100.IN-ADDR.ARPA</listitem> + <listitem>88.100.IN-ADDR.ARPA</listitem> + <listitem>89.100.IN-ADDR.ARPA</listitem> + <listitem>90.100.IN-ADDR.ARPA</listitem> + <listitem>91.100.IN-ADDR.ARPA</listitem> + <listitem>92.100.IN-ADDR.ARPA</listitem> + <listitem>93.100.IN-ADDR.ARPA</listitem> + <listitem>94.100.IN-ADDR.ARPA</listitem> + <listitem>95.100.IN-ADDR.ARPA</listitem> + <listitem>96.100.IN-ADDR.ARPA</listitem> + <listitem>97.100.IN-ADDR.ARPA</listitem> + <listitem>98.100.IN-ADDR.ARPA</listitem> + <listitem>99.100.IN-ADDR.ARPA</listitem> + <listitem>100.100.IN-ADDR.ARPA</listitem> + <listitem>101.100.IN-ADDR.ARPA</listitem> + <listitem>102.100.IN-ADDR.ARPA</listitem> + <listitem>103.100.IN-ADDR.ARPA</listitem> + <listitem>104.100.IN-ADDR.ARPA</listitem> + <listitem>105.100.IN-ADDR.ARPA</listitem> + <listitem>106.100.IN-ADDR.ARPA</listitem> + <listitem>107.100.IN-ADDR.ARPA</listitem> + <listitem>108.100.IN-ADDR.ARPA</listitem> + <listitem>109.100.IN-ADDR.ARPA</listitem> + <listitem>110.100.IN-ADDR.ARPA</listitem> + <listitem>111.100.IN-ADDR.ARPA</listitem> + <listitem>112.100.IN-ADDR.ARPA</listitem> + <listitem>113.100.IN-ADDR.ARPA</listitem> + <listitem>114.100.IN-ADDR.ARPA</listitem> + <listitem>115.100.IN-ADDR.ARPA</listitem> + <listitem>116.100.IN-ADDR.ARPA</listitem> + <listitem>117.100.IN-ADDR.ARPA</listitem> + <listitem>118.100.IN-ADDR.ARPA</listitem> + <listitem>119.100.IN-ADDR.ARPA</listitem> + <listitem>120.100.IN-ADDR.ARPA</listitem> + <listitem>121.100.IN-ADDR.ARPA</listitem> + <listitem>122.100.IN-ADDR.ARPA</listitem> + <listitem>123.100.IN-ADDR.ARPA</listitem> + <listitem>124.100.IN-ADDR.ARPA</listitem> + <listitem>125.100.IN-ADDR.ARPA</listitem> + <listitem>126.100.IN-ADDR.ARPA</listitem> + <listitem>127.100.IN-ADDR.ARPA</listitem> + <listitem>0.IN-ADDR.ARPA</listitem> + <listitem>127.IN-ADDR.ARPA</listitem> + <listitem>254.169.IN-ADDR.ARPA</listitem> + <listitem>2.0.192.IN-ADDR.ARPA</listitem> + <listitem>100.51.198.IN-ADDR.ARPA</listitem> + <listitem>113.0.203.IN-ADDR.ARPA</listitem> + <listitem>255.255.255.255.IN-ADDR.ARPA</listitem> + <listitem>0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.ARPA</listitem> + <listitem>1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.ARPA</listitem> + <listitem>8.B.D.0.1.0.0.2.IP6.ARPA</listitem> + <listitem>D.F.IP6.ARPA</listitem> + <listitem>8.E.F.IP6.ARPA</listitem> + <listitem>9.E.F.IP6.ARPA</listitem> + <listitem>A.E.F.IP6.ARPA</listitem> + <listitem>B.E.F.IP6.ARPA</listitem> + <listitem>EMPTY.AS112.ARPA</listitem> + <listitem>HOME.ARPA</listitem> + </itemizedlist> + </para> + <para> + Empty zones are settable at the view level and only apply to + views of class IN. Disabled empty zones are only inherited + from options if there are no disabled empty zones specified + at the view level. To override the options list of disabled + zones, you can disable the root zone at the view level, for example: +<programlisting> + disable-empty-zone "."; +</programlisting> + </para> + <para> + If you are using the address ranges covered here, you should + already have reverse zones covering the addresses you use. + In practice this appears to not be the case with many queries + being made to the infrastructure servers for names in these + spaces. So many in fact that sacrificial servers were needed + to be deployed to channel the query load away from the + infrastructure servers. + </para> + <note><simpara> + The real parent servers for these zones should disable all + empty zone under the parent zone they serve. For the real + root servers, this is all built-in empty zones. This will + enable them to return referrals to deeper in the tree. + </simpara></note> + <variablelist> + <varlistentry> + <term><command>empty-server</command></term> + <listitem> + <para> + Specify what server name will appear in the returned + SOA record for empty zones. If none is specified, then + the zone's name will be used. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>empty-contact</command></term> + <listitem> + <para> + Specify what contact name will appear in the returned + SOA record for empty zones. If none is specified, then + "." will be used. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>empty-zones-enable</command></term> + <listitem> + <para> + Enable or disable all empty zones. By default, they + are enabled. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>disable-empty-zone</command></term> + <listitem> + <para> + Disable individual empty zones. By default, none are + disabled. This option can be specified multiple times. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section xml:id="acache"><info><title>Additional Section Caching</title></info> + + + <para> + The additional section cache, also called <command>acache</command>, + is an internal cache to improve the response performance of BIND 9. + When additional section caching is enabled, BIND 9 will + cache an internal short-cut to the additional section content for + each answer RR. + Note that <command>acache</command> is an internal caching + mechanism of BIND 9, and is not related to the DNS caching + server function. + </para> + + <para> + Additional section caching does not change the + response content (except the RRsets ordering of the additional + section, see below), but can improve the response performance + significantly. + It is particularly effective when BIND 9 acts as an authoritative + server for a zone that has many delegations with many glue RRs. + </para> + + <para> + In order to obtain the maximum performance improvement + from additional section caching, setting + <command>additional-from-cache</command> + to <command>no</command> is recommended, since the current + implementation of <command>acache</command> + does not short-cut of additional section information from the + DNS cache data. + </para> + + <para> + One obvious disadvantage of <command>acache</command> is + that it requires much more + memory for the internal cached data. + Thus, if the response performance does not matter and memory + consumption is much more critical, the + <command>acache</command> mechanism can be + disabled by setting <command>acache-enable</command> to + <command>no</command>. + It is also possible to specify the upper limit of memory + consumption + for acache by using <command>max-acache-size</command>. + </para> + + <para> + Additional section caching also has a minor effect on the + RRset ordering in the additional section. + Without <command>acache</command>, + <command>cyclic</command> order is effective for the additional + section as well as the answer and authority sections. + However, additional section caching fixes the ordering when it + first caches an RRset for the additional section, and the same + ordering will be kept in succeeding responses, regardless of the + setting of <command>rrset-order</command>. + The effect of this should be minor, however, since an + RRset in the additional section + typically only contains a small number of RRs (and in many cases + it only contains a single RR), in which case the + ordering does not matter much. + </para> + + <para> + The following is a summary of options related to + <command>acache</command>. + </para> + + <variablelist> + + <varlistentry> + <term><command>acache-enable</command></term> + <listitem> + <para> + If <command>yes</command>, additional section caching is + enabled. The default value is <command>no</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>acache-cleaning-interval</command></term> + <listitem> + <para> + The server will remove stale cache entries, based on an LRU + based + algorithm, every <command>acache-cleaning-interval</command> minutes. + The default is 60 minutes. + If set to 0, no periodic cleaning will occur. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>max-acache-size</command></term> + <listitem> + <para> + The maximum amount of memory in bytes to use for the server's acache. + When the amount of data in the acache reaches this limit, + the server + will clean more aggressively so that the limit is not + exceeded. + In a server with multiple views, the limit applies + separately to the + acache of each view. + The default is <literal>16M</literal>. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </section> + + <section xml:id="content_filtering"><info><title>Content Filtering</title></info> + + <para> + <acronym>BIND</acronym> 9 provides the ability to filter + out DNS responses from external DNS servers containing + certain types of data in the answer section. + Specifically, it can reject address (A or AAAA) records if + the corresponding IPv4 or IPv6 addresses match the given + <varname>address_match_list</varname> of the + <command>deny-answer-addresses</command> option. + It can also reject CNAME or DNAME records if the "alias" + name (i.e., the CNAME alias or the substituted query name + due to DNAME) matches the + given <varname>namelist</varname> of the + <command>deny-answer-aliases</command> option, where + "match" means the alias name is a subdomain of one of + the <varname>name_list</varname> elements. + If the optional <varname>namelist</varname> is specified + with <command>except-from</command>, records whose query name + matches the list will be accepted regardless of the filter + setting. + Likewise, if the alias name is a subdomain of the + corresponding zone, the <command>deny-answer-aliases</command> + filter will not apply; + for example, even if "example.com" is specified for + <command>deny-answer-aliases</command>, + </para> +<programlisting>www.example.com. CNAME xxx.example.com.</programlisting> + + <para> + returned by an "example.com" server will be accepted. + </para> + + <para> + In the <varname>address_match_list</varname> of the + <command>deny-answer-addresses</command> option, only + <varname>ip_addr</varname> + and <varname>ip_prefix</varname> + are meaningful; + any <varname>key_id</varname> will be silently ignored. + </para> + + <para> + If a response message is rejected due to the filtering, + the entire message is discarded without being cached, and + a SERVFAIL error will be returned to the client. + </para> + + <para> + This filtering is intended to prevent "DNS rebinding attacks," in + which an attacker, in response to a query for a domain name the + attacker controls, returns an IP address within your own network or + an alias name within your own domain. + A naive web browser or script could then serve as an + unintended proxy, allowing the attacker + to get access to an internal node of your local network + that couldn't be externally accessed otherwise. + See the paper available at + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://portal.acm.org/citation.cfm?id=1315245.1315298"> + http://portal.acm.org/citation.cfm?id=1315245.1315298 + </link> + for more details about the attacks. + </para> + + <para> + For example, if you own a domain named "example.net" and + your internal network uses an IPv4 prefix 192.0.2.0/24, + you might specify the following rules: + </para> + +<programlisting>deny-answer-addresses { 192.0.2.0/24; } except-from { "example.net"; }; +deny-answer-aliases { "example.net"; }; +</programlisting> + + <para> + If an external attacker lets a web browser in your local + network look up an IPv4 address of "attacker.example.com", + the attacker's DNS server would return a response like this: + </para> + +<programlisting>attacker.example.com. A 192.0.2.1</programlisting> + + <para> + in the answer section. + Since the rdata of this record (the IPv4 address) matches + the specified prefix 192.0.2.0/24, this response will be + ignored. + </para> + + <para> + On the other hand, if the browser looks up a legitimate + internal web server "www.example.net" and the + following response is returned to + the <acronym>BIND</acronym> 9 server + </para> + +<programlisting>www.example.net. A 192.0.2.2</programlisting> + + <para> + it will be accepted since the owner name "www.example.net" + matches the <command>except-from</command> element, + "example.net". + </para> + + <para> + Note that this is not really an attack on the DNS per se. + In fact, there is nothing wrong for an "external" name to + be mapped to your "internal" IP address or domain name + from the DNS point of view. + It might actually be provided for a legitimate purpose, + such as for debugging. + As long as the mapping is provided by the correct owner, + it is not possible or does not make sense to detect + whether the intent of the mapping is legitimate or not + within the DNS. + The "rebinding" attack must primarily be protected at the + application that uses the DNS. + For a large site, however, it may be difficult to protect + all possible applications at once. + This filtering feature is provided only to help such an + operational environment; + it is generally discouraged to turn it on unless you are + very sure you have no other choice and the attack is a + real threat for your applications. + </para> + + <para> + Care should be particularly taken if you want to use this + option for addresses within 127.0.0.0/8. + These addresses are obviously "internal", but many + applications conventionally rely on a DNS mapping from + some name to such an address. + Filtering out DNS records containing this address + spuriously can break such applications. + </para> + </section> + + <section xml:id="rpz"><info><title>Response Policy Zone (RPZ) Rewriting</title></info> + + <para> + <acronym>BIND</acronym> 9 includes a limited + mechanism to modify DNS responses for requests + analogous to email anti-spam DNS blacklists. + Responses can be changed to deny the existence of domains (NXDOMAIN), + deny the existence of IP addresses for domains (NODATA), + or contain other IP addresses or data. + </para> + + <para> + Response policy zones are named in the + <command>response-policy</command> option for the view or among the + global options if there is no response-policy option for the view. + Response policy zones are ordinary DNS zones containing RRsets + that can be queried normally if allowed. + It is usually best to restrict those queries with something like + <command>allow-query { localhost; };</command>. + Note that zones using <command>masterfile-format map</command> + cannot be used as policy zones. + </para> + + <para> + A <command>response-policy</command> option can support + multiple policy zones. To maximize performance, a radix + tree is used to quickly identify response policy zones + containing triggers that match the current query. This + imposes an upper limit of 32 on the number of policy zones + in a single <command>response-policy</command> option; more + than that is a configuration error. + </para> + + <para> + Five policy triggers can be encoded in RPZ records. + <variablelist> + <varlistentry> + <term><command>RPZ-CLIENT-IP</command></term> + <listitem> + <para> + IP records are triggered by the IP address of the + DNS client. + Client IP address triggers are encoded in records that have + owner names that are subdomains of + <command>rpz-client-ip</command> relativized to the + policy zone origin name + and encode an address or address block. + IPv4 addresses are represented as + <userinput>prefixlength.B4.B3.B2.B1.rpz-client-ip</userinput>. + The IPv4 prefix length must be between 1 and 32. + All four bytes, B4, B3, B2, and B1, must be present. + B4 is the decimal value of the least significant byte of the + IPv4 address as in IN-ADDR.ARPA. + </para> + + <para> + IPv6 addresses are encoded in a format similar + to the standard IPv6 text representation, + <userinput>prefixlength.W8.W7.W6.W5.W4.W3.W2.W1.rpz-client-ip</userinput>. + Each of W8,...,W1 is a one to four digit hexadecimal number + representing 16 bits of the IPv6 address as in the standard + text representation of IPv6 addresses, but reversed as in + IP6.ARPA. (Note that this representation of IPv6 + address is different from IP6.ARPA where each hex + digit occupies a label.) + All 8 words must be present except when one set of consecutive + zero words is replaced with <userinput>.zz.</userinput> + analogous to double colons (::) in standard IPv6 text + encodings. + The IPv6 prefix length must be between 1 and 128. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>QNAME</command></term> + <listitem> + <para> + QNAME policy records are triggered by query names of + requests and targets of CNAME records resolved to generate + the response. + The owner name of a QNAME policy record is + the query name relativized to the policy zone. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>RPZ-IP</command></term> + <listitem> + <para> + IP triggers are IP addresses in an + A or AAAA record in the ANSWER section of a response. + They are encoded like client-IP triggers except as + subdomains of <command>rpz-ip</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>RPZ-NSDNAME</command></term> + <listitem> + <para> + NSDNAME triggers match names of authoritative servers + for the query name, a parent of the query name, a CNAME for + query name, or a parent of a CNAME. + They are encoded as subdomains of + <command>rpz-nsdname</command> relativized + to the RPZ origin name. + NSIP triggers match IP addresses in A and + AAAA RRsets for domains that can be checked against NSDNAME + policy records. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>RPZ-NSIP</command></term> + <listitem> + <para> + NSIP triggers match the IP addresses of authoritative + servers. They are enncoded like IP triggers, except as + subdomains of <command>rpz-nsip</command>. + NSDNAME and NSIP triggers are checked only for names with at + least <command>min-ns-dots</command> dots. + The default value of <command>min-ns-dots</command> is + 1, to exclude top level domains. + </para> + <para> + If a name server's IP address is not yet known, + <command>named</command> will recursively look up + the IP address before applying an RPZ-NSIP rule. + This can cause a processing delay. To speed up + processing at the cost of precision, the + <command>nsip-wait-recurse</command> option + can be used: when set to <userinput>no</userinput>, + RPZ-NSIP rules will only be applied when a name + servers's IP address has already been looked up and + cached. If a server's IP address is not in the + cache, then the RPZ-NSIP rule will be ignored, + but the address will be looked up in the + background, and the rule will be applied + to subsequent queries. The default is + <userinput>yes</userinput>, meaning RPZ-NSIP + rules should always be applied even if an + address needs to be looked up first. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + The query response is checked against all response policy zones, + so two or more policy records can be triggered by a response. + Because DNS responses are rewritten according to at most one + policy record, a single record encoding an action (other than + <command>DISABLED</command> actions) must be chosen. + Triggers or the records that encode them are chosen for the + rewriting in the following order: + <orderedlist inheritnum="ignore" continuation="restarts"> + <listitem>Choose the triggered record in the zone that appears + first in the <command>response-policy</command> option. + </listitem> + <listitem>Prefer CLIENT-IP to QNAME to IP to NSDNAME to NSIP + triggers in a single zone. + </listitem> + <listitem>Among NSDNAME triggers, prefer the + trigger that matches the smallest name under the DNSSEC ordering. + </listitem> + <listitem>Among IP or NSIP triggers, prefer the trigger + with the longest prefix. + </listitem> + <listitem>Among triggers with the same prefix length, + prefer the IP or NSIP trigger that matches + the smallest IP address. + </listitem> + </orderedlist> + </para> + + <para> + When the processing of a response is restarted to resolve + DNAME or CNAME records and a policy record set has + not been triggered, + all response policy zones are again consulted for the + DNAME or CNAME names and addresses. + </para> + + <para> + RPZ record sets are any types of DNS record except + DNAME or DNSSEC that encode actions or responses to + individual queries. + Any of the policies can be used with any of the triggers. + For example, while the <command>TCP-only</command> policy is + commonly used with <command>client-IP</command> triggers, + it can be used with any type of trigger to force the use of + TCP for responses with owner names in a zone. + <variablelist> + <varlistentry> + <term><command>PASSTHRU</command></term> + <listitem> + <para> + The whitelist policy is specified + by a CNAME whose target is <command>rpz-passthru</command>. + It causes the response to not be rewritten + and is most often used to "poke holes" in policies for + CIDR blocks. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>DROP</command></term> + <listitem> + <para> + The blacklist policy is specified + by a CNAME whose target is <command>rpz-drop</command>. + It causes the response to be discarded. + Nothing is sent to the DNS client. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>TCP-Only</command></term> + <listitem> + <para> + The "slip" policy is specified + by a CNAME whose target is <command>rpz-tcp-only</command>. + It changes UDP responses to short, truncated DNS responses + that require the DNS client to try again with TCP. + It is used to mitigate distributed DNS reflection attacks. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>NXDOMAIN</command></term> + <listitem> + <para> + The domain undefined response is encoded + by a CNAME whose target is the root domain (.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>NODATA</command></term> + <listitem> + <para> + The empty set of resource records is specified by + CNAME whose target is the wildcard top-level + domain (*.). + It rewrites the response to NODATA or ANCOUNT=1. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>Local Data</command></term> + <listitem> + <para> + A set of ordinary DNS records can be used to answer queries. + Queries for record types not the set are answered with + NODATA. + </para> + + <para> + A special form of local data is a CNAME whose target is a + wildcard such as *.example.com. + It is used as if were an ordinary CNAME after the asterisk (*) + has been replaced with the query name. + The purpose for this special form is query logging in the + walled garden's authority DNS server. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + All of the actions specified in all of the individual records + in a policy zone + can be overridden with a <command>policy</command> clause in the + <command>response-policy</command> option. + An organization using a policy zone provided by another + organization might use this mechanism to redirect domains + to its own walled garden. + <variablelist> + <varlistentry> + <term><command>GIVEN</command></term> + <listitem> + <para>The placeholder policy says "do not override but + perform the action specified in the zone." + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>DISABLED</command></term> + <listitem> + <para> + The testing override policy causes policy zone records to do + nothing but log what they would have done if the + policy zone were not disabled. + The response to the DNS query will be written (or not) + according to any triggered policy records that are not + disabled. + Disabled policy zones should appear first, + because they will often not be logged + if a higher precedence trigger is found first. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>PASSTHRU</command></term>, + <term><command>DROP</command></term>, + <term><command>TCP-Only</command></term>, + <term><command>NXDOMAIN</command></term>, + and + <term><command>NODATA</command></term> + <listitem> + <para> + override with the corresponding per-record policy. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>CNAME domain</command></term> + <listitem> + <para> + causes all RPZ policy records to act as if they were + "cname domain" records. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + By default, the actions encoded in a response policy zone + are applied only to queries that ask for recursion (RD=1). + That default can be changed for a single policy zone or + all response policy zones in a view + with a <command>recursive-only no</command> clause. + This feature is useful for serving the same zone files + both inside and outside an RFC 1918 cloud and using RPZ to + delete answers that would otherwise contain RFC 1918 values + on the externally visible name server or view. + </para> + + <para> + Also by default, RPZ actions are applied only to DNS requests + that either do not request DNSSEC metadata (DO=0) or when no + DNSSEC records are available for request name in the original + zone (not the response policy zone). This default can be + changed for all response policy zones in a view with a + <command>break-dnssec yes</command> clause. In that case, RPZ + actions are applied regardless of DNSSEC. The name of the + clause option reflects the fact that results rewritten by RPZ + actions cannot verify. + </para> + + <para> + No DNS records are needed for a QNAME or Client-IP trigger. + The name or IP address itself is sufficient, + so in principle the query name need not be recursively resolved. + However, not resolving the requested + name can leak the fact that response policy rewriting is in use + and that the name is listed in a policy zone to operators of + servers for listed names. To prevent that information leak, by + default any recursion needed for a request is done before any + policy triggers are considered. Because listed domains often + have slow authoritative servers, this default behavior can cost + significant time. + The <command>qname-wait-recurse no</command> option + overrides that default behavior when recursion cannot + change a non-error response. + The option does not affect QNAME or client-IP triggers + in policy zones listed + after other zones containing IP, NSIP and NSDNAME triggers, because + those may depend on the A, AAAA, and NS records that would be + found during recursive resolution. It also does not affect + DNSSEC requests (DO=1) unless <command>break-dnssec yes</command> + is in use, because the response would depend on whether or not + RRSIG records were found during resolution. + Using this option can cause error responses such as SERVFAIL to + appear to be rewritten, since no recursion is being done to + discover problems at the authoritative server. + </para> + + <para> + The TTL of a record modified by RPZ policies is set from the + TTL of the relevant record in policy zone. It is then limited + to a maximum value. + The <command>max-policy-ttl</command> clause changes the + maximum seconds from its default of 5. + </para> + + <para> + For example, you might use this option statement + </para> +<programlisting> response-policy { zone "badlist"; };</programlisting> + <para> + and this zone statement + </para> +<programlisting> zone "badlist" {type master; file "master/badlist"; allow-query {none;}; };</programlisting> + <para> + with this zone file + </para> +<programlisting>$TTL 1H +@ SOA LOCALHOST. named-mgr.example.com (1 1h 15m 30d 2h) + NS LOCALHOST. + +; QNAME policy records. There are no periods (.) after the owner names. +nxdomain.domain.com CNAME . ; NXDOMAIN policy +*.nxdomain.domain.com CNAME . ; NXDOMAIN policy +nodata.domain.com CNAME *. ; NODATA policy +*.nodata.domain.com CNAME *. ; NODATA policy +bad.domain.com A 10.0.0.1 ; redirect to a walled garden + AAAA 2001:2::1 +bzone.domain.com CNAME garden.example.com. + +; do not rewrite (PASSTHRU) OK.DOMAIN.COM +ok.domain.com CNAME rpz-passthru. + +; redirect x.bzone.domain.com to x.bzone.domain.com.garden.example.com +*.bzone.domain.com CNAME *.garden.example.com. + + +; IP policy records that rewrite all responses containing A records in 127/8 +; except 127.0.0.1 +8.0.0.0.127.rpz-ip CNAME . +32.1.0.0.127.rpz-ip CNAME rpz-passthru. + +; NSDNAME and NSIP policy records +ns.domain.com.rpz-nsdname CNAME . +48.zz.2.2001.rpz-nsip CNAME . + +; blacklist and whitelist some DNS clients +112.zz.2001.rpz-client-ip CNAME rpz-drop. +8.0.0.0.127.rpz-client-ip CNAME rpz-drop. + +; force some DNS clients and responses in the example.com zone to TCP +16.0.0.1.10.rpz-client-ip CNAME rpz-tcp-only. +example.com CNAME rpz-tcp-only. +*.example.com CNAME rpz-tcp-only. + +</programlisting> + <para> + RPZ can affect server performance. + Each configured response policy zone requires the server to + perform one to four additional database lookups before a + query can be answered. + For example, a DNS server with four policy zones, each with all + four kinds of response triggers, QNAME, IP, NSIP, and + NSDNAME, requires a total of 17 times as many database + lookups as a similar DNS server with no response policy zones. + A <acronym>BIND9</acronym> server with adequate memory and one + response policy zone with QNAME and IP triggers might achieve a + maximum queries-per-second rate about 20% lower. + A server with four response policy zones with QNAME and IP + triggers might have a maximum QPS rate about 50% lower. + </para> + + <para> + Responses rewritten by RPZ are counted in the + <command>RPZRewrites</command> statistics. + </para> + + <para> + The <command>log</command> clause can be used to optionally + turn off rewrite logging for a particular response policy + zone. By default, all rewrites are logged. + </para> + </section> + + <section xml:id="rrl"><info><title>Response Rate Limiting</title></info> + + <para> + Excessive almost identical UDP <emphasis>responses</emphasis> + can be controlled by configuring a + <command>rate-limit</command> clause in an + <command>options</command> or <command>view</command> statement. + This mechanism keeps authoritative BIND 9 from being used + in amplifying reflection denial of service (DoS) attacks. + Short truncated (TC=1) responses can be sent to provide + rate-limited responses to legitimate clients within + a range of forged, attacked IP addresses. + Legitimate clients react to dropped or truncated response + by retrying with UDP or with TCP respectively. + </para> + + <para> + This mechanism is intended for authoritative DNS servers. + It can be used on recursive servers but can slow + applications such as SMTP servers (mail receivers) and + HTTP clients (web browsers) that repeatedly request the + same domains. + When possible, closing "open" recursive servers is better. + </para> + + <para> + Response rate limiting uses a "credit" or "token bucket" scheme. + Each combination of identical response and client + has a conceptual account that earns a specified number + of credits every second. + A prospective response debits its account by one. + Responses are dropped or truncated + while the account is negative. + Responses are tracked within a rolling window of time + which defaults to 15 seconds, but can be configured with + the <command>window</command> option to any value from + 1 to 3600 seconds (1 hour). + The account cannot become more positive than + the per-second limit + or more negative than <command>window</command> + times the per-second limit. + When the specified number of credits for a class of + responses is set to 0, those responses are not rate limited. + </para> + + <para> + The notions of "identical response" and "DNS client" + for rate limiting are not simplistic. + All responses to an address block are counted as if to a + single client. + The prefix lengths of addresses blocks are + specified with <command>ipv4-prefix-length</command> (default 24) + and <command>ipv6-prefix-length</command> (default 56). + </para> + + <para> + All non-empty responses for a valid domain name (qname) + and record type (qtype) are identical and have a limit specified + with <command>responses-per-second</command> + (default 0 or no limit). + All empty (NODATA) responses for a valid domain, + regardless of query type, are identical. + Responses in the NODATA class are limited by + <command>nodata-per-second</command> + (default <command>responses-per-second</command>). + Requests for any and all undefined subdomains of a given + valid domain result in NXDOMAIN errors, and are identical + regardless of query type. + They are limited by <command>nxdomains-per-second</command> + (default <command>responses-per-second</command>). + This controls some attacks using random names, but + can be relaxed or turned off (set to 0) + on servers that expect many legitimate + NXDOMAIN responses, such as from anti-spam blacklists. + Referrals or delegations to the server of a given + domain are identical and are limited by + <command>referrals-per-second</command> + (default <command>responses-per-second</command>). + </para> + + <para> + Responses generated from local wildcards are counted and limited + as if they were for the parent domain name. + This controls flooding using random.wild.example.com. + </para> + + <para> + All requests that result in DNS errors other + than NXDOMAIN, such as SERVFAIL and FORMERR, are identical + regardless of requested name (qname) or record type (qtype). + This controls attacks using invalid requests or distant, + broken authoritative servers. + By default the limit on errors is the same as the + <command>responses-per-second</command> value, + but it can be set separately with + <command>errors-per-second</command>. + </para> + + <para> + Many attacks using DNS involve UDP requests with forged source + addresses. + Rate limiting prevents the use of BIND 9 to flood a network + with responses to requests with forged source addresses, + but could let a third party block responses to legitimate requests. + There is a mechanism that can answer some legitimate + requests from a client whose address is being forged in a flood. + Setting <command>slip</command> to 2 (its default) causes every + other UDP request to be answered with a small truncated (TC=1) + response. + The small size and reduced frequency, and so lack of + amplification, of "slipped" responses make them unattractive + for reflection DoS attacks. + <command>slip</command> must be between 0 and 10. + A value of 0 does not "slip": + no truncated responses are sent due to rate limiting, + all responses are dropped. + A value of 1 causes every response to slip; + values between 2 and 10 cause every n'th response to slip. + Some error responses including REFUSED and SERVFAIL + cannot be replaced with truncated responses and are instead + leaked at the <command>slip</command> rate. + </para> + + <para> + (NOTE: Dropped responses from an authoritative server may + reduce the difficulty of a third party successfully forging + a response to a recursive resolver. The best security + against forged responses is for authoritative operators + to sign their zones using DNSSEC and for resolver operators + to validate the responses. When this is not an option, + operators who are more concerned with response integrity + than with flood mitigation may consider setting + <command>slip</command> to 1, causing all rate-limited + responses to be truncated rather than dropped. This reduces + the effectiveness of rate-limiting against reflection attacks.) + </para> + + <para> + When the approximate query per second rate exceeds + the <command>qps-scale</command> value, + then the <command>responses-per-second</command>, + <command>errors-per-second</command>, + <command>nxdomains-per-second</command> and + <command>all-per-second</command> values are reduced by the + ratio of the current rate to the <command>qps-scale</command> value. + This feature can tighten defenses during attacks. + For example, with + <command>qps-scale 250; responses-per-second 20;</command> and + a total query rate of 1000 queries/second for all queries from + all DNS clients including via TCP, + then the effective responses/second limit changes to + (250/1000)*20 or 5. + Responses sent via TCP are not limited + but are counted to compute the query per second rate. + </para> + + <para> + Rate limiters for different name spaces maintain + separate counters: If, for example, there is a + <command>rate-limit</command> statement for "com" and + another for "example.com", queries matching "example.com" + will not be debited against the rate limiter for "com". + </para> + + <para> + If a <command>rate-limit</command> statement does not specify a + <command>domain</command>, then it applies to the root domain + (".") and thus affects the entire DNS namespace, except those + portions covered by other <command>rate-limit</command> + statements. + </para> + + <para> + Communities of DNS clients can be given their own parameters or no + rate limiting by putting + <command>rate-limit</command> statements in <command>view</command> + statements instead of the global <command>option</command> + statement. + A <command>rate-limit</command> statement in a view replaces, + rather than supplementing, a <command>rate-limit</command> + statement among the main options. + DNS clients within a view can be exempted from rate limits + with the <command>exempt-clients</command> clause. + </para> + + <para> + UDP responses of all kinds can be limited with the + <command>all-per-second</command> phrase. This rate + limiting is unlike the rate limiting provided by + <command>responses-per-second</command>, + <command>errors-per-second</command>, and + <command>nxdomains-per-second</command> on a DNS server + which are often invisible to the victim of a DNS + reflection attack. Unless the forged requests of the + attack are the same as the legitimate requests of the + victim, the victim's requests are not affected. Responses + affected by an <command>all-per-second</command> limit + are always dropped; the <command>slip</command> value + has no effect. An <command>all-per-second</command> + limit should be at least 4 times as large as the other + limits, because single DNS clients often send bursts + of legitimate requests. For example, the receipt of a + single mail message can prompt requests from an SMTP + server for NS, PTR, A, and AAAA records as the incoming + SMTP/TCP/IP connection is considered. The SMTP server + can need additional NS, A, AAAA, MX, TXT, and SPF records + as it considers the STMP <command>Mail From</command> + command. Web browsers often repeatedly resolve the + same names that are repeated in HTML <IMG> tags + in a page. <command>all-per-second</command> is similar + to the rate limiting offered by firewalls but often + inferior. Attacks that justify ignoring the contents + of DNS responses are likely to be attacks on the DNS + server itself. They usually should be discarded before + the DNS server spends resources make TCP connections + or parsing DNS requests, but that rate limiting must + be done before the DNS server sees the requests. + </para> + + <para> + The maximum size of the table used to track requests and + rate limit responses is set with <command>max-table-size</command>. + Each entry in the table is between 40 and 80 bytes. + The table needs approximately as many entries as the number + of requests received per second. + The default is 20,000. + To reduce the cold start of growing the table, + <command>min-table-size</command> (default 500) + can set the minimum table size. + Enable <command>rate-limit</command> category logging to monitor + expansions of the table and inform + choices for the initial and maximum table size. + </para> + + <para> + Use <command>log-only yes</command> to test rate limiting parameters + without actually dropping any requests. + </para> + + <para> + Responses dropped by rate limits are included in the + <command>RateDropped</command> and <command>QryDropped</command> + statistics. + Responses that truncated by rate limits are included in + <command>RateSlipped</command> and <command>RespTruncated</command>. + </para> + </section> + + <section title="NXDOMAIN Redirection"><info/> + <para> + Named supports NXDOMAIN redirection via two methods: + <itemizedlist> + <listitem>Redirect zone <xref linkend="zone_statement_grammar"/></listitem> + <listitem>Redirect namespace</listitem> + </itemizedlist> + </para> + <para> + With both methods when named gets a NXDOMAIN response + it examines a separate namespace to see if the NXDOMAIN + response should be replaced with an alternative response. + </para> + <para> + With a redirect zone (<command>zone "." { type redirect; };</command>), the + data used to replace the NXDOMAIN is held in a single + zone which is not part of the normal namespace. All the + redirect information is contained in the zone; there are + no delegations. + </para> + <para> + With a redirect namespace (<command>option { nxdomain-redirect + <suffix> };</command>) the data used to replace the + NXDOMAIN is part of the normal namespace and is looked up by + appending the specified suffix to the original query name. + This roughly doubles the cache required to process NXDOMAIN + responses as you have the original NXDOMAIN response and + the replacement data or a NXDOMAIN indicating that there + is no replacement. + </para> + <para> + If both a redirect zone and a redirect namespace are configured, + the redirect zone is tried first. + </para> + </section> + </section> + + <section xml:id="server_statement_grammar"><info><title><command>server</command> Statement Grammar</title></info> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="server.grammar.xml"/> + </section> + + <section xml:id="server_statement_definition_and_usage"><info><title><command>server</command> Statement Definition and + Usage</title></info> + + <para> + The <command>server</command> statement defines + characteristics + to be associated with a remote name server. If a prefix length is + specified, then a range of servers is covered. Only the most + specific + server clause applies regardless of the order in + <filename>named.conf</filename>. + </para> + + <para> + The <command>server</command> statement can occur at + the top level of the + configuration file or inside a <command>view</command> + statement. + If a <command>view</command> statement contains + one or more <command>server</command> statements, only + those + apply to the view and any top-level ones are ignored. + If a view contains no <command>server</command> + statements, + any top-level <command>server</command> statements are + used as + defaults. + </para> + + <para> + If you discover that a remote server is giving out bad data, + marking it as bogus will prevent further queries to it. The + default + value of <command>bogus</command> is <command>no</command>. + </para> + <para> + The <command>provide-ixfr</command> clause determines + whether + the local server, acting as master, will respond with an + incremental + zone transfer when the given remote server, a slave, requests it. + If set to <command>yes</command>, incremental transfer + will be provided + whenever possible. If set to <command>no</command>, + all transfers + to the remote server will be non-incremental. If not set, the + value + of the <command>provide-ixfr</command> option in the + view or + global options block is used as a default. + </para> + + <para> + The <command>request-ixfr</command> clause determines + whether + the local server, acting as a slave, will request incremental zone + transfers from the given remote server, a master. If not set, the + value of the <command>request-ixfr</command> option in + the view or global options block is used as a default. It may + also be set in the zone block and, if set there, it will + override the global or view setting for that zone. + </para> + + <para> + IXFR requests to servers that do not support IXFR will + automatically + fall back to AXFR. Therefore, there is no need to manually list + which servers support IXFR and which ones do not; the global + default + of <command>yes</command> should always work. + The purpose of the <command>provide-ixfr</command> and + <command>request-ixfr</command> clauses is + to make it possible to disable the use of IXFR even when both + master + and slave claim to support it, for example if one of the servers + is buggy and crashes or corrupts data when IXFR is used. + </para> + + <para> + The <command>request-expire</command> clause determines + whether the local server, when acting as a slave, will + request the EDNS EXPIRE value. The EDNS EXPIRE value + indicates the remaining time before the zone data will + expire and need to be be refreshed. This is used + when a secondary server transfers a zone from another + secondary server; when transferring from the primary, the + expiration timer is set from the EXPIRE field of the SOA + record instead. + The default is <command>yes</command>. + </para> + + <para> + The <command>edns</command> clause determines whether + the local server will attempt to use EDNS when communicating + with the remote server. The default is <command>yes</command>. + </para> + + <para> + The <command>edns-udp-size</command> option sets the + EDNS UDP size that is advertised by <command>named</command> + when querying the remote server. Valid values are 512 + to 4096 bytes (values outside this range will be silently + adjusted to the nearest value within it). This option + is useful when you wish to advertise a different value + to this server than the value you advertise globally, + for example, when there is a firewall at the remote + site that is blocking large replies. (Note: Currently, + this sets a single UDP size for all packets sent to the + server; <command>named</command> will not deviate from + this value. This differs from the behavior of + <command>edns-udp-size</command> in <command>options</command> + or <command>view</command> statements, where it specifies + a maximum value. The <command>server</command> statement + behavior may be brought into conformance with the + <command>options/view</command> behavior in future releases.) + </para> + + <para> + The <command>edns-version</command> option sets the + maximum EDNS VERSION that will be sent to the server(s) + by the resolver. The actual EDNS version sent is still + subject to normal EDNS version negotiation rules (see + RFC 6891), the maximum EDNS version supported by the + server, and any other heuristics that indicate that a + lower version should be sent. This option is intended + to be used when a remote server reacts badly to a given + EDNS version or higher; it should be set to the highest + version the remote server is known to support. Valid + values are 0 to 255; higher values will be silently + adjusted. This option will not be needed until higher + EDNS versions than 0 are in use. + </para> + + <para> + The <command>max-udp-size</command> option sets the + maximum EDNS UDP message size <command>named</command> + will send. Valid values are 512 to 4096 bytes (values + outside this range will be silently adjusted). This + option is useful when you know that there is a firewall + that is blocking large replies from <command>named</command>. + </para> + + <para> + The <command>tcp-only</command> option sets the transport + protocol to TCP. The default is to use the UDP transport + and to fallback on TCP only when a truncated response + is received. + </para> + + <para> + The server supports two zone transfer methods. The first, <command>one-answer</command>, + uses one DNS message per resource record transferred. <command>many-answers</command> packs + as many resource records as possible into a message. <command>many-answers</command> is + more efficient, but is only known to be understood by <acronym>BIND</acronym> 9, <acronym>BIND</acronym> + 8.x, and patched versions of <acronym>BIND</acronym> + 4.9.5. You can specify which method + to use for a server with the <command>transfer-format</command> option. + If <command>transfer-format</command> is not + specified, the <command>transfer-format</command> + specified + by the <command>options</command> statement will be + used. + </para> + + <para><command>transfers</command> + is used to limit the number of concurrent inbound zone + transfers from the specified server. If no + <command>transfers</command> clause is specified, the + limit is set according to the + <command>transfers-per-ns</command> option. + </para> + + <para> + The <command>keys</command> clause identifies a + <command>key_id</command> defined by the <command>key</command> statement, + to be used for transaction security (TSIG, <xref linkend="tsig"/>) + when talking to the remote server. + When a request is sent to the remote server, a request signature + will be generated using the key specified here and appended to the + message. A request originating from the remote server is not + required + to be signed by this key. + </para> + + <para> + Only a single key per server is currently supported. + </para> + + <para> + The <command>transfer-source</command> and + <command>transfer-source-v6</command> clauses specify + the IPv4 and IPv6 source + address to be used for zone transfer with the remote server, + respectively. + For an IPv4 remote server, only <command>transfer-source</command> can + be specified. + Similarly, for an IPv6 remote server, only + <command>transfer-source-v6</command> can be + specified. + For more details, see the description of + <command>transfer-source</command> and + <command>transfer-source-v6</command> in + <xref linkend="zone_transfers"/>. + </para> + + <para> + The <command>notify-source</command> and + <command>notify-source-v6</command> clauses specify the + IPv4 and IPv6 source address to be used for notify + messages sent to remote servers, respectively. For an + IPv4 remote server, only <command>notify-source</command> + can be specified. Similarly, for an IPv6 remote server, + only <command>notify-source-v6</command> can be specified. + </para> + + <para> + The <command>query-source</command> and + <command>query-source-v6</command> clauses specify the + IPv4 and IPv6 source address to be used for queries + sent to remote servers, respectively. For an IPv4 + remote server, only <command>query-source</command> can + be specified. Similarly, for an IPv6 remote server, + only <command>query-source-v6</command> can be specified. + </para> + + <para> + The <command>request-nsid</command> clause determines + whether the local server will add a NSID EDNS option + to requests sent to the server. This overrides + <command>request-nsid</command> set at the view or + option level. + </para> + + <para> + The <command>send-cookie</command> clause determines + whether the local server will add a COOKIE EDNS option + to requests sent to the server. This overrides + <command>send-cookie</command> set at the view or + option level. The <command>named</command> server may + determine that COOKIE is not supported by the remote server + and not add a COOKIE EDNS option to requests. + </para> + </section> + + <section xml:id="statschannels"><info><title><command>statistics-channels</command> Statement Grammar</title></info> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="statistics-channels.grammar.xml"/> + </section> + + <section xml:id="statistics_channels"><info><title><command>statistics-channels</command> Statement Definition and + Usage</title></info> + + <para> + The <command>statistics-channels</command> statement + declares communication channels to be used by system + administrators to get access to statistics information of + the name server. + </para> + + <para> + This statement intends to be flexible to support multiple + communication protocols in the future, but currently only + HTTP access is supported. + It requires that BIND 9 be compiled with libxml2 and/or + json-c (also known as libjson0); the + <command>statistics-channels</command> statement is + still accepted even if it is built without the library, + but any HTTP access will fail with an error. + </para> + + <para> + An <command>inet</command> control channel is a TCP socket + listening at the specified <command>ip_port</command> on the + specified <command>ip_addr</command>, which can be an IPv4 or IPv6 + address. An <command>ip_addr</command> of <literal>*</literal> + (asterisk) is + interpreted as the IPv4 wildcard address; connections will be + accepted on any of the system's IPv4 addresses. + To listen on the IPv6 wildcard address, + use an <command>ip_addr</command> of <literal>::</literal>. + </para> + + <para> + If no port is specified, port 80 is used for HTTP channels. + The asterisk "<literal>*</literal>" cannot be used for + <command>ip_port</command>. + </para> + + <para> + The attempt of opening a statistics channel is + restricted by the optional <command>allow</command> clause. + Connections to the statistics channel are permitted based on the + <command>address_match_list</command>. + If no <command>allow</command> clause is present, + <command>named</command> accepts connection + attempts from any address; since the statistics may + contain sensitive internal information, it is highly + recommended to restrict the source of connection requests + appropriately. + </para> + + <para> + If no <command>statistics-channels</command> statement is present, + <command>named</command> will not open any communication channels. + </para> + + <para> + The statistics are available in various formats and views + depending on the URI used to access them. For example, if + the statistics channel is configured to listen on 127.0.0.1 + port 8888, then the statistics are accessible in XML format at + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/">http://127.0.0.1:8888/</link> or + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/xml">http://127.0.0.1:8888/xml</link>. A CSS file is + included which can format the XML statistics into tables + when viewed with a stylesheet-capable browser, and into + charts and graphs using the Google Charts API when using a + javascript-capable browser. + </para> + + <para> + Applications that depend on a particular XML schema + can request + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/xml/v2">http://127.0.0.1:8888/xml/v2</link> for version 2 + of the statistics XML schema or + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/xml/v3">http://127.0.0.1:8888/xml/v3</link> for version 3. + If the requested schema is supported by the server, then + it will respond; if not, it will return a "page not found" + error. + </para> + + <para> + Broken-out subsets of the statistics can be viewed at + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/xml/v3/status">http://127.0.0.1:8888/xml/v3/status</link> + (server uptime and last reconfiguration time), + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/xml/v3/server">http://127.0.0.1:8888/xml/v3/server</link> + (server and resolver statistics), + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/xml/v3/zones">http://127.0.0.1:8888/xml/v3/zones</link> + (zone statistics), + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/xml/v3/net">http://127.0.0.1:8888/xml/v3/net</link> + (network status and socket statistics), + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/xml/v3/mem">http://127.0.0.1:8888/xml/v3/mem</link> + (memory manager statistics), + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/xml/v3/tasks">http://127.0.0.1:8888/xml/v3/tasks</link> + (task manager statistics), and + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/xml/v3/traffic">http://127.0.0.1:8888/xml/v3/traffic</link> + (traffic sizes). + </para> + + <para> + The full set of statistics can also be read in JSON format at + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/json">http://127.0.0.1:8888/json</link>, + with the broken-out subsets at + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/json/v1/status">http://127.0.0.1:8888/json/v1/status</link> + (server uptime and last reconfiguration time), + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/json/v1/server">http://127.0.0.1:8888/json/v1/server</link> + (server and resolver statistics), + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/json/v1/zones">http://127.0.0.1:8888/json/v1/zones</link> + (zone statistics), + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/json/v1/net">http://127.0.0.1:8888/json/v1/net</link> + (network status and socket statistics), + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/json/v1/mem">http://127.0.0.1:8888/json/v1/mem</link> + (memory manager statistics), + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/json/v1/tasks">http://127.0.0.1:8888/json/v1/tasks</link> + (task manager statistics), and + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/json/v1/traffic">http://127.0.0.1:8888/json/v1/traffic</link> + (traffic sizes). + </para> + </section> + + <section xml:id="trusted-keys"><info><title><command>trusted-keys</command> Statement Grammar</title></info> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="trusted-keys.grammar.xml"/> + </section> + <section xml:id="trusted_keys"><info><title><command>trusted-keys</command> Statement Definition + and Usage</title></info> + + <para> + The <command>trusted-keys</command> statement defines + DNSSEC security roots. DNSSEC is described in <xref linkend="DNSSEC"/>. A security root is defined when the + public key for a non-authoritative zone is known, but + cannot be securely obtained through DNS, either because + it is the DNS root zone or because its parent zone is + unsigned. Once a key has been configured as a trusted + key, it is treated as if it had been validated and + proven secure. The resolver attempts DNSSEC validation + on all DNS data in subdomains of a security root. + </para> + <para> + All keys (and corresponding zones) listed in + <command>trusted-keys</command> are deemed to exist regardless + of what parent zones say. Similarly for all keys listed in + <command>trusted-keys</command> only those keys are + used to validate the DNSKEY RRset. The parent's DS RRset + will not be used. + </para> + <para> + The <command>trusted-keys</command> statement can contain + multiple key entries, each consisting of the key's + domain name, flags, protocol, algorithm, and the Base64 + representation of the key data. + Spaces, tabs, newlines and carriage returns are ignored + in the key data, so the configuration may be split up into + multiple lines. + </para> + <para> + <command>trusted-keys</command> may be set at the top level + of <filename>named.conf</filename> or within a view. If it is + set in both places, they are additive: keys defined at the top + level are inherited by all views, but keys defined in a view + are only used within that view. + </para> + <para> + Validation below specified names can be temporarily disabled + by using <command>rndc nta</command>. + </para> + </section> + + <section xml:id="managed_keys"><info><title><command>managed-keys</command> Statement Grammar</title></info> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="managed-keys.grammar.xml"/> + </section> + <section xml:id="managed-keys"><info><title><command>managed-keys</command> Statement Definition + and Usage</title></info> + + <para> + The <command>managed-keys</command> statement, like + <command>trusted-keys</command>, defines DNSSEC + security roots. The difference is that + <command>managed-keys</command> can be kept up to date + automatically, without intervention from the resolver + operator. + </para> + <para> + Suppose, for example, that a zone's key-signing + key was compromised, and the zone owner had to revoke and + replace the key. A resolver which had the old key in a + <command>trusted-keys</command> statement would be + unable to validate this zone any longer; it would + reply with a SERVFAIL response code. This would + continue until the resolver operator had updated the + <command>trusted-keys</command> statement with the new key. + </para> + <para> + If, however, the zone were listed in a + <command>managed-keys</command> statement instead, then the + zone owner could add a "stand-by" key to the zone in advance. + <command>named</command> would store the stand-by key, and + when the original key was revoked, <command>named</command> + would be able to transition smoothly to the new key. It would + also recognize that the old key had been revoked, and cease + using that key to validate answers, minimizing the damage that + the compromised key could do. + </para> + <para> + A <command>managed-keys</command> statement contains a list of + the keys to be managed, along with information about how the + keys are to be initialized for the first time. The only + initialization method currently supported is + <literal>initial-key</literal>. + This means the <command>managed-keys</command> statement must + contain a copy of the initializing key. (Future releases may + allow keys to be initialized by other methods, eliminating this + requirement.) + </para> + <para> + Consequently, a <command>managed-keys</command> statement + appears similar to a <command>trusted-keys</command>, differing + in the presence of the second field, containing the keyword + <literal>initial-key</literal>. The difference is, whereas the + keys listed in a <command>trusted-keys</command> continue to be + trusted until they are removed from + <filename>named.conf</filename>, an initializing key listed + in a <command>managed-keys</command> statement is only trusted + <emphasis>once</emphasis>: for as long as it takes to load the + managed key database and start the RFC 5011 key maintenance + process. + </para> + <para> + The first time <command>named</command> runs with a managed key + configured in <filename>named.conf</filename>, it fetches the + DNSKEY RRset directly from the zone apex, and validates it + using the key specified in the <command>managed-keys</command> + statement. If the DNSKEY RRset is validly signed, then it is + used as the basis for a new managed keys database. + </para> + <para> + From that point on, whenever <command>named</command> runs, it + sees the <command>managed-keys</command> statement, checks to + make sure RFC 5011 key maintenance has already been initialized + for the specified domain, and if so, it simply moves on. The + key specified in the <command>managed-keys</command> + statement is not used to validate answers; it has been + superseded by the key or keys stored in the managed keys database. + </para> + <para> + The next time <command>named</command> runs after a name + has been <emphasis>removed</emphasis> from the + <command>managed-keys</command> statement, the corresponding + zone will be removed from the managed keys database, + and RFC 5011 key maintenance will no longer be used for that + domain. + </para> + <para> + In the current implementation, the managed keys database + is stored as a master-format zone file. + </para> + <para> + On servers which do not use views, this file is named + <filename>managed-keys.bind</filename>. When views are in + use, there will be a separate managed keys database for each + view; the filename will be the view name (or, if a view name + contains characters which would make it illegal as a filename, + a hash of the view name), followed by + the suffix <filename>.mkeys</filename>. + </para> + <para> + When the key database is changed, the zone is updated. + As with any other dynamic zone, changes will be written + into a journal file, e.g., + <filename>managed-keys.bind.jnl</filename> or + <filename>internal.mkeys.jnl</filename>. + Changes are committed to the master file as soon as + possible afterward; this will usually occur within 30 + seconds. So, whenever <command>named</command> is using + automatic key maintenance, the zone file and journal file + can be expected to exist in the working directory. + (For this reason among others, the working directory + should be always be writable by <command>named</command>.) + </para> + <para> + If the <command>dnssec-validation</command> option is + set to <userinput>auto</userinput>, <command>named</command> + will automatically initialize a managed key for the + root zone. The key that is used to initialize the key + maintenance process is stored in <filename>bind.keys</filename>; + the location of this file can be overridden with the + <command>bindkeys-file</command> option. As a fallback + in the event no <filename>bind.keys</filename> can be + found, the initializing key is also compiled directly + into <command>named</command>. + </para> + </section> + + <section xml:id="view_statement_grammar"><info><title><command>view</command> Statement Grammar</title></info> + +<programlisting><command>view</command> <replaceable>view_name</replaceable> [ <replaceable>class</replaceable> ] <command>{</command> + <command>match-clients {</command> <replaceable>address_match_list</replaceable> <command>}</command> ; + <command>match-destinations {</command> <replaceable>address_match_list</replaceable> <command>}</command> ; + <command>match-recursive-only</command> <replaceable>yes_or_no</replaceable> ; + [ <replaceable>view_option</replaceable> ; ... ] + [ <replaceable>zone_statement</replaceable> ; ... ] +<command>} </command>; +</programlisting> + + </section> + <section xml:id="view_statement"><info><title><command>view</command> Statement Definition and Usage</title></info> + + <para> + The <command>view</command> statement is a powerful + feature + of <acronym>BIND</acronym> 9 that lets a name server + answer a DNS query differently + depending on who is asking. It is particularly useful for + implementing + split DNS setups without having to run multiple servers. + </para> + + <para> + Each <command>view</command> statement defines a view + of the + DNS namespace that will be seen by a subset of clients. A client + matches + a view if its source IP address matches the + <varname>address_match_list</varname> of the view's + <command>match-clients</command> clause and its + destination IP address matches + the <varname>address_match_list</varname> of the + view's + <command>match-destinations</command> clause. If not + specified, both + <command>match-clients</command> and <command>match-destinations</command> + default to matching all addresses. In addition to checking IP + addresses + <command>match-clients</command> and <command>match-destinations</command> + can also take <command>keys</command> which provide an + mechanism for the + client to select the view. A view can also be specified + as <command>match-recursive-only</command>, which + means that only recursive + requests from matching clients will match that view. + The order of the <command>view</command> statements is + significant — + a client request will be resolved in the context of the first + <command>view</command> that it matches. + </para> + + <para> + Zones defined within a <command>view</command> + statement will + only be accessible to clients that match the <command>view</command>. + By defining a zone of the same name in multiple views, different + zone data can be given to different clients, for example, + "internal" + and "external" clients in a split DNS setup. + </para> + + <para> + Many of the options given in the <command>options</command> statement + can also be used within a <command>view</command> + statement, and then + apply only when resolving queries with that view. When no + view-specific + value is given, the value in the <command>options</command> statement + is used as a default. Also, zone options can have default values + specified + in the <command>view</command> statement; these + view-specific defaults + take precedence over those in the <command>options</command> statement. + </para> + + <para> + Views are class specific. If no class is given, class IN + is assumed. Note that all non-IN views must contain a hint zone, + since only the IN class has compiled-in default hints. + </para> + + <para> + If there are no <command>view</command> statements in + the config + file, a default view that matches any client is automatically + created + in class IN. Any <command>zone</command> statements + specified on + the top level of the configuration file are considered to be part + of + this default view, and the <command>options</command> + statement will + apply to the default view. If any explicit <command>view</command> + statements are present, all <command>zone</command> + statements must + occur inside <command>view</command> statements. + </para> + + <para> + Here is an example of a typical split DNS setup implemented + using <command>view</command> statements: + </para> + +<programlisting>view "internal" { + // This should match our internal networks. + match-clients { 10.0.0.0/8; }; + + // Provide recursive service to internal + // clients only. + recursion yes; + + // Provide a complete view of the example.com + // zone including addresses of internal hosts. + zone "example.com" { + type master; + file "example-internal.db"; + }; +}; + +view "external" { + // Match all clients not matched by the + // previous view. + match-clients { any; }; + + // Refuse recursive service to external clients. + recursion no; + + // Provide a restricted view of the example.com + // zone containing only publicly accessible hosts. + zone "example.com" { + type master; + file "example-external.db"; + }; +}; +</programlisting> + + </section> + <section xml:id="zone_statement_grammar"><info><title><command>zone</command> + Statement Grammar</title></info> + +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="master.zoneopt.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="slave.zoneopt.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hint.zoneopt.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="stub.zoneopt.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="static-stub.zoneopt.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="forward.zoneopt.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="redirect.zoneopt.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="delegation-only.zoneopt.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="in-view.zoneopt.xml"/> + + </section> + <section xml:id="zone_statement"><info><title><command>zone</command> Statement Definition and Usage</title></info> + + <section xml:id="zone_types"><info><title>Zone Types</title></info> + <para> + The <command>type</command> keyword is required + for the <command>zone</command> configuration unless + it is an <command>in-view</command> configuration. Its + acceptable values include: <varname>delegation-only</varname>, + <varname>forward</varname>, <varname>hint</varname>, + <varname>master</varname>, <varname>redirect</varname>, + <varname>slave</varname>, <varname>static-stub</varname>, + and <varname>stub</varname>. + </para> + + <informaltable colsep="0" rowsep="0"> + <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="3Level-table"> + <!--colspec colname="1" colnum="1" colsep="0" colwidth="1.108in"/--> + <!--colspec colname="2" colnum="2" colsep="0" colwidth="4.017in"/--> + <colspec colname="1" colnum="1" colsep="0"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="4.017in"/> + <tbody> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>master</varname> + </para> + </entry> + <entry colname="2"> + <para> + The server has a master copy of the data + for the zone and will be able to provide authoritative + answers for + it. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>slave</varname> + </para> + </entry> + <entry colname="2"> + <para> + A slave zone is a replica of a master + zone. The <command>masters</command> list + specifies one or more IP addresses + of master servers that the slave contacts to update + its copy of the zone. + Masters list elements can also be names of other + masters lists. + By default, transfers are made from port 53 on the + servers; this can + be changed for all servers by specifying a port number + before the + list of IP addresses, or on a per-server basis after + the IP address. + Authentication to the master can also be done with + per-server TSIG keys. + If a file is specified, then the + replica will be written to this file whenever the zone + is changed, + and reloaded from this file on a server restart. Use + of a file is + recommended, since it often speeds server startup and + eliminates + a needless waste of bandwidth. Note that for large + numbers (in the + tens or hundreds of thousands) of zones per server, it + is best to + use a two-level naming scheme for zone filenames. For + example, + a slave server for the zone <literal>example.com</literal> might place + the zone contents into a file called + <filename>ex/example.com</filename> where <filename>ex/</filename> is + just the first two letters of the zone name. (Most + operating systems + behave very slowly if you put 100000 files into + a single directory.) + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>stub</varname> + </para> + </entry> + <entry colname="2"> + <para> + A stub zone is similar to a slave zone, + except that it replicates only the NS records of a + master zone instead + of the entire zone. Stub zones are not a standard part + of the DNS; + they are a feature specific to the <acronym>BIND</acronym> implementation. + </para> + + <para> + Stub zones can be used to eliminate the need for glue + NS record + in a parent zone at the expense of maintaining a stub + zone entry and + a set of name server addresses in <filename>named.conf</filename>. + This usage is not recommended for new configurations, + and BIND 9 + supports it only in a limited way. + In <acronym>BIND</acronym> 4/8, zone + transfers of a parent zone + included the NS records from stub children of that + zone. This meant + that, in some cases, users could get away with + configuring child stubs + only in the master server for the parent zone. <acronym>BIND</acronym> + 9 never mixes together zone data from different zones + in this + way. Therefore, if a <acronym>BIND</acronym> 9 master serving a parent + zone has child stub zones configured, all the slave + servers for the + parent zone also need to have the same child stub + zones + configured. + </para> + + <para> + Stub zones can also be used as a way of forcing the + resolution + of a given domain to use a particular set of + authoritative servers. + For example, the caching name servers on a private + network using + RFC1918 addressing may be configured with stub zones + for + <literal>10.in-addr.arpa</literal> + to use a set of internal name servers as the + authoritative + servers for that domain. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>static-stub</varname> + </para> + </entry> + <entry colname="2"> + <para> + A static-stub zone is similar to a stub zone + with the following exceptions: + the zone data is statically configured, rather + than transferred from a master server; + when recursion is necessary for a query that + matches a static-stub zone, the locally + configured data (nameserver names and glue addresses) + is always used even if different authoritative + information is cached. + </para> + <para> + Zone data is configured via the + <command>server-addresses</command> and + <command>server-names</command> zone options. + </para> + <para> + The zone data is maintained in the form of NS + and (if necessary) glue A or AAAA RRs + internally, which can be seen by dumping zone + databases by <command>rndc dumpdb -all</command>. + The configured RRs are considered local configuration + parameters rather than public data. + Non recursive queries (i.e., those with the RD + bit off) to a static-stub zone are therefore + prohibited and will be responded with REFUSED. + </para> + <para> + Since the data is statically configured, no + zone maintenance action takes place for a static-stub + zone. + For example, there is no periodic refresh + attempt, and an incoming notify message + will be rejected with an rcode of NOTAUTH. + </para> + <para> + Each static-stub zone is configured with + internally generated NS and (if necessary) + glue A or AAAA RRs + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>forward</varname> + </para> + </entry> + <entry colname="2"> + <para> + A "forward zone" is a way to configure + forwarding on a per-domain basis. A <command>zone</command> statement + of type <command>forward</command> can + contain a <command>forward</command> + and/or <command>forwarders</command> + statement, + which will apply to queries within the domain given by + the zone + name. If no <command>forwarders</command> + statement is present or + an empty list for <command>forwarders</command> is given, then no + forwarding will be done for the domain, canceling the + effects of + any forwarders in the <command>options</command> statement. Thus + if you want to use this type of zone to change the + behavior of the + global <command>forward</command> option + (that is, "forward first" + to, then "forward only", or vice versa, but want to + use the same + servers as set globally) you need to re-specify the + global forwarders. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>hint</varname> + </para> + </entry> + <entry colname="2"> + <para> + The initial set of root name servers is + specified using a "hint zone". When the server starts + up, it uses + the root hints to find a root name server and get the + most recent + list of root name servers. If no hint zone is + specified for class + IN, the server uses a compiled-in default set of root + servers hints. + Classes other than IN have no built-in defaults hints. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>redirect</varname> + </para> + </entry> + <entry colname="2"> + <para> + Redirect zones are used to provide answers to + queries when normal resolution would result in + NXDOMAIN being returned. + Only one redirect zone is supported + per view. <command>allow-query</command> can be + used to restrict which clients see these answers. + </para> + <para> + If the client has requested DNSSEC records (DO=1) and + the NXDOMAIN response is signed then no substitution + will occur. + </para> + <para> + To redirect all NXDOMAIN responses to + 100.100.100.2 and + 2001:ffff:ffff::100.100.100.2, one would + configure a type redirect zone named ".", + with the zone file containing wildcard records + that point to the desired addresses: + <literal>"*. IN A 100.100.100.2"</literal> + and + <literal>"*. IN AAAA 2001:ffff:ffff::100.100.100.2"</literal>. + </para> + <para> + To redirect all Spanish names (under .ES) one + would use similar entries but with the names + "*.ES." instead of "*.". To redirect all + commercial Spanish names (under COM.ES) one + would use wildcard entries called "*.COM.ES.". + </para> + <para> + Note that the redirect zone supports all + possible types; it is not limited to A and + AAAA records. + </para> + <para> + Because redirect zones are not referenced + directly by name, they are not kept in the + zone lookup table with normal master and slave + zones. Consequently, it is not currently possible + to use + <command>rndc reload + <replaceable>zonename</replaceable></command> + to reload a redirect zone. However, when using + <command>rndc reload</command> without specifying + a zone name, redirect zones will be reloaded along + with other zones. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>delegation-only</varname> + </para> + </entry> + <entry colname="2"> + <para> + This is used to enforce the delegation-only + status of infrastructure zones (e.g. COM, + NET, ORG). Any answer that is received + without an explicit or implicit delegation + in the authority section will be treated + as NXDOMAIN. This does not apply to the + zone apex. This should not be applied to + leaf zones. + </para> + <para> + <varname>delegation-only</varname> has no + effect on answers received from forwarders. + </para> + <para> + See caveats in <xref linkend="root_delegation_only"/>. + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </section> + + <section xml:id="class"><info><title>Class</title></info> + + <para> + The zone's name may optionally be followed by a class. If + a class is not specified, class <literal>IN</literal> (for <varname>Internet</varname>), + is assumed. This is correct for the vast majority of cases. + </para> + <para> + The <literal>hesiod</literal> class is + named for an information service from MIT's Project Athena. It + is + used to share information about various systems databases, such + as users, groups, printers and so on. The keyword + <literal>HS</literal> is + a synonym for hesiod. + </para> + <para> + Another MIT development is Chaosnet, a LAN protocol created + in the mid-1970s. Zone data for it can be specified with the <literal>CHAOS</literal> class. + </para> + </section> + + <section xml:id="zone_options"><info><title>Zone Options</title></info> + + <variablelist> + + <varlistentry> + <term><command>allow-notify</command></term> + <listitem> + <para> + See the description of + <command>allow-notify</command> in <xref linkend="access_control"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>allow-query</command></term> + <listitem> + <para> + See the description of + <command>allow-query</command> in <xref linkend="access_control"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>allow-query-on</command></term> + <listitem> + <para> + See the description of + <command>allow-query-on</command> in <xref linkend="access_control"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>allow-transfer</command></term> + <listitem> + <para> + See the description of <command>allow-transfer</command> + in <xref linkend="access_control"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>allow-update</command></term> + <listitem> + <para> + See the description of <command>allow-update</command> + in <xref linkend="access_control"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>update-policy</command></term> + <listitem> + <para> + Specifies a "Simple Secure Update" policy. See + <xref linkend="dynamic_update_policies"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>allow-update-forwarding</command></term> + <listitem> + <para> + See the description of <command>allow-update-forwarding</command> + in <xref linkend="access_control"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>also-notify</command></term> + <listitem> + <para> + Only meaningful if <command>notify</command> + is + active for this zone. The set of machines that will + receive a + <literal>DNS NOTIFY</literal> message + for this zone is made up of all the listed name servers + (other than + the primary master) for the zone plus any IP addresses + specified + with <command>also-notify</command>. A port + may be specified + with each <command>also-notify</command> + address to send the notify + messages to a port other than the default of 53. + A TSIG key may also be specified to cause the + <literal>NOTIFY</literal> to be signed by the + given key. + <command>also-notify</command> is not + meaningful for stub zones. + The default is the empty list. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>check-names</command></term> + <listitem> + <para> + This option is used to restrict the character set and + syntax of + certain domain names in master files and/or DNS responses + received from the + network. The default varies according to zone type. For <command>master</command> zones the default is <command>fail</command>. For <command>slave</command> + zones the default is <command>warn</command>. + It is not implemented for <command>hint</command> zones. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>check-mx</command></term> + <listitem> + <para> + See the description of + <command>check-mx</command> in <xref linkend="boolean_options"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>check-spf</command></term> + <listitem> + <para> + See the description of + <command>check-spf</command> in <xref linkend="boolean_options"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>check-wildcard</command></term> + <listitem> + <para> + See the description of + <command>check-wildcard</command> in <xref linkend="boolean_options"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>check-integrity</command></term> + <listitem> + <para> + See the description of + <command>check-integrity</command> in <xref linkend="boolean_options"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>check-sibling</command></term> + <listitem> + <para> + See the description of + <command>check-sibling</command> in <xref linkend="boolean_options"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>zero-no-soa-ttl</command></term> + <listitem> + <para> + See the description of + <command>zero-no-soa-ttl</command> in <xref linkend="boolean_options"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>update-check-ksk</command></term> + <listitem> + <para> + See the description of + <command>update-check-ksk</command> in <xref linkend="boolean_options"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>dnssec-loadkeys-interval</command></term> + <listitem> + <para> + See the description of + <command>dnssec-loadkeys-interval</command> in <xref linkend="options"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>dnssec-update-mode</command></term> + <listitem> + <para> + See the description of + <command>dnssec-update-mode</command> in <xref linkend="options"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>dnssec-dnskey-kskonly</command></term> + <listitem> + <para> + See the description of + <command>dnssec-dnskey-kskonly</command> in <xref linkend="boolean_options"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>try-tcp-refresh</command></term> + <listitem> + <para> + See the description of + <command>try-tcp-refresh</command> in <xref linkend="boolean_options"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>database</command></term> + <listitem> + <para> + Specify the type of database to be used for storing the + zone data. The string following the <command>database</command> keyword + is interpreted as a list of whitespace-delimited words. + The first word + identifies the database type, and any subsequent words are + passed + as arguments to the database to be interpreted in a way + specific + to the database type. + </para> + <para> + The default is <userinput>"rbt"</userinput>, BIND 9's + native in-memory + red-black-tree database. This database does not take + arguments. + </para> + <para> + Other values are possible if additional database drivers + have been linked into the server. Some sample drivers are + included + with the distribution but none are linked in by default. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>dialup</command></term> + <listitem> + <para> + See the description of + <command>dialup</command> in <xref linkend="boolean_options"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>delegation-only</command></term> + <listitem> + <para> + The flag only applies to forward, hint and stub + zones. If set to <userinput>yes</userinput>, + then the zone will also be treated as if it is + also a delegation-only type zone. + </para> + <para> + See caveats in <xref linkend="root_delegation_only"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>file</command></term> + <listitem> + <para> + Set the zone's filename. In <command>master</command>, + <command>hint</command>, and <command>redirect</command> + zones which do not have <command>masters</command> + defined, zone data is loaded from this file. In + <command>slave</command>, <command>stub</command>, and + <command>redirect</command> zones which do have + <command>masters</command> defined, zone data is + retrieved from another server and saved in this file. + This option is not applicable to other zone types. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>forward</command></term> + <listitem> + <para> + Only meaningful if the zone has a forwarders + list. The <command>only</command> value causes + the lookup to fail + after trying the forwarders and getting no answer, while <command>first</command> would + allow a normal lookup to be tried. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>forwarders</command></term> + <listitem> + <para> + Used to override the list of global forwarders. + If it is not specified in a zone of type <command>forward</command>, + no forwarding is done for the zone and the global options are + not used. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>ixfr-base</command></term> + <listitem> + <para> + Was used in <acronym>BIND</acronym> 8 to + specify the name + of the transaction log (journal) file for dynamic update + and IXFR. + <acronym>BIND</acronym> 9 ignores the option + and constructs the name of the journal + file by appending "<filename>.jnl</filename>" + to the name of the + zone file. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>ixfr-tmp-file</command></term> + <listitem> + <para> + Was an undocumented option in <acronym>BIND</acronym> 8. + Ignored in <acronym>BIND</acronym> 9. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>journal</command></term> + <listitem> + <para> + Allow the default journal's filename to be overridden. + The default is the zone's filename with "<filename>.jnl</filename>" appended. + This is applicable to <command>master</command> and <command>slave</command> zones. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>max-journal-size</command></term> + <listitem> + <para> + See the description of + <command>max-journal-size</command> in <xref linkend="server_resource_limits"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>max-records</command></term> + <listitem> + <para> + See the description of + <command>max-records</command> in <xref linkend="server_resource_limits"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>max-transfer-time-in</command></term> + <listitem> + <para> + See the description of + <command>max-transfer-time-in</command> in <xref linkend="zone_transfers"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>max-transfer-idle-in</command></term> + <listitem> + <para> + See the description of + <command>max-transfer-idle-in</command> in <xref linkend="zone_transfers"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>max-transfer-time-out</command></term> + <listitem> + <para> + See the description of + <command>max-transfer-time-out</command> in <xref linkend="zone_transfers"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>max-transfer-idle-out</command></term> + <listitem> + <para> + See the description of + <command>max-transfer-idle-out</command> in <xref linkend="zone_transfers"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>notify</command></term> + <listitem> + <para> + See the description of + <command>notify</command> in <xref linkend="boolean_options"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>notify-delay</command></term> + <listitem> + <para> + See the description of + <command>notify-delay</command> in <xref linkend="tuning"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>notify-to-soa</command></term> + <listitem> + <para> + See the description of + <command>notify-to-soa</command> in + <xref linkend="boolean_options"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>pubkey</command></term> + <listitem> + <para> + In <acronym>BIND</acronym> 8, this option was + intended for specifying + a public zone key for verification of signatures in DNSSEC + signed + zones when they are loaded from disk. <acronym>BIND</acronym> 9 does not verify signatures + on load and ignores the option. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>zone-statistics</command></term> + <listitem> + <para> + See the description of + <command>zone-statistics</command> in + <xref linkend="options"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>server-addresses</command></term> + <listitem> + <para> + Only meaningful for static-stub zones. + This is a list of IP addresses to which queries + should be sent in recursive resolution for the + zone. + A non empty list for this option will internally + configure the apex NS RR with associated glue A or + AAAA RRs. + </para> + <para> + For example, if "example.com" is configured as a + static-stub zone with 192.0.2.1 and 2001:db8::1234 + in a <command>server-addresses</command> option, + the following RRs will be internally configured. + </para> +<programlisting>example.com. NS example.com. +example.com. A 192.0.2.1 +example.com. AAAA 2001:db8::1234</programlisting> + <para> + These records are internally used to resolve + names under the static-stub zone. + For instance, if the server receives a query for + "www.example.com" with the RD bit on, the server + will initiate recursive resolution and send + queries to 192.0.2.1 and/or 2001:db8::1234. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>server-names</command></term> + <listitem> + <para> + Only meaningful for static-stub zones. + This is a list of domain names of nameservers that + act as authoritative servers of the static-stub + zone. + These names will be resolved to IP addresses when + <command>named</command> needs to send queries to + these servers. + To make this supplemental resolution successful, + these names must not be a subdomain of the origin + name of static-stub zone. + That is, when "example.net" is the origin of a + static-stub zone, "ns.example" and + "master.example.com" can be specified in the + <command>server-names</command> option, but + "ns.example.net" cannot, and will be rejected by + the configuration parser. + </para> + <para> + A non empty list for this option will internally + configure the apex NS RR with the specified names. + For example, if "example.com" is configured as a + static-stub zone with "ns1.example.net" and + "ns2.example.net" + in a <command>server-names</command> option, + the following RRs will be internally configured. + </para> +<programlisting>example.com. NS ns1.example.net. +example.com. NS ns2.example.net. +</programlisting> + <para> + These records are internally used to resolve + names under the static-stub zone. + For instance, if the server receives a query for + "www.example.com" with the RD bit on, the server + initiate recursive resolution, + resolve "ns1.example.net" and/or + "ns2.example.net" to IP addresses, and then send + queries to (one or more of) these addresses. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>sig-validity-interval</command></term> + <listitem> + <para> + See the description of + <command>sig-validity-interval</command> in <xref linkend="tuning"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>sig-signing-nodes</command></term> + <listitem> + <para> + See the description of + <command>sig-signing-nodes</command> in <xref linkend="tuning"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>sig-signing-signatures</command></term> + <listitem> + <para> + See the description of + <command>sig-signing-signatures</command> in <xref linkend="tuning"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>sig-signing-type</command></term> + <listitem> + <para> + See the description of + <command>sig-signing-type</command> in <xref linkend="tuning"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>transfer-source</command></term> + <listitem> + <para> + See the description of + <command>transfer-source</command> in <xref linkend="zone_transfers"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>transfer-source-v6</command></term> + <listitem> + <para> + See the description of + <command>transfer-source-v6</command> in <xref linkend="zone_transfers"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>alt-transfer-source</command></term> + <listitem> + <para> + See the description of + <command>alt-transfer-source</command> in <xref linkend="zone_transfers"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>alt-transfer-source-v6</command></term> + <listitem> + <para> + See the description of + <command>alt-transfer-source-v6</command> in <xref linkend="zone_transfers"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>use-alt-transfer-source</command></term> + <listitem> + <para> + See the description of + <command>use-alt-transfer-source</command> in <xref linkend="zone_transfers"/>. + </para> + </listitem> + </varlistentry> + + + <varlistentry> + <term><command>notify-source</command></term> + <listitem> + <para> + See the description of + <command>notify-source</command> in <xref linkend="zone_transfers"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>notify-source-v6</command></term> + <listitem> + <para> + See the description of + <command>notify-source-v6</command> in <xref linkend="zone_transfers"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>min-refresh-time</command></term> + <term><command>max-refresh-time</command></term> + <term><command>min-retry-time</command></term> + <term><command>max-retry-time</command></term> + <listitem> + <para> + See the description in <xref linkend="tuning"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>ixfr-from-differences</command></term> + <listitem> + <para> + See the description of + <command>ixfr-from-differences</command> in <xref linkend="boolean_options"/>. + (Note that the <command>ixfr-from-differences</command> + <userinput>master</userinput> and + <userinput>slave</userinput> choices are not + available at the zone level.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>key-directory</command></term> + <listitem> + <para> + See the description of + <command>key-directory</command> in <xref linkend="options"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>auto-dnssec</command></term> + <listitem> + <para> + See the description of + <command>auto-dnssec</command> in + <xref linkend="options"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>serial-update-method</command></term> + <listitem> + <para> + See the description of + <command>serial-update-method</command> in + <xref linkend="options"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>inline-signing</command></term> + <listitem> + <para> + If <literal>yes</literal>, this enables + "bump in the wire" signing of a zone, where a + unsigned zone is transferred in or loaded from + disk and a signed version of the zone is served, + with possibly, a different serial number. This + behavior is disabled by default. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>multi-master</command></term> + <listitem> + <para> + See the description of <command>multi-master</command> in + <xref linkend="boolean_options"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>masterfile-format</command></term> + <listitem> + <para> + See the description of <command>masterfile-format</command> + in <xref linkend="tuning"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>max-zone-ttl</command></term> + <listitem> + <para> + See the description of <command>max-zone-ttl</command> + in <xref linkend="options"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>dnssec-secure-to-insecure</command></term> + <listitem> + <para> + See the description of + <command>dnssec-secure-to-insecure</command> in <xref linkend="boolean_options"/>. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </section> + <section xml:id="dynamic_update_policies"><info><title>Dynamic Update Policies</title></info> + + <para><acronym>BIND</acronym> 9 supports two alternative + methods of granting clients the right to perform + dynamic updates to a zone, configured by the + <command>allow-update</command> and + <command>update-policy</command> option, respectively. + </para> + <para> + The <command>allow-update</command> clause is a simple + access control list. Any client that matches + the ACL is granted permission to update any record + in the zone. + </para> + <para> + The <command>update-policy</command> clause + allows more fine-grained control over what updates are + allowed. It specifies a set of rules, in which each rule + either grants or denies permission for one or more + names in the zone to be updated by one or more + identities. Identity is determined by the key that + signed the update request using either TSIG or SIG(0). + In most cases, <command>update-policy</command> rules + only apply to key-based identities. There is no way + to specify update permissions based on client source + address. + </para> + <para> + <command>update-policy</command> rules are only meaningful + for zones of type <command>master</command>, and are + not allowed in any other zone type. + It is a configuration error to specify both + <command>allow-update</command> and + <command>update-policy</command> at the same time. + </para> + <para> + A pre-defined <command>update-policy</command> rule can be + switched on with the command + <command>update-policy local;</command>. + Using this in a zone causes + <command>named</command> to generate a TSIG session key + when starting up and store it in a file; this key can then + be used by local clients to update the zone while + <command>named</command> is running. + By default, the session key is stored in the file + <filename>/var/run/named/session.key</filename>, the key name + is "local-ddns", and the key algorithm is HMAC-SHA256. + These values are configurable with the + <command>session-keyfile</command>, + <command>session-keyname</command> and + <command>session-keyalg</command> options, respectively. + A client running on the local system, if run with appropriate + permissions, may read the session key from the key file and + use it to sign update requests. The zone's update + policy will be set to allow that key to change any record + within the zone. Assuming the key name is "local-ddns", + this policy is equivalent to: + </para> + + <programlisting>update-policy { grant local-ddns zonesub any; }; + </programlisting> + + <para> + ...with the additional restriction that only clients + connecting from the local system will be permitted to send + updates. + </para> + <para> + Note that only one session key is generated by + <command>named</command>; all zones configured to use + <command>update-policy local</command> will accept the same key. + </para> + <para> + The command <command>nsupdate -l</command> implements this + feature, sending requests to localhost and signing them using + the key retrieved from the session key file. + </para> + + <para> + Other rule definitions look like this: + </para> + +<programlisting> +( <command>grant</command> | <command>deny</command> ) <replaceable>identity</replaceable> <replaceable>ruletype</replaceable> <optional> <replaceable>name</replaceable> </optional> <optional> <replaceable>types</replaceable> </optional> +</programlisting> + + <para> + Each rule grants or denies privileges. Rules are checked + in the order in which they are specified in the + <command>update-policy</command> statement. Once a message + has successfully matched a rule, the operation is immediately + granted or denied, and no further rules are examined. There + are 13 types of rules; the rule type is specified by the + <command>ruletype</command> field, and the interpretation + of other fields varies depending on the rule type. + </para> + <para> + In general, a rule is matched when the + key that signed an update request matches the + <command>identity</command> field, the name of the record + to be updated matches the <command>name</command> field + (in the manner specified by the <command>ruletype</command> + field), and the type of the record to be updated matches the + <command>types</command> field. Details for each rule type + are described below. + </para> + <para> + The <command>identity</command> field must be set to + a fully-qualified domain name. In most cases, this + represensts the name of the TSIG or SIG(0) key that must be + used to sign the update request. If the specified name is a + wildcard, it is subject to DNS wildcard expansion, and the + rule may apply to multiple identities. When a TKEY exchange + has been used to create a shared secret, the identity of + the key used to authenticate the TKEY exchange will be + used as the identity of the shared secret. Some rule types + use identities matching the client's Kerberos principal + (e.g, <userinput>"host/machine@REALM"</userinput>) or + Windows realm (<userinput>machine$@REALM</userinput>). + </para> + <para> + The <replaceable>name</replaceable> field also specifies + a fully-qualified domain name. This often + represents the name of the record to be updated. + Interpretation of this field is dependent on rule type. + </para> + <para> + If no <command>types</command> are explicitly specified, + then a rule matches all types except RRSIG, NS, SOA, NSEC + and NSEC3. Types may be specified by name, including + "ANY" (ANY matches all types except NSEC and NSEC3, + which can never be updated). Note that when an attempt + is made to delete all records associated with a name, + the rules are checked for each existing record type. + </para> + <para> + The <replaceable>ruletype</replaceable> field has 16 + values: + <varname>name</varname>, <varname>subdomain</varname>, + <varname>wildcard</varname>, <varname>self</varname>, + <varname>selfsub</varname>, <varname>selfwild</varname>, + <varname>krb5-self</varname>, <varname>ms-self</varname>, + <varname>krb5-selfsub</varname>, <varname>ms-selfsub</varname>, + <varname>krb5-subdomain</varname>, + <varname>ms-subdomain</varname>, + <varname>tcp-self</varname>, <varname>6to4-self</varname>, + <varname>zonesub</varname>, and <varname>external</varname>. + </para> + <informaltable> + <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="4Level-table"> + <colspec colname="1" colnum="1" colsep="0" colwidth="0.819in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="3.681in"/> + <tbody> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>name</varname> + </para> + </entry> <entry colname="2"> + <para> + Exact-match semantics. This rule matches + when the name being updated is identical + to the contents of the + <replaceable>name</replaceable> field. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>subdomain</varname> + </para> + </entry> <entry colname="2"> + <para> + This rule matches when the name being updated + is a subdomain of, or identical to, the + contents of the <replaceable>name</replaceable> + field. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>zonesub</varname> + </para> + </entry> <entry colname="2"> + <para> + This rule is similar to subdomain, except that + it matches when the name being updated is a + subdomain of the zone in which the + <command>update-policy</command> statement + appears. This obviates the need to type the zone + name twice, and enables the use of a standard + <command>update-policy</command> statement in + multiple zones without modification. + </para> + <para> + When this rule is used, the + <replaceable>name</replaceable> field is omitted. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>wildcard</varname> + </para> + </entry> <entry colname="2"> + <para> + The <replaceable>name</replaceable> field + is subject to DNS wildcard expansion, and + this rule matches when the name being updated + is a valid expansion of the wildcard. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>self</varname> + </para> + </entry> + <entry colname="2"> + <para> + This rule matches when the name of the record + being updated matches the contents of the + <replaceable>identity</replaceable> field. + The <replaceable>name</replaceable> field + is ignored. To avoid confusion, it is recommended + that this field be set to the same value as the + <replaceable>identity</replaceable> field or to + "." + </para> + <para> + The <varname>self</varname> rule type is + most useful when allowing one key per + name to update, where the key has the same + name as the record to be updated. In this case, + the <replaceable>identity</replaceable> field + can be specified as <constant>*</constant> + (an asterisk). + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>selfsub</varname> + </para> + </entry> <entry colname="2"> + <para> + This rule is similar to <varname>self</varname> + except that subdomains of <varname>self</varname> + can also be updated. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>selfwild</varname> + </para> + </entry> <entry colname="2"> + <para> + This rule is similar to <varname>self</varname> + except that only subdomains of + <varname>self</varname> can be updated. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>ms-self</varname> + </para> + </entry> <entry colname="2"> + <para> + When a client sends an UPDATE using a Windows + machine principal (for example, 'machine$@REALM'), + this rule allows records with the absolute name + of 'machine.REALM' to be updated. + </para> + <para> + The realm to be matched is specified in the + <replaceable>identity</replaceable> field. + </para> + <para> + The <replaceable>name</replaceable> field has + no effect on this rule; it should be set to "." + as a placeholder. + </para> + <para> + For example, + <userinput>grant EXAMPLE.COM ms-self . A AAAA</userinput> + allows any machine with a valid principal in + the realm <userinput>EXAMPLE.COM</userinput> to update + its own address records. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>ms-selfsub</varname> + </para> + </entry> <entry colname="2"> + <para> + This is similar to <command>ms-self</command> + except it also allows updates to any subdomain of + the name specified in the Windows machine + principal, not just to the name itself. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>ms-subdomain</varname> + </para> + </entry> <entry colname="2"> + <para> + When a client sends an UPDATE using a Windows + machine principal (for example, 'machine$@REALM'), + this rule allows any machine in the specified + realm to update any record in the zone or in a + specified subdomain of the zone. + </para> + <para> + The realm to be matched is specified in the + <replaceable>identity</replaceable> field. + </para> + <para> + The <replaceable>name</replaceable> field + specifies the subdomain that may be updated. + If set to "." (or any other name at or above + the zone apex), any name in the zone can be + updated. + </para> + <para> + For example, if <command>update-policy</command> + for the zone "example.com" includes + <userinput>grant EXAMPLE.COM ms-subdomain hosts.example.com. A AAAA</userinput>, + any machine with a valid principal in + the realm <userinput>EXAMPLE.COM</userinput> will + be able to update address records at or below + "hosts.example.com". + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>krb5-self</varname> + </para> + </entry> <entry colname="2"> + <para> + When a client sends an UPDATE using a + Kerberos machine principal (for example, + 'host/machine@REALM'), this rule allows + records with the absolute name of 'machine' + to be updated provided it has been authenticated + by REALM. This is similar but not identical + to <command>ms-self</command> due to the + 'machine' part of the Kerberos principal + being an absolute name instead of a unqualified + name. + </para> + <para> + The realm to be matched is specified in the + <replaceable>identity</replaceable> field. + </para> + <para> + The <replaceable>name</replaceable> field has + no effect on this rule; it should be set to "." + as a placeholder. + </para> + <para> + For example, + <userinput>grant EXAMPLE.COM krb5-self . A AAAA</userinput> + allows any machine with a valid principal in + the realm <userinput>EXAMPLE.COM</userinput> to update + its own address records. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>krb5-selfsub</varname> + </para> + </entry> <entry colname="2"> + <para> + This is similar to <command>krb5-self</command> + except it also allows updates to any subdomain of + the name specified in the 'machine' part of the + Kerberos principal, not just to the name itself. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>krb5-subdomain</varname> + </para> + </entry> <entry colname="2"> + <para> + This rule is identical to + <command>ms-subdomain</command>, except that it works + with Kerberos machine principals (i.e., + 'host/machine@REALM') rather than Windows machine + principals. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>tcp-self</varname> + </para> + </entry> <entry colname="2"> + <para> + This rule allows updates that have been sent via + TCP and for which the standard mapping from the + client's IP address into the + <literal>in-addr.arpa</literal> and + <literal>ip6.arpa</literal> + namespaces match the name to be updated. + The <command>identity</command> field must match + that name. The <command>name</command> field + should be set to ".". + Note that, since identity is based on the client's + IP address, it is not necessary for update request + messages to be signed. + </para> + <note> + It is theoretically possible to spoof these TCP + sessions. + </note> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>6to4-self</varname> + </para> + </entry> <entry colname="2"> + <para> + This allows the name matching a 6to4 IPv6 prefix, + as specified in RFC 3056, to be updated by any + TCP connection from either the 6to4 network or + from the corresponding IPv4 address. This is + intended to allow NS or DNAME RRsets to be added + to the <literal>ip6.arpa</literal> reverse tree. + </para> + <para> + The <command>identity</command> field must match + the 6to4 prefix in <literal>ip6.arpa</literal>. + The <command>name</command> field should + be set to ".". + Note that, since identity is based on the client's + IP address, it is not necessary for update request + messages to be signed. + </para> + <para> + In addition, if specified for an + <literal>ip6.arpa</literal> name outside of the + <literal>2.0.0.2.ip6.arpa</literal> namespace, + the corresponding /48 reverse name can be updated. + For example, TCP/IPv6 connections + from 2001:DB8:ED0C::/48 can update records at + <literal>C.0.D.E.8.B.D.0.1.0.0.2.ip6.arpa</literal>. + </para> + <note> + It is theoretically possible to spoof these TCP + sessions. + </note> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>external</varname> + </para> + </entry> <entry colname="2"> + <para> + This rule allows <command>named</command> + to defer the decision of whether to allow a + given update to an external daemon. + </para> + <para> + The method of communicating with the daemon is + specified in the <replaceable>identity</replaceable> + field, the format of which is + "<constant>local:</constant><replaceable>path</replaceable>", + where <replaceable>path</replaceable> is the location + of a UNIX-domain socket. (Currently, "local" is the + only supported mechanism.) + </para> + <para> + Requests to the external daemon are sent over the + UNIX-domain socket as datagrams with the following + format: + </para> + <programlisting> + Protocol version number (4 bytes, network byte order, currently 1) + Request length (4 bytes, network byte order) + Signer (null-terminated string) + Name (null-terminated string) + TCP source address (null-terminated string) + Rdata type (null-terminated string) + Key (null-terminated string) + TKEY token length (4 bytes, network byte order) + TKEY token (remainder of packet)</programlisting> + <para> + The daemon replies with a four-byte value in + network byte order, containing either 0 or 1; 0 + indicates that the specified update is not + permitted, and 1 indicates that it is. + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </section> + + <section xml:id="multiple_views"><info><title>Multiple views</title></info> + + <para> + When multiple views are in use, a zone may be + referenced by more than one of them. Often, the views + will contain different zones with the same name, allowing + different clients to receive different answers for the same + queries. At times, however, it is desirable for multiple + views to contain identical zones. The + <command>in-view</command> zone option provides an efficient + way to do this: it allows a view to reference a zone that + was defined in a previously configured view. Example: + </para> + <programlisting> +view internal { + match-clients { 10/8; }; + + zone example.com { + type master; + file "example-external.db"; + }; +}; + +view external { + match-clients { any; }; + + zone example.com { + in-view internal; + }; +}; + </programlisting> + <para> + An <command>in-view</command> option cannot refer to a view + that is configured later in the configuration file. + </para> + <para> + A <command>zone</command> statement which uses the + <command>in-view</command> option may not use any other + options with the exception of <command>forward</command> + and <command>forwarders</command>. (These options control + the behavior of the containing view, rather than changing + the zone object itself.) + </para> + <para> + Zone level acls (e.g. allow-query, allow-transfer) and + other configuration details of the zone are all set + in the view the referenced zone is defined in. Care + need to be taken to ensure that acls are wide enough + for all views referencing the zone. + </para> + <para> + An <command>in-view</command> zone cannot be used as a + response policy zone. + </para> + <para> + An <command>in-view</command> zone is not intended to reference + a <command>forward</command> zone. + </para> + </section> + + </section> + </section> + <section xml:id="zone_file"><info><title>Zone File</title></info> + + <section xml:id="types_of_resource_records_and_when_to_use_them"><info><title>Types of Resource Records and When to Use Them</title></info> + + <para> + This section, largely borrowed from RFC 1034, describes the + concept of a Resource Record (RR) and explains when each is used. + Since the publication of RFC 1034, several new RRs have been + identified + and implemented in the DNS. These are also included. + </para> + <section><info><title>Resource Records</title></info> + + <para> + A domain name identifies a node. Each node has a set of + resource information, which may be empty. The set of resource + information associated with a particular name is composed of + separate RRs. The order of RRs in a set is not significant and + need not be preserved by name servers, resolvers, or other + parts of the DNS. However, sorting of multiple RRs is + permitted for optimization purposes, for example, to specify + that a particular nearby server be tried first. See <xref linkend="the_sortlist_statement"/> and <xref linkend="rrset_ordering"/>. + </para> + + <para> + The components of a Resource Record are: + </para> + <informaltable colsep="0" rowsep="0"> + <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="4Level-table"> + <colspec colname="1" colnum="1" colsep="0" colwidth="1.000in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="3.500in"/> + <tbody> + <row rowsep="0"> + <entry colname="1"> + <para> + owner name + </para> + </entry> + <entry colname="2"> + <para> + The domain name where the RR is found. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + type + </para> + </entry> + <entry colname="2"> + <para> + An encoded 16-bit value that specifies + the type of the resource record. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + TTL + </para> + </entry> + <entry colname="2"> + <para> + The time-to-live of the RR. This field + is a 32-bit integer in units of seconds, and is + primarily used by + resolvers when they cache RRs. The TTL describes how + long a RR can + be cached before it should be discarded. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + class + </para> + </entry> + <entry colname="2"> + <para> + An encoded 16-bit value that identifies + a protocol family or instance of a protocol. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + RDATA + </para> + </entry> + <entry colname="2"> + <para> + The resource data. The format of the + data is type (and sometimes class) specific. + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <para> + The following are <emphasis>types</emphasis> of valid RRs: + </para> + <informaltable colsep="0" rowsep="0"> + <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="4Level-table"> + <colspec colname="1" colnum="1" colsep="0" colwidth="0.875in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="3.625in"/> + <tbody> + <row rowsep="0"> + <entry colname="1"> + <para> + A + </para> + </entry> + <entry colname="2"> + <para> + A host address. In the IN class, this is a + 32-bit IP address. Described in RFC 1035. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + AAAA + </para> + </entry> + <entry colname="2"> + <para> + IPv6 address. Described in RFC 1886. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + A6 + </para> + </entry> + <entry colname="2"> + <para> + IPv6 address. This can be a partial + address (a suffix) and an indirection to the name + where the rest of the + address (the prefix) can be found. Experimental. + Described in RFC 2874. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + AFSDB + </para> + </entry> + <entry colname="2"> + <para> + Location of AFS database servers. + Experimental. Described in RFC 1183. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + APL + </para> + </entry> + <entry colname="2"> + <para> + Address prefix list. Experimental. + Described in RFC 3123. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + ATMA + </para> + </entry> + <entry colname="2"> + <para> + ATM Address. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + AVC + </para> + </entry> + <entry colname="2"> + <para> + Application Visibility and Control record. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + CAA + </para> + </entry> + <entry colname="2"> + <para> + Identifies which Certificate Authorities can issue + certificates for this domain and what rules they + need to follow when doing so. Defined in RFC 6844. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + CDNSKEY + </para> + </entry> + <entry colname="2"> + <para> + Identifies which DNSKEY records should be published + as DS records in the parent zone. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + CDS + </para> + </entry> + <entry colname="2"> + <para> + Contains the set of DS records that should be published + by the parent zone. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + CERT + </para> + </entry> + <entry colname="2"> + <para> + Holds a digital certificate. + Described in RFC 2538. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + CNAME + </para> + </entry> + <entry colname="2"> + <para> + Identifies the canonical name of an alias. + Described in RFC 1035. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + CSYNC + </para> + </entry> + <entry colname="2"> + <para> + Child-to-Parent Synchronization in DNS as described + in RFC 7477. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + DHCID + </para> + </entry> + <entry colname="2"> + <para> + Is used for identifying which DHCP client is + associated with this name. Described in RFC 4701. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + DLV + </para> + </entry> + <entry colname="2"> + <para> + A DNS Look-aside Validation record which contains + the records that are used as trust anchors for + zones in a DLV namespace. Described in RFC 4431. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + DNAME + </para> + </entry> + <entry colname="2"> + <para> + Replaces the domain name specified with + another name to be looked up, effectively aliasing an + entire + subtree of the domain name space rather than a single + record + as in the case of the CNAME RR. + Described in RFC 2672. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + DNSKEY + </para> + </entry> + <entry colname="2"> + <para> + Stores a public key associated with a signed + DNS zone. Described in RFC 4034. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + DOA + </para> + </entry> + <entry colname="2"> + <para> + Implements the Digital Object Architecture over + DNS. Experimental. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + DS + </para> + </entry> + <entry colname="2"> + <para> + Stores the hash of a public key associated with a + signed DNS zone. Described in RFC 4034. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + EID + </para> + </entry> + <entry colname="2"> + <para> + End Point Identifier. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + EUI48 + </para> + </entry> + <entry colname="2"> + <para> + A 48-bit EUI address. Described in RFC 7043. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + EUI64 + </para> + </entry> + <entry colname="2"> + <para> + A 64-bit EUI address. Described in RFC 7043. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + GID + </para> + </entry> + <entry colname="2"> + <para> + Reserved. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + GPOS + </para> + </entry> + <entry colname="2"> + <para> + Specifies the global position. Superseded by LOC. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + HINFO + </para> + </entry> + <entry colname="2"> + <para> + Identifies the CPU and OS used by a host. + Described in RFC 1035. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + HIP + </para> + </entry> + <entry colname="2"> + <para> + Host Identity Protocol Address. + Described in RFC 5205. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + IPSECKEY + </para> + </entry> + <entry colname="2"> + <para> + Provides a method for storing IPsec keying material in + DNS. Described in RFC 4025. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + ISDN + </para> + </entry> + <entry colname="2"> + <para> + Representation of ISDN addresses. + Experimental. Described in RFC 1183. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + KEY + </para> + </entry> + <entry colname="2"> + <para> + Stores a public key associated with a + DNS name. Used in original DNSSEC; replaced + by DNSKEY in DNSSECbis, but still used with + SIG(0). Described in RFCs 2535 and 2931. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + KX + </para> + </entry> + <entry colname="2"> + <para> + Identifies a key exchanger for this + DNS name. Described in RFC 2230. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + L32 + </para> + </entry> + <entry colname="2"> + <para> + Holds 32-bit Locator values for + Identifier-Locator Network Protocol. Described + in RFC 6742. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + L64 + </para> + </entry> + <entry colname="2"> + <para> + Holds 64-bit Locator values for + Identifier-Locator Network Protocol. Described + in RFC 6742. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + LOC + </para> + </entry> + <entry colname="2"> + <para> + For storing GPS info. Described in RFC 1876. + Experimental. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + LP + </para> + </entry> + <entry colname="2"> + <para> + Identifier-Locator Network Protocol. + Described in RFC 6742. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + MB + </para> + </entry> + <entry colname="2"> + <para> + Mail Box. Historical. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + MD + </para> + </entry> + <entry colname="2"> + <para> + Mail Destination. Historical. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + MF + </para> + </entry> + <entry colname="2"> + <para> + Mail Forwarder. Historical. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + MG + </para> + </entry> + <entry colname="2"> + <para> + Mail Group. Historical. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + MINFO + </para> + </entry> + <entry colname="2"> + <para> + Mail Information. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + MR + </para> + </entry> + <entry colname="2"> + <para> + Mail Rename. Historical. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + MX + </para> + </entry> + <entry colname="2"> + <para> + Identifies a mail exchange for the domain with + a 16-bit preference value (lower is better) + followed by the host name of the mail exchange. + Described in RFC 974, RFC 1035. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + NAPTR + </para> + </entry> + <entry colname="2"> + <para> + Name authority pointer. Described in RFC 2915. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + NID + </para> + </entry> + <entry colname="2"> + <para> + Holds values for Node Identifiers in + Identifier-Locator Network Protocol. Described + in RFC 6742. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + NINFO + </para> + </entry> + <entry colname="2"> + <para> + Contains zone status information. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + NIMLOC + </para> + </entry> + <entry colname="2"> + <para> + Nimrod Locator. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + NSAP + </para> + </entry> + <entry colname="2"> + <para> + A network service access point. + Described in RFC 1706. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + NSAP-PTR + </para> + </entry> + <entry colname="2"> + <para> + Historical. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + NS + </para> + </entry> + <entry colname="2"> + <para> + The authoritative name server for the + domain. Described in RFC 1035. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + NSEC + </para> + </entry> + <entry colname="2"> + <para> + Used in DNSSECbis to securely indicate that + RRs with an owner name in a certain name interval do + not exist in + a zone and indicate what RR types are present for an + existing name. + Described in RFC 4034. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + NSEC3 + </para> + </entry> + <entry colname="2"> + <para> + Used in DNSSECbis to securely indicate that + RRs with an owner name in a certain name + interval do not exist in a zone and indicate + what RR types are present for an existing + name. NSEC3 differs from NSEC in that it + prevents zone enumeration but is more + computationally expensive on both the server + and the client than NSEC. Described in RFC + 5155. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + NSEC3PARAM + </para> + </entry> + <entry colname="2"> + <para> + Used in DNSSECbis to tell the authoritative + server which NSEC3 chains are available to use. + Described in RFC 5155. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + NULL + </para> + </entry> + <entry colname="2"> + <para> + This is an opaque container. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + NXT + </para> + </entry> + <entry colname="2"> + <para> + Used in DNSSEC to securely indicate that + RRs with an owner name in a certain name interval do + not exist in + a zone and indicate what RR types are present for an + existing name. + Used in original DNSSEC; replaced by NSEC in + DNSSECbis. + Described in RFC 2535. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + OPENPGPKEY + </para> + </entry> + <entry colname="2"> + <para> + Used to hold an OPENPGPKEY. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + PTR + </para> + </entry> + <entry colname="2"> + <para> + A pointer to another part of the domain + name space. Described in RFC 1035. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + PX + </para> + </entry> + <entry colname="2"> + <para> + Provides mappings between RFC 822 and X.400 + addresses. Described in RFC 2163. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + RKEY + </para> + </entry> + <entry colname="2"> + <para> + Resource key. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + RP + </para> + </entry> + <entry colname="2"> + <para> + Information on persons responsible + for the domain. Experimental. Described in RFC 1183. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + RRSIG + </para> + </entry> + <entry colname="2"> + <para> + Contains DNSSECbis signature data. Described + in RFC 4034. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + RT + </para> + </entry> + <entry colname="2"> + <para> + Route-through binding for hosts that + do not have their own direct wide area network + addresses. + Experimental. Described in RFC 1183. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + SIG + </para> + </entry> + <entry colname="2"> + <para> + Contains DNSSEC signature data. Used in + original DNSSEC; replaced by RRSIG in + DNSSECbis, but still used for SIG(0). + Described in RFCs 2535 and 2931. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + SINK + </para> + </entry> + <entry colname="2"> + <para> + The kitchen sink record. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + SMIMEA + </para> + </entry> + <entry colname="2"> + <para> + The S/MIME Security Certificate Association. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + SOA + </para> + </entry> + <entry colname="2"> + <para> + Identifies the start of a zone of authority. + Described in RFC 1035. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + SPF + </para> + </entry> + <entry colname="2"> + <para> + Contains the Sender Policy Framework information + for a given email domain. Described in RFC 4408. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + SRV + </para> + </entry> + <entry colname="2"> + <para> + Information about well known network + services (replaces WKS). Described in RFC 2782. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + SSHFP + </para> + </entry> + <entry colname="2"> + <para> + Provides a way to securely publish a secure shell key's + fingerprint. Described in RFC 4255. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + TA + </para> + </entry> + <entry colname="2"> + <para> + Trust Anchor. Experimental. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + TALINK + </para> + </entry> + <entry colname="2"> + <para> + Trust Anchor Link. Experimental. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + TLSA + </para> + </entry> + <entry colname="2"> + <para> + Transport Layer Security Certificate Association. + Described in RFC 6698. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + TXT + </para> + </entry> + <entry colname="2"> + <para> + Text records. Described in RFC 1035. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + UID + </para> + </entry> + <entry colname="2"> + <para> + Reserved. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + UINFO + </para> + </entry> + <entry colname="2"> + <para> + Reserved. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + UNSPEC + </para> + </entry> + <entry colname="2"> + <para> + Reserved. Historical. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + URI + </para> + </entry> + <entry colname="2"> + <para> + Holds a URI. Described in RFC 7553. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + WKS + </para> + </entry> + <entry colname="2"> + <para> + Information about which well known + network services, such as SMTP, that a domain + supports. Historical. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + X25 + </para> + </entry> + <entry colname="2"> + <para> + Representation of X.25 network addresses. + Experimental. Described in RFC 1183. + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <para> + The following <emphasis>classes</emphasis> of resource records + are currently valid in the DNS: + </para> + <informaltable colsep="0" rowsep="0"><tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="4Level-table"> + <colspec colname="1" colnum="1" colsep="0" colwidth="0.875in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="3.625in"/> + <tbody> + + <row rowsep="0"> + <entry colname="1"> + <para> + IN + </para> + </entry> + <entry colname="2"> + <para> + The Internet. + </para> + </entry> + </row> + + <row rowsep="0"> + <entry colname="1"> + <para> + CH + </para> + </entry> + <entry colname="2"> + <para> + Chaosnet, a LAN protocol created at MIT in the + mid-1970s. + Rarely used for its historical purpose, but reused for + BIND's + built-in server information zones, e.g., + <literal>version.bind</literal>. + </para> + </entry> + </row> + + <row rowsep="0"> + <entry colname="1"> + <para> + HS + </para> + </entry> + <entry colname="2"> + <para> + Hesiod, an information service + developed by MIT's Project Athena. It is used to share + information + about various systems databases, such as users, + groups, printers + and so on. + </para> + </entry> + </row> + + </tbody> + </tgroup> + </informaltable> + + <para> + The owner name is often implicit, rather than forming an + integral + part of the RR. For example, many name servers internally form + tree + or hash structures for the name space, and chain RRs off nodes. + The remaining RR parts are the fixed header (type, class, TTL) + which is consistent for all RRs, and a variable part (RDATA) + that + fits the needs of the resource being described. + </para> + <para> + The meaning of the TTL field is a time limit on how long an + RR can be kept in a cache. This limit does not apply to + authoritative + data in zones; it is also timed out, but by the refreshing + policies + for the zone. The TTL is assigned by the administrator for the + zone where the data originates. While short TTLs can be used to + minimize caching, and a zero TTL prohibits caching, the + realities + of Internet performance suggest that these times should be on + the + order of days for the typical host. If a change can be + anticipated, + the TTL can be reduced prior to the change to minimize + inconsistency + during the change, and then increased back to its former value + following + the change. + </para> + <para> + The data in the RDATA section of RRs is carried as a combination + of binary strings and domain names. The domain names are + frequently + used as "pointers" to other data in the DNS. + </para> + </section> + <section xml:id="rr_text"><info><title>Textual expression of RRs</title></info> + + <para> + RRs are represented in binary form in the packets of the DNS + protocol, and are usually represented in highly encoded form + when + stored in a name server or resolver. In the examples provided + in + RFC 1034, a style similar to that used in master files was + employed + in order to show the contents of RRs. In this format, most RRs + are shown on a single line, although continuation lines are + possible + using parentheses. + </para> + <para> + The start of the line gives the owner of the RR. If a line + begins with a blank, then the owner is assumed to be the same as + that of the previous RR. Blank lines are often included for + readability. + </para> + <para> + Following the owner, we list the TTL, type, and class of the + RR. Class and type use the mnemonics defined above, and TTL is + an integer before the type field. In order to avoid ambiguity + in + parsing, type and class mnemonics are disjoint, TTLs are + integers, + and the type mnemonic is always last. The IN class and TTL + values + are often omitted from examples in the interests of clarity. + </para> + <para> + The resource data or RDATA section of the RR are given using + knowledge of the typical representation for the data. + </para> + <para> + For example, we might show the RRs carried in a message as: + </para> + <informaltable colsep="0" rowsep="0"><tgroup cols="3" colsep="0" rowsep="0" tgroupstyle="4Level-table"> + <colspec colname="1" colnum="1" colsep="0" colwidth="1.381in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="1.020in"/> + <colspec colname="3" colnum="3" colsep="0" colwidth="2.099in"/> + <tbody> + <row rowsep="0"> + <entry colname="1"> + <para> + <literal>ISI.EDU.</literal> + </para> + </entry> + <entry colname="2"> + <para> + <literal>MX</literal> + </para> + </entry> + <entry colname="3"> + <para> + <literal>10 VENERA.ISI.EDU.</literal> + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para/> + </entry> + <entry colname="2"> + <para> + <literal>MX</literal> + </para> + </entry> + <entry colname="3"> + <para> + <literal>10 VAXA.ISI.EDU</literal> + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <literal>VENERA.ISI.EDU</literal> + </para> + </entry> + <entry colname="2"> + <para> + <literal>A</literal> + </para> + </entry> + <entry colname="3"> + <para> + <literal>128.9.0.32</literal> + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para/> + </entry> + <entry colname="2"> + <para> + <literal>A</literal> + </para> + </entry> + <entry colname="3"> + <para> + <literal>10.1.0.52</literal> + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <literal>VAXA.ISI.EDU</literal> + </para> + </entry> + <entry colname="2"> + <para> + <literal>A</literal> + </para> + </entry> + <entry colname="3"> + <para> + <literal>10.2.0.27</literal> + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para/> + </entry> + <entry colname="2"> + <para> + <literal>A</literal> + </para> + </entry> + <entry colname="3"> + <para> + <literal>128.9.0.33</literal> + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <para> + The MX RRs have an RDATA section which consists of a 16-bit + number followed by a domain name. The address RRs use a + standard + IP address format to contain a 32-bit internet address. + </para> + <para> + The above example shows six RRs, with two RRs at each of three + domain names. + </para> + <para> + Similarly we might see: + </para> + <informaltable colsep="0" rowsep="0"><tgroup cols="3" colsep="0" rowsep="0" tgroupstyle="4Level-table"> + <colspec colname="1" colnum="1" colsep="0" colwidth="1.491in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="1.067in"/> + <colspec colname="3" colnum="3" colsep="0" colwidth="2.067in"/> + <tbody> + <row rowsep="0"> + <entry colname="1"> + <para> + <literal>XX.LCS.MIT.EDU.</literal> + </para> + </entry> + <entry colname="2"> + <para> + <literal>IN A</literal> + </para> + </entry> + <entry colname="3"> + <para> + <literal>10.0.0.44</literal> + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"/> + <entry colname="2"> + <para> + <literal>CH A</literal> + </para> + </entry> + <entry colname="3"> + <para> + <literal>MIT.EDU. 2420</literal> + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <para> + This example shows two addresses for + <literal>XX.LCS.MIT.EDU</literal>, each of a different class. + </para> + </section> + </section> + + <section xml:id="mx_records"><info><title>Discussion of MX Records</title></info> + + <para> + As described above, domain servers store information as a + series of resource records, each of which contains a particular + piece of information about a given domain name (which is usually, + but not always, a host). The simplest way to think of a RR is as + a typed pair of data, a domain name matched with a relevant datum, + and stored with some additional type information to help systems + determine when the RR is relevant. + </para> + + <para> + MX records are used to control delivery of email. The data + specified in the record is a priority and a domain name. The + priority + controls the order in which email delivery is attempted, with the + lowest number first. If two priorities are the same, a server is + chosen randomly. If no servers at a given priority are responding, + the mail transport agent will fall back to the next largest + priority. + Priority numbers do not have any absolute meaning — they are + relevant + only respective to other MX records for that domain name. The + domain + name given is the machine to which the mail will be delivered. + It <emphasis>must</emphasis> have an associated address record + (A or AAAA) — CNAME is not sufficient. + </para> + <para> + For a given domain, if there is both a CNAME record and an + MX record, the MX record is in error, and will be ignored. + Instead, + the mail will be delivered to the server specified in the MX + record + pointed to by the CNAME. + For example: + </para> + <informaltable colsep="0" rowsep="0"> + <tgroup cols="5" colsep="0" rowsep="0" tgroupstyle="3Level-table"> + <colspec colname="1" colnum="1" colsep="0" colwidth="1.708in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="0.444in"/> + <colspec colname="3" colnum="3" colsep="0" colwidth="0.444in"/> + <colspec colname="4" colnum="4" colsep="0" colwidth="0.976in"/> + <colspec colname="5" colnum="5" colsep="0" colwidth="1.553in"/> + <tbody> + <row rowsep="0"> + <entry colname="1"> + <para> + <literal>example.com.</literal> + </para> + </entry> + <entry colname="2"> + <para> + <literal>IN</literal> + </para> + </entry> + <entry colname="3"> + <para> + <literal>MX</literal> + </para> + </entry> + <entry colname="4"> + <para> + <literal>10</literal> + </para> + </entry> + <entry colname="5"> + <para> + <literal>mail.example.com.</literal> + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para/> + </entry> + <entry colname="2"> + <para> + <literal>IN</literal> + </para> + </entry> + <entry colname="3"> + <para> + <literal>MX</literal> + </para> + </entry> + <entry colname="4"> + <para> + <literal>10</literal> + </para> + </entry> + <entry colname="5"> + <para> + <literal>mail2.example.com.</literal> + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para/> + </entry> + <entry colname="2"> + <para> + <literal>IN</literal> + </para> + </entry> + <entry colname="3"> + <para> + <literal>MX</literal> + </para> + </entry> + <entry colname="4"> + <para> + <literal>20</literal> + </para> + </entry> + <entry colname="5"> + <para> + <literal>mail.backup.org.</literal> + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <literal>mail.example.com.</literal> + </para> + </entry> + <entry colname="2"> + <para> + <literal>IN</literal> + </para> + </entry> + <entry colname="3"> + <para> + <literal>A</literal> + </para> + </entry> + <entry colname="4"> + <para> + <literal>10.0.0.1</literal> + </para> + </entry> + <entry colname="5"> + <para/> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <literal>mail2.example.com.</literal> + </para> + </entry> + <entry colname="2"> + <para> + <literal>IN</literal> + </para> + </entry> + <entry colname="3"> + <para> + <literal>A</literal> + </para> + </entry> + <entry colname="4"> + <para> + <literal>10.0.0.2</literal> + </para> + </entry> + <entry colname="5"> + <para/> + </entry> + </row> + </tbody> + </tgroup> + </informaltable><para> + Mail delivery will be attempted to <literal>mail.example.com</literal> and + <literal>mail2.example.com</literal> (in + any order), and if neither of those succeed, delivery to <literal>mail.backup.org</literal> will + be attempted. + </para> + </section> + <section xml:id="Setting_TTLs"><info><title>Setting TTLs</title></info> + + <para> + The time-to-live of the RR field is a 32-bit integer represented + in units of seconds, and is primarily used by resolvers when they + cache RRs. The TTL describes how long a RR can be cached before it + should be discarded. The following three types of TTL are + currently + used in a zone file. + </para> + <informaltable colsep="0" rowsep="0"> + <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="3Level-table"> + <colspec colname="1" colnum="1" colsep="0" colwidth="0.750in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="4.375in"/> + <tbody> + <row rowsep="0"> + <entry colname="1"> + <para> + SOA + </para> + </entry> + <entry colname="2"> + <para> + The last field in the SOA is the negative + caching TTL. This controls how long other servers will + cache no-such-domain + (NXDOMAIN) responses from you. + </para> + <para> + The maximum time for + negative caching is 3 hours (3h). + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + $TTL + </para> + </entry> + <entry colname="2"> + <para> + The $TTL directive at the top of the + zone file (before the SOA) gives a default TTL for every + RR without + a specific TTL set. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + RR TTLs + </para> + </entry> + <entry colname="2"> + <para> + Each RR can have a TTL as the second + field in the RR, which will control how long other + servers can cache it. + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <para> + All of these TTLs default to units of seconds, though units + can be explicitly specified, for example, <literal>1h30m</literal>. + </para> + </section> + <section xml:id="ipv4_reverse"><info><title>Inverse Mapping in IPv4</title></info> + + <para> + Reverse name resolution (that is, translation from IP address + to name) is achieved by means of the <emphasis>in-addr.arpa</emphasis> domain + and PTR records. Entries in the in-addr.arpa domain are made in + least-to-most significant order, read left to right. This is the + opposite order to the way IP addresses are usually written. Thus, + a machine with an IP address of 10.1.2.3 would have a + corresponding + in-addr.arpa name of + 3.2.1.10.in-addr.arpa. This name should have a PTR resource record + whose data field is the name of the machine or, optionally, + multiple + PTR records if the machine has more than one name. For example, + in the <optional>example.com</optional> domain: + </para> + <informaltable colsep="0" rowsep="0"> + <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="3Level-table"> + <colspec colname="1" colnum="1" colsep="0" colwidth="1.125in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="4.000in"/> + <tbody> + <row rowsep="0"> + <entry colname="1"> + <para> + <literal>$ORIGIN</literal> + </para> + </entry> + <entry colname="2"> + <para> + <literal>2.1.10.in-addr.arpa</literal> + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <literal>3</literal> + </para> + </entry> + <entry colname="2"> + <para> + <literal>IN PTR foo.example.com.</literal> + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <note> + <para> + The <command>$ORIGIN</command> lines in the examples + are for providing context to the examples only — they do not + necessarily + appear in the actual usage. They are only used here to indicate + that the example is relative to the listed origin. + </para> + </note> + </section> + <section xml:id="zone_directives"><info><title>Other Zone File Directives</title></info> + + <para> + The Master File Format was initially defined in RFC 1035 and + has subsequently been extended. While the Master File Format + itself + is class independent all records in a Master File must be of the + same + class. + </para> + <para> + Master File Directives include <command>$ORIGIN</command>, <command>$INCLUDE</command>, + and <command>$TTL.</command> + </para> + <section xml:id="atsign"><info><title>The <command>@</command> (at-sign)</title></info> + + <para> + When used in the label (or name) field, the asperand or + at-sign (@) symbol represents the current origin. + At the start of the zone file, it is the + <<varname>zone_name</varname>> (followed by + trailing dot). + </para> + </section> + <section xml:id="origin_directive"><info><title>The <command>$ORIGIN</command> Directive</title></info> + + <para> + Syntax: <command>$ORIGIN</command> + <replaceable>domain-name</replaceable> + <optional><replaceable>comment</replaceable></optional> + </para> + <para><command>$ORIGIN</command> + sets the domain name that will be appended to any + unqualified records. When a zone is first read in there + is an implicit <command>$ORIGIN</command> + <<varname>zone_name</varname>><command>.</command> + (followed by trailing dot). + The current <command>$ORIGIN</command> is appended to + the domain specified in the <command>$ORIGIN</command> + argument if it is not absolute. + </para> + +<programlisting> +$ORIGIN example.com. +WWW CNAME MAIN-SERVER +</programlisting> + + <para> + is equivalent to + </para> + +<programlisting> +WWW.EXAMPLE.COM. CNAME MAIN-SERVER.EXAMPLE.COM. +</programlisting> + + </section> + <section xml:id="include_directive"><info><title>The <command>$INCLUDE</command> Directive</title></info> + + <para> + Syntax: <command>$INCLUDE</command> + <replaceable>filename</replaceable> + <optional> +<replaceable>origin</replaceable> </optional> + <optional> <replaceable>comment</replaceable> </optional> + </para> + <para> + Read and process the file <filename>filename</filename> as + if it were included into the file at this point. If <command>origin</command> is + specified the file is processed with <command>$ORIGIN</command> set + to that value, otherwise the current <command>$ORIGIN</command> is + used. + </para> + <para> + The origin and the current domain name + revert to the values they had prior to the <command>$INCLUDE</command> once + the file has been read. + </para> + <note> + <para> + RFC 1035 specifies that the current origin should be restored + after + an <command>$INCLUDE</command>, but it is silent + on whether the current + domain name should also be restored. BIND 9 restores both of + them. + This could be construed as a deviation from RFC 1035, a + feature, or both. + </para> + </note> + </section> + <section xml:id="ttl_directive"><info><title>The <command>$TTL</command> Directive</title></info> + + <para> + Syntax: <command>$TTL</command> + <replaceable>default-ttl</replaceable> + <optional> +<replaceable>comment</replaceable> </optional> + </para> + <para> + Set the default Time To Live (TTL) for subsequent records + with undefined TTLs. Valid TTLs are of the range 0-2147483647 + seconds. + </para> + <para><command>$TTL</command> + is defined in RFC 2308. + </para> + </section> + </section> + <section xml:id="generate_directive"><info><title><acronym>BIND</acronym> Master File Extension: the <command>$GENERATE</command> Directive</title></info> + + <para> + Syntax: <command>$GENERATE</command> + <replaceable>range</replaceable> + <replaceable>lhs</replaceable> + <optional><replaceable>ttl</replaceable></optional> + <optional><replaceable>class</replaceable></optional> + <replaceable>type</replaceable> + <replaceable>rhs</replaceable> + <optional><replaceable>comment</replaceable></optional> + </para> + <para><command>$GENERATE</command> + is used to create a series of resource records that only + differ from each other by an + iterator. <command>$GENERATE</command> can be used to + easily generate the sets of records required to support + sub /24 reverse delegations described in RFC 2317: + Classless IN-ADDR.ARPA delegation. + </para> + +<programlisting>$ORIGIN 0.0.192.IN-ADDR.ARPA. +$GENERATE 1-2 @ NS SERVER$.EXAMPLE. +$GENERATE 1-127 $ CNAME $.0</programlisting> + + <para> + is equivalent to + </para> + +<programlisting>0.0.0.192.IN-ADDR.ARPA. NS SERVER1.EXAMPLE. +0.0.0.192.IN-ADDR.ARPA. NS SERVER2.EXAMPLE. +1.0.0.192.IN-ADDR.ARPA. CNAME 1.0.0.0.192.IN-ADDR.ARPA. +2.0.0.192.IN-ADDR.ARPA. CNAME 2.0.0.0.192.IN-ADDR.ARPA. +... +127.0.0.192.IN-ADDR.ARPA. CNAME 127.0.0.0.192.IN-ADDR.ARPA. +</programlisting> + + <para> + Generate a set of A and MX records. Note the MX's right hand + side is a quoted string. The quotes will be stripped when the + right hand side is processed. + </para> + +<programlisting> +$ORIGIN EXAMPLE. +$GENERATE 1-127 HOST-$ A 1.2.3.$ +$GENERATE 1-127 HOST-$ MX "0 ."</programlisting> + + <para> + is equivalent to + </para> + +<programlisting>HOST-1.EXAMPLE. A 1.2.3.1 +HOST-1.EXAMPLE. MX 0 . +HOST-2.EXAMPLE. A 1.2.3.2 +HOST-2.EXAMPLE. MX 0 . +HOST-3.EXAMPLE. A 1.2.3.3 +HOST-3.EXAMPLE. MX 0 . +... +HOST-127.EXAMPLE. A 1.2.3.127 +HOST-127.EXAMPLE. MX 0 . +</programlisting> + + <informaltable colsep="0" rowsep="0"> + <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="3Level-table"> + <colspec colname="1" colnum="1" colsep="0" colwidth="0.875in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="4.250in"/> + <tbody> + <row rowsep="0"> + <entry colname="1"> + <para><command>range</command></para> + </entry> + <entry colname="2"> + <para> + This can be one of two forms: start-stop + or start-stop/step. If the first form is used, then step + is set to 1. start, stop and step must be positive + integers between 0 and (2^31)-1. start must not be + larger than stop. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>lhs</command></para> + </entry> + <entry colname="2"> + <para>This + describes the owner name of the resource records + to be created. Any single <command>$</command> + (dollar sign) + symbols within the <command>lhs</command> string + are replaced by the iterator value. + + To get a $ in the output, you need to escape the + <command>$</command> using a backslash + <command>\</command>, + e.g. <command>\$</command>. The + <command>$</command> may optionally be followed + by modifiers which change the offset from the + iterator, field width and base. + + Modifiers are introduced by a + <command>{</command> (left brace) immediately following the + <command>$</command> as + <command>${offset[,width[,base]]}</command>. + For example, <command>${-20,3,d}</command> + subtracts 20 from the current value, prints the + result as a decimal in a zero-padded field of + width 3. + + Available output forms are decimal + (<command>d</command>), octal + (<command>o</command>), hexadecimal + (<command>x</command> or <command>X</command> + for uppercase) and nibble + (<command>n</command> or <command>N</command>\ + for uppercase). The default modifier is + <command>${0,0,d}</command>. If the + <command>lhs</command> is not absolute, the + current <command>$ORIGIN</command> is appended + to the name. + </para> + <para> + In nibble mode the value will be treated as + if it was a reversed hexadecimal string + with each hexadecimal digit as a separate + label. The width field includes the label + separator. + </para> + <para> + For compatibility with earlier versions, + <command>$$</command> is still recognized as + indicating a literal $ in the output. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>ttl</command></para> + </entry> + <entry colname="2"> + <para> + Specifies the time-to-live of the generated records. If + not specified this will be inherited using the + normal TTL inheritance rules. + </para> + <para><command>class</command> + and <command>ttl</command> can be + entered in either order. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>class</command></para> + </entry> + <entry colname="2"> + <para> + Specifies the class of the generated records. + This must match the zone class if it is + specified. + </para> + <para><command>class</command> + and <command>ttl</command> can be + entered in either order. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>type</command></para> + </entry> + <entry colname="2"> + <para> + Any valid type. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>rhs</command></para> + </entry> + <entry colname="2"> + <para> + <command>rhs</command>, optionally, quoted string. + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <para> + The <command>$GENERATE</command> directive is a <acronym>BIND</acronym> extension + and not part of the standard zone file format. + </para> + <para> + BIND 8 did not support the optional TTL and CLASS fields. + </para> + </section> + + <section xml:id="zonefile_format"><info><title>Additional File Formats</title></info> + + <para> + In addition to the standard textual format, BIND 9 + supports the ability to read or dump to zone files in + other formats. + </para> + <para> + The <constant>raw</constant> format is + a binary representation of zone data in a manner similar + to that used in zone transfers. Since it does not require + parsing text, load time is significantly reduced. + </para> + <para> + An even faster alternative is the <constant>map</constant> + format, which is an image of a <acronym>BIND</acronym> 9 + in-memory zone database; it is capable of being loaded + directly into memory via the <command>mmap()</command> + function; the zone can begin serving queries almost + immediately. + </para> + <para> + For a primary server, a zone file in + <constant>raw</constant> or <constant>map</constant> + format is expected to be generated from a textual zone + file by the <command>named-compilezone</command> command. + For a secondary server or for a dynamic zone, it is automatically + generated (if this format is specified by the + <command>masterfile-format</command> option) when + <command>named</command> dumps the zone contents after + zone transfer or when applying prior updates. + </para> + <para> + If a zone file in a binary format needs manual modification, + it first must be converted to a textual form by the + <command>named-compilezone</command> command. All + necessary modification should go to the text file, which + should then be converted to the binary form by the + <command>named-compilezone</command> command again. + </para> + <para> + Note that <command>map</command> format is extremely + architecture-specific. A <constant>map</constant> + file <emphasis>cannot</emphasis> be used on a system + with different pointer size, endianness or data alignment + than the system on which it was generated, and should in + general be used only inside a single system. + While <constant>raw</constant> format uses + network byte order and avoids architecture-dependent + data alignment so that it is as portable as + possible, it is also primarily expected to be used + inside the same single system. To export a + zone file in either <constant>raw</constant> or + <constant>map</constant> format, or make a + portable backup of such a file, conversion to + <constant>text</constant> format is recommended. + </para> + </section> + </section> + + <section xml:id="statistics"><info><title>BIND9 Statistics</title></info> + + <para> + <acronym>BIND</acronym> 9 maintains lots of statistics + information and provides several interfaces for users to + get access to the statistics. + The available statistics include all statistics counters + that were available in <acronym>BIND</acronym> 8 and + are meaningful in <acronym>BIND</acronym> 9, + and other information that is considered useful. + </para> + + <para> + The statistics information is categorized into the following + sections. + </para> + + <informaltable frame="all"> + <tgroup cols="2"> + <colspec colname="1" colnum="1" colsep="0" colwidth="3.300in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="2.625in"/> + <tbody> + + <row rowsep="0"> + <entry colname="1"> + <para>Incoming Requests</para> + </entry> + <entry colname="2"> + <para> + The number of incoming DNS requests for each OPCODE. + </para> + </entry> + </row> + + <row rowsep="0"> + <entry colname="1"> + <para>Incoming Queries</para> + </entry> + <entry colname="2"> + <para> + The number of incoming queries for each RR type. + </para> + </entry> + </row> + + <row rowsep="0"> + <entry colname="1"> + <para>Outgoing Queries</para> + </entry> + <entry colname="2"> + <para> + The number of outgoing queries for each RR + type sent from the internal resolver. + Maintained per view. + </para> + </entry> + </row> + + <row rowsep="0"> + <entry colname="1"> + <para>Name Server Statistics</para> + </entry> + <entry colname="2"> + <para> + Statistics counters about incoming request processing. + </para> + </entry> + </row> + + <row rowsep="0"> + <entry colname="1"> + <para>Zone Maintenance Statistics</para> + </entry> + <entry colname="2"> + <para> + Statistics counters regarding zone maintenance + operations such as zone transfers. + </para> + </entry> + </row> + + <row rowsep="0"> + <entry colname="1"> + <para>Resolver Statistics</para> + </entry> + <entry colname="2"> + <para> + Statistics counters about name resolution + performed in the internal resolver. + Maintained per view. + </para> + </entry> + </row> + + <row rowsep="0"> + <entry colname="1"> + <para>Cache DB RRsets</para> + </entry> + <entry colname="2"> + <para> + The number of RRsets per RR type and nonexistent + names stored in the cache database. + If the exclamation mark (!) is printed for a RR + type, it means that particular type of RRset is + known to be nonexistent (this is also known as + "NXRRSET"). If a hash mark (#) is present then + the RRset is marked for garbage collection. + Maintained per view. + </para> + </entry> + </row> + + <row rowsep="0"> + <entry colname="1"> + <para>Socket I/O Statistics</para> + </entry> + <entry colname="2"> + <para> + Statistics counters about network related events. + </para> + </entry> + </row> + + </tbody> + </tgroup> + </informaltable> + + <para> + A subset of Name Server Statistics is collected and shown + per zone for which the server has the authority when + <command>zone-statistics</command> is set to + <userinput>full</userinput> (or <userinput>yes</userinput> + for backward compatibility. See the description of + <command>zone-statistics</command> in <xref linkend="options"/> + for further details. + </para> + + <para> + These statistics counters are shown with their zone and + view names. The view name is omitted when the server is + not configured with explicit views.</para> + + <para> + There are currently two user interfaces to get access to the + statistics. + One is in the plain text format dumped to the file specified + by the <command>statistics-file</command> configuration option. + The other is remotely accessible via a statistics channel + when the <command>statistics-channels</command> statement + is specified in the configuration file + (see <xref linkend="statschannels"/>.) + </para> + + <section xml:id="statsfile"><info><title>The Statistics File</title></info> + + <para> + The text format statistics dump begins with a line, like: + </para> + <para> + <command>+++ Statistics Dump +++ (973798949)</command> + </para> + <para> + The number in parentheses is a standard + Unix-style timestamp, measured as seconds since January 1, 1970. + + Following + that line is a set of statistics information, which is categorized + as described above. + Each section begins with a line, like: + </para> + + <para> + <command>++ Name Server Statistics ++</command> + </para> + + <para> + Each section consists of lines, each containing the statistics + counter value followed by its textual description. + See below for available counters. + For brevity, counters that have a value of 0 are not shown + in the statistics file. + </para> + + <para> + The statistics dump ends with the line where the + number is identical to the number in the beginning line; for example: + </para> + <para> + <command>--- Statistics Dump --- (973798949)</command> + </para> + </section> + + <section xml:id="statistics_counters"><info><title>Statistics Counters</title></info> + + <para> + The following tables summarize statistics counters that + <acronym>BIND</acronym> 9 provides. + For each row of the tables, the leftmost column is the + abbreviated symbol name of that counter. + These symbols are shown in the statistics information + accessed via an HTTP statistics channel. + The rightmost column gives the description of the counter, + which is also shown in the statistics file + (but, in this document, possibly with slight modification + for better readability). + Additional notes may also be provided in this column. + When a middle column exists between these two columns, + it gives the corresponding counter name of the + <acronym>BIND</acronym> 8 statistics, if applicable. + </para> + + <section xml:id="stats_counters"><info><title>Name Server Statistics Counters</title></info> + + <informaltable colsep="0" rowsep="0"> + <tgroup cols="3" colsep="0" rowsep="0" tgroupstyle="4Level-table"> + <colspec colname="1" colnum="1" colsep="0" colwidth="1.150in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="1.150in"/> + <colspec colname="3" colnum="3" colsep="0" colwidth="3.350in"/> + <tbody> + <row> + <entry colname="1"> + <para> + <emphasis>Symbol</emphasis> + </para> + </entry> + <entry colname="2"> + <para> + <emphasis>BIND8 Symbol</emphasis> + </para> + </entry> + <entry colname="3"> + <para> + <emphasis>Description</emphasis> + </para> + </entry> + </row> + + <row rowsep="0"> + <entry colname="1"> + <para><command>Requestv4</command></para> + </entry> + <entry colname="2"> + <para><command>RQ</command></para> + </entry> + <entry colname="3"> + <para> + IPv4 requests received. + Note: this also counts non query requests. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>Requestv6</command></para> + </entry> + <entry colname="2"> + <para><command>RQ</command></para> + </entry> + <entry colname="3"> + <para> + IPv6 requests received. + Note: this also counts non query requests. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>ReqEdns0</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Requests with EDNS(0) received. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>ReqBadEDNSVer</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Requests with unsupported EDNS version received. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>ReqTSIG</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Requests with TSIG received. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>ReqSIG0</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Requests with SIG(0) received. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>ReqBadSIG</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Requests with invalid (TSIG or SIG(0)) signature. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>ReqTCP</command></para> + </entry> + <entry colname="2"> + <para><command>RTCP</command></para> + </entry> + <entry colname="3"> + <para> + TCP requests received. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>AuthQryRej</command></para> + </entry> + <entry colname="2"> + <para><command>RUQ</command></para> + </entry> + <entry colname="3"> + <para> + Authoritative (non recursive) queries rejected. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>RecQryRej</command></para> + </entry> + <entry colname="2"> + <para><command>RURQ</command></para> + </entry> + <entry colname="3"> + <para> + Recursive queries rejected. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>XfrRej</command></para> + </entry> + <entry colname="2"> + <para><command>RUXFR</command></para> + </entry> + <entry colname="3"> + <para> + Zone transfer requests rejected. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>UpdateRej</command></para> + </entry> + <entry colname="2"> + <para><command>RUUpd</command></para> + </entry> + <entry colname="3"> + <para> + Dynamic update requests rejected. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>Response</command></para> + </entry> + <entry colname="2"> + <para><command>SAns</command></para> + </entry> + <entry colname="3"> + <para> + Responses sent. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>RespTruncated</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Truncated responses sent. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>RespEDNS0</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Responses with EDNS(0) sent. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>RespTSIG</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Responses with TSIG sent. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>RespSIG0</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Responses with SIG(0) sent. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>QrySuccess</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Queries resulted in a successful answer. + This means the query which returns a NOERROR response + with at least one answer RR. + This corresponds to the + <command>success</command> counter + of previous versions of + <acronym>BIND</acronym> 9. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>QryAuthAns</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Queries resulted in authoritative answer. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>QryNoauthAns</command></para> + </entry> + <entry colname="2"> + <para><command>SNaAns</command></para> + </entry> + <entry colname="3"> + <para> + Queries resulted in non authoritative answer. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>QryReferral</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Queries resulted in referral answer. + This corresponds to the + <command>referral</command> counter + of previous versions of + <acronym>BIND</acronym> 9. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>QryNxrrset</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Queries resulted in NOERROR responses with no data. + This corresponds to the + <command>nxrrset</command> counter + of previous versions of + <acronym>BIND</acronym> 9. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>QrySERVFAIL</command></para> + </entry> + <entry colname="2"> + <para><command>SFail</command></para> + </entry> + <entry colname="3"> + <para> + Queries resulted in SERVFAIL. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>QryFORMERR</command></para> + </entry> + <entry colname="2"> + <para><command>SFErr</command></para> + </entry> + <entry colname="3"> + <para> + Queries resulted in FORMERR. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>QryNXDOMAIN</command></para> + </entry> + <entry colname="2"> + <para><command>SNXD</command></para> + </entry> + <entry colname="3"> + <para> + Queries resulted in NXDOMAIN. + This corresponds to the + <command>nxdomain</command> counter + of previous versions of + <acronym>BIND</acronym> 9. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>QryRecursion</command></para> + </entry> + <entry colname="2"> + <para><command>RFwdQ</command></para> + </entry> + <entry colname="3"> + <para> + Queries which caused the server + to perform recursion in order to find the final answer. + This corresponds to the + <command>recursion</command> counter + of previous versions of + <acronym>BIND</acronym> 9. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>QryDuplicate</command></para> + </entry> + <entry colname="2"> + <para><command>RDupQ</command></para> + </entry> + <entry colname="3"> + <para> + Queries which the server attempted to + recurse but discovered an existing query with the same + IP address, port, query ID, name, type and class + already being processed. + This corresponds to the + <command>duplicate</command> counter + of previous versions of + <acronym>BIND</acronym> 9. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>QryDropped</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Recursive queries for which the server + discovered an excessive number of existing + recursive queries for the same name, type and + class and were subsequently dropped. + This is the number of dropped queries due to + the reason explained with the + <command>clients-per-query</command> + and + <command>max-clients-per-query</command> + options + (see the description about + <xref endterm="cpq_term" linkend="clients-per-query"/>.) + This corresponds to the + <command>dropped</command> counter + of previous versions of + <acronym>BIND</acronym> 9. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>QryFailure</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Other query failures. + This corresponds to the + <command>failure</command> counter + of previous versions of + <acronym>BIND</acronym> 9. + Note: this counter is provided mainly for + backward compatibility with the previous versions. + Normally a more fine-grained counters such as + <command>AuthQryRej</command> and + <command>RecQryRej</command> + that would also fall into this counter are provided, + and so this counter would not be of much + interest in practice. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>QryNXRedir</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Queries resulted in NXDOMAIN that were redirected. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>QryNXRedirRLookup</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Queries resulted in NXDOMAIN that were redirected + and resulted in a successful remote lookup. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>XfrReqDone</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Requested zone transfers completed. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>UpdateReqFwd</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Update requests forwarded. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>UpdateRespFwd</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Update responses forwarded. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>UpdateFwdFail</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Dynamic update forward failed. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>UpdateDone</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Dynamic updates completed. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>UpdateFail</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Dynamic updates failed. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>UpdateBadPrereq</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Dynamic updates rejected due to prerequisite failure. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>RateDropped</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Responses dropped by rate limits. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>RateSlipped</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Responses truncated by rate limits. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>RPZRewrites</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Response policy zone rewrites. + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </section> + + <section xml:id="zone_stats"><info><title>Zone Maintenance Statistics Counters</title></info> + + <informaltable colsep="0" rowsep="0"> + <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="4Level-table"> + <colspec colname="1" colnum="1" colsep="0" colwidth="1.150in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="3.350in"/> + <tbody> + <row> + <entry colname="1"> + <para> + <emphasis>Symbol</emphasis> + </para> + </entry> + <entry colname="2"> + <para> + <emphasis>Description</emphasis> + </para> + </entry> + </row> + + <row rowsep="0"> + <entry colname="1"> + <para><command>NotifyOutv4</command></para> + </entry> + <entry colname="2"> + <para> + IPv4 notifies sent. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>NotifyOutv6</command></para> + </entry> + <entry colname="2"> + <para> + IPv6 notifies sent. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>NotifyInv4</command></para> + </entry> + <entry colname="2"> + <para> + IPv4 notifies received. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>NotifyInv6</command></para> + </entry> + <entry colname="2"> + <para> + IPv6 notifies received. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>NotifyRej</command></para> + </entry> + <entry colname="2"> + <para> + Incoming notifies rejected. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>SOAOutv4</command></para> + </entry> + <entry colname="2"> + <para> + IPv4 SOA queries sent. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>SOAOutv6</command></para> + </entry> + <entry colname="2"> + <para> + IPv6 SOA queries sent. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>AXFRReqv4</command></para> + </entry> + <entry colname="2"> + <para> + IPv4 AXFR requested. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>AXFRReqv6</command></para> + </entry> + <entry colname="2"> + <para> + IPv6 AXFR requested. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>IXFRReqv4</command></para> + </entry> + <entry colname="2"> + <para> + IPv4 IXFR requested. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>IXFRReqv6</command></para> + </entry> + <entry colname="2"> + <para> + IPv6 IXFR requested. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>XfrSuccess</command></para> + </entry> + <entry colname="2"> + <para> + Zone transfer requests succeeded. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>XfrFail</command></para> + </entry> + <entry colname="2"> + <para> + Zone transfer requests failed. + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </section> + + <section xml:id="resolver_stats"><info><title>Resolver Statistics Counters</title></info> + + <informaltable colsep="0" rowsep="0"> + <tgroup cols="3" colsep="0" rowsep="0" tgroupstyle="4Level-table"> + <colspec colname="1" colnum="1" colsep="0" colwidth="1.150in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="1.150in"/> + <colspec colname="3" colnum="3" colsep="0" colwidth="3.350in"/> + <tbody> + <row> + <entry colname="1"> + <para> + <emphasis>Symbol</emphasis> + </para> + </entry> + <entry colname="2"> + <para> + <emphasis>BIND8 Symbol</emphasis> + </para> + </entry> + <entry colname="3"> + <para> + <emphasis>Description</emphasis> + </para> + </entry> + </row> + + <row rowsep="0"> + <entry colname="1"> + <para><command>Queryv4</command></para> + </entry> + <entry colname="2"> + <para><command>SFwdQ</command></para> + </entry> + <entry colname="3"> + <para> + IPv4 queries sent. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>Queryv6</command></para> + </entry> + <entry colname="2"> + <para><command>SFwdQ</command></para> + </entry> + <entry colname="3"> + <para> + IPv6 queries sent. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>Responsev4</command></para> + </entry> + <entry colname="2"> + <para><command>RR</command></para> + </entry> + <entry colname="3"> + <para> + IPv4 responses received. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>Responsev6</command></para> + </entry> + <entry colname="2"> + <para><command>RR</command></para> + </entry> + <entry colname="3"> + <para> + IPv6 responses received. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>NXDOMAIN</command></para> + </entry> + <entry colname="2"> + <para><command>RNXD</command></para> + </entry> + <entry colname="3"> + <para> + NXDOMAIN received. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>SERVFAIL</command></para> + </entry> + <entry colname="2"> + <para><command>RFail</command></para> + </entry> + <entry colname="3"> + <para> + SERVFAIL received. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>FORMERR</command></para> + </entry> + <entry colname="2"> + <para><command>RFErr</command></para> + </entry> + <entry colname="3"> + <para> + FORMERR received. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>OtherError</command></para> + </entry> + <entry colname="2"> + <para><command>RErr</command></para> + </entry> + <entry colname="3"> + <para> + Other errors received. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>EDNS0Fail</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + EDNS(0) query failures. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>Mismatch</command></para> + </entry> + <entry colname="2"> + <para><command>RDupR</command></para> + </entry> + <entry colname="3"> + <para> + Mismatch responses received. + The DNS ID, response's source address, + and/or the response's source port does not + match what was expected. + (The port must be 53 or as defined by + the <command>port</command> option.) + This may be an indication of a cache + poisoning attempt. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>Truncated</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Truncated responses received. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>Lame</command></para> + </entry> + <entry colname="2"> + <para><command>RLame</command></para> + </entry> + <entry colname="3"> + <para> + Lame delegations received. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>Retry</command></para> + </entry> + <entry colname="2"> + <para><command>SDupQ</command></para> + </entry> + <entry colname="3"> + <para> + Query retries performed. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>QueryAbort</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Queries aborted due to quota control. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>QuerySockFail</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Failures in opening query sockets. + One common reason for such failures is a + failure of opening a new socket due to a + limitation on file descriptors. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>QueryTimeout</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Query timeouts. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>GlueFetchv4</command></para> + </entry> + <entry colname="2"> + <para><command>SSysQ</command></para> + </entry> + <entry colname="3"> + <para> + IPv4 NS address fetches invoked. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>GlueFetchv6</command></para> + </entry> + <entry colname="2"> + <para><command>SSysQ</command></para> + </entry> + <entry colname="3"> + <para> + IPv6 NS address fetches invoked. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>GlueFetchv4Fail</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + IPv4 NS address fetch failed. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>GlueFetchv6Fail</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + IPv6 NS address fetch failed. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>ValAttempt</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + DNSSEC validation attempted. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>ValOk</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + DNSSEC validation succeeded. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>ValNegOk</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + DNSSEC validation on negative information succeeded. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>ValFail</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + DNSSEC validation failed. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>QryRTTnn</command></para> + </entry> + <entry colname="2"> + <para><command/></para> + </entry> + <entry colname="3"> + <para> + Frequency table on round trip times (RTTs) of + queries. + Each <command>nn</command> specifies the corresponding + frequency. + In the sequence of + <command>nn_1</command>, + <command>nn_2</command>, + ..., + <command>nn_m</command>, + the value of <command>nn_i</command> is the + number of queries whose RTTs are between + <command>nn_(i-1)</command> (inclusive) and + <command>nn_i</command> (exclusive) milliseconds. + For the sake of convenience we define + <command>nn_0</command> to be 0. + The last entry should be represented as + <command>nn_m+</command>, which means the + number of queries whose RTTs are equal to or over + <command>nn_m</command> milliseconds. + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + + </section> + + <section xml:id="socket_stats"><info><title>Socket I/O Statistics Counters</title></info> + + <para> + Socket I/O statistics counters are defined per socket + types, which are + <command>UDP4</command> (UDP/IPv4), + <command>UDP6</command> (UDP/IPv6), + <command>TCP4</command> (TCP/IPv4), + <command>TCP6</command> (TCP/IPv6), + <command>Unix</command> (Unix Domain), and + <command>FDwatch</command> (sockets opened outside the + socket module). + In the following table <command><TYPE></command> + represents a socket type. + Not all counters are available for all socket types; + exceptions are noted in the description field. + </para> + + <informaltable colsep="0" rowsep="0"> + <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="4Level-table"> + <colspec colname="1" colnum="1" colsep="0" colwidth="1.150in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="3.350in"/> + <tbody> + <row> + <entry colname="1"> + <para> + <emphasis>Symbol</emphasis> + </para> + </entry> + <entry colname="2"> + <para> + <emphasis>Description</emphasis> + </para> + </entry> + </row> + + <row rowsep="0"> + <entry colname="1"> + <para><command><TYPE>Open</command></para> + </entry> + <entry colname="2"> + <para> + Sockets opened successfully. + This counter is not applicable to the + <command>FDwatch</command> type. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command><TYPE>OpenFail</command></para> + </entry> + <entry colname="2"> + <para> + Failures of opening sockets. + This counter is not applicable to the + <command>FDwatch</command> type. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command><TYPE>Close</command></para> + </entry> + <entry colname="2"> + <para> + Sockets closed. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command><TYPE>BindFail</command></para> + </entry> + <entry colname="2"> + <para> + Failures of binding sockets. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command><TYPE>ConnFail</command></para> + </entry> + <entry colname="2"> + <para> + Failures of connecting sockets. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command><TYPE>Conn</command></para> + </entry> + <entry colname="2"> + <para> + Connections established successfully. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command><TYPE>AcceptFail</command></para> + </entry> + <entry colname="2"> + <para> + Failures of accepting incoming connection requests. + This counter is not applicable to the + <command>UDP</command> and + <command>FDwatch</command> types. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command><TYPE>Accept</command></para> + </entry> + <entry colname="2"> + <para> + Incoming connections successfully accepted. + This counter is not applicable to the + <command>UDP</command> and + <command>FDwatch</command> types. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command><TYPE>SendErr</command></para> + </entry> + <entry colname="2"> + <para> + Errors in socket send operations. + This counter corresponds + to <command>SErr</command> counter of + <command>BIND</command> 8. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command><TYPE>RecvErr</command></para> + </entry> + <entry colname="2"> + <para> + Errors in socket receive operations. + This includes errors of send operations on a + connected UDP socket notified by an ICMP error + message. + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </section> + + <section xml:id="bind8_compatibility"><info><title>Compatibility with <emphasis>BIND</emphasis> 8 Counters</title></info> + + <para> + Most statistics counters that were available + in <command>BIND</command> 8 are also supported in + <command>BIND</command> 9 as shown in the above tables. + Here are notes about other counters that do not appear + in these tables. + </para> + + <variablelist> + <varlistentry> + <term><command>RFwdR,SFwdR</command></term> + <listitem> + <para> + These counters are not supported + because <command>BIND</command> 9 does not adopt + the notion of <emphasis>forwarding</emphasis> + as <command>BIND</command> 8 did. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>RAXFR</command></term> + <listitem> + <para> + This counter is accessible in the Incoming Queries section. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>RIQ</command></term> + <listitem> + <para> + This counter is accessible in the Incoming Requests section. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>ROpts</command></term> + <listitem> + <para> + This counter is not supported + because <command>BIND</command> 9 does not care + about IP options in the first place. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + </section> + </section> + + </chapter> + <chapter xml:id="Bv9ARM.ch07"><info><title><acronym>BIND</acronym> 9 Security Considerations</title></info> + + <section xml:id="Access_Control_Lists"><info><title>Access Control Lists</title></info> + + <para> + Access Control Lists (ACLs) are address match lists that + you can set up and nickname for future use in + <command>allow-notify</command>, <command>allow-query</command>, + <command>allow-query-on</command>, <command>allow-recursion</command>, + <command>blackhole</command>, <command>allow-transfer</command>, + <command>match-clients</command>, etc. + </para> + <para> + Using ACLs allows you to have finer control over who can access + your name server, without cluttering up your config files with huge + lists of IP addresses. + </para> + <para> + It is a <emphasis>good idea</emphasis> to use ACLs, and to + control access to your server. Limiting access to your server by + outside parties can help prevent spoofing and denial of service + (DoS) attacks against your server. + </para> + <para> + ACLs match clients on the basis of up to three characteristics: + 1) The client's IP address; 2) the TSIG or SIG(0) key that was + used to sign the request, if any; and 3) an address prefix + encoded in an EDNS Client Subnet option, if any. + </para> + <para> + Here is an example of ACLs based on client addresses: + </para> + +<programlisting> +// Set up an ACL named "bogusnets" that will block +// RFC1918 space and some reserved space, which is +// commonly used in spoofing attacks. +acl bogusnets { + 0.0.0.0/8; 192.0.2.0/24; 224.0.0.0/3; + 10.0.0.0/8; 172.16.0.0/12; 192.168.0.0/16; +}; + +// Set up an ACL called our-nets. Replace this with the +// real IP numbers. +acl our-nets { x.x.x.x/24; x.x.x.x/21; }; +options { + ... + ... + allow-query { our-nets; }; + allow-recursion { our-nets; }; + ... + blackhole { bogusnets; }; + ... +}; + +zone "example.com" { + type master; + file "m/example.com"; + allow-query { any; }; +}; +</programlisting> + + <para> + This allows authoritative queries for "example.com" from any + address, but recursive queries only from the networks specified + in "our-nets", and no queries at all from the networks + specified in "bogusnets". + </para> + <para> + In addition to network addresses and prefixes, which are + matched against the source address of the DNS request, ACLs + may include <option>key</option> elements, which specify the + name of a TSIG or SIG(0) key, or <option>ecs</option> + elements, which specify a network prefix but are only matched + if that prefix matches an EDNS client subnet option included + in the request. + </para> + <para> + The EDNS Client Subnet (ECS) option is used by a recursive + resolver to inform an authoritative name server of the network + address block from which the original query was received, enabling + authoritative servers to give different answers to the same + resolver for different resolver clients. An ACL containing + an element of the form + <command>ecs <replaceable>prefix</replaceable></command> + will match if a request arrives in containing an ECS option + encoding an address within that prefix. If the request has no + ECS option, then "ecs" elements are simply ignored. Addresses + in ACLs that are not prefixed with "ecs" are matched only + against the source address. + </para> + <note> + <simpara> + (Note: The authoritative ECS implementation in + <command>named</command> is based on an early version of the + specification, and is known to have incompatibilities with + other implementations. It is also inefficient, requiring + a separate view for each client subnet to be sent different + answers, and it is unable to correct for overlapping subnets in + the configuration. It can be used for testing purposes, but is + not recommended for production use.) + </simpara> + </note> + <para> + When <acronym>BIND</acronym> 9 is built with GeoIP support, + ACLs can also be used for geographic access restrictions. + This is done by specifying an ACL element of the form: + <command>geoip <optional>db <replaceable>database</replaceable></optional> <replaceable>field</replaceable> <replaceable>value</replaceable></command> + </para> + <para> + The <replaceable>field</replaceable> indicates which field + to search for a match. Available fields are "country", + "region", "city", "continent", "postal" (postal code), + "metro" (metro code), "area" (area code), "tz" (timezone), + "isp", "org", "asnum", "domain" and "netspeed". + </para> + <para> + <replaceable>value</replaceable> is the value to search + for within the database. A string may be quoted if it + contains spaces or other special characters. If this is + an "asnum" search, then the leading "ASNNNN" string can be + used, otherwise the full description must be used (e.g. + "ASNNNN Example Company Name"). If this is a "country" + search and the string is two characters long, then it must + be a standard ISO-3166-1 two-letter country code, and if it + is three characters long then it must be an ISO-3166-1 + three-letter country code; otherwise it is the full name + of the country. Similarly, if this is a "region" search + and the string is two characters long, then it must be a + standard two-letter state or province abbreviation; + otherwise it is the full name of the state or province. + </para> + <para> + The <replaceable>database</replaceable> field indicates which + GeoIP database to search for a match. In most cases this is + unnecessary, because most search fields can only be found in + a single database. However, searches for country can be + answered from the "city", "region", or "country" databases, + and searches for region (i.e., state or province) can be + answered from the "city" or "region" databases. For these + search types, specifying a <replaceable>database</replaceable> + will force the query to be answered from that database and no + other. If <replaceable>database</replaceable> is not + specified, then these queries will be answered from the "city", + database if it is installed, or the "region" database if it is + installed, or the "country" database, in that order. + </para> + <para> + By default, if a DNS query includes an EDNS Client Subnet (ECS) + option which encodes a non-zero address prefix, then GeoIP ACLs + will be matched against that address prefix. Otherwise, they + are matched against the source address of the query. To + prevent GeoIP ACLs from matching against ECS options, set + the <command>geoip-use-ecs</command> to <literal>no</literal>. + </para> + <para> + Some example GeoIP ACLs: + </para> + <programlisting>geoip country US; +geoip country JAP; +geoip db country country Canada; +geoip db region region WA; +geoip city "San Francisco"; +geoip region Oklahoma; +geoip postal 95062; +geoip tz "America/Los_Angeles"; +geoip org "Internet Systems Consortium"; +</programlisting> + + <para> + ACLs use a "first-match" logic rather than "best-match": + if an address prefix matches an ACL element, then that ACL + is considered to have matched even if a later element would + have matched more specifically. For example, the ACL + <command> { 10/8; !10.0.0.1; }</command> would actually + match a query from 10.0.0.1, because the first element + indicated that the query should be accepted, and the second + element is ignored. + </para> + <para> + When using "nested" ACLs (that is, ACLs included or referenced + within other ACLs), a negative match of a nested ACL will + the containing ACL to continue looking for matches. This + enables complex ACLs to be constructed, in which multiple + client characteristics can be checked at the same time. For + example, to construct an ACL which allows queries only when + it originates from a particular network <emphasis>and</emphasis> + only when it is signed with a particular key, use: + </para> + <programlisting> +allow-query { !{ !10/8; any; }; key example; }; +</programlisting> + <para> + Within the nested ACL, any address that is + <emphasis>not</emphasis> in the 10/8 network prefix will + be rejected, and this will terminate processing of the + ACL. Any address that <emphasis>is</emphasis> in the 10/8 + network prefix will be accepted, but this causes a negative + match of the nested ACL, so the containing ACL continues + processing. The query will then be accepted if it is signed + by the key "example", and rejected otherwise. The ACL, then, + will only matches when <emphasis>both</emphasis> conditions + are true. + </para> + </section> + + <section xml:id="chroot_and_setuid"><info><title><command>Chroot</command> and <command>Setuid</command></title></info> + + <para> + On UNIX servers, it is possible to run <acronym>BIND</acronym> + in a <emphasis>chrooted</emphasis> environment (using + the <command>chroot()</command> function) by specifying + the <option>-t</option> option for <command>named</command>. + This can help improve system security by placing + <acronym>BIND</acronym> in a "sandbox", which will limit + the damage done if a server is compromised. + </para> + <para> + Another useful feature in the UNIX version of <acronym>BIND</acronym> is the + ability to run the daemon as an unprivileged user ( <option>-u</option> <replaceable>user</replaceable> ). + We suggest running as an unprivileged user when using the <command>chroot</command> feature. + </para> + <para> + Here is an example command line to load <acronym>BIND</acronym> in a <command>chroot</command> sandbox, + <command>/var/named</command>, and to run <command>named</command> <command>setuid</command> to + user 202: + </para> + <para> + <userinput>/usr/local/sbin/named -u 202 -t /var/named</userinput> + </para> + + <section xml:id="chroot"><info><title>The <command>chroot</command> Environment</title></info> + + <para> + In order for a <command>chroot</command> environment + to work properly in a particular directory (for example, + <filename>/var/named</filename>), you will need to set + up an environment that includes everything + <acronym>BIND</acronym> needs to run. From + <acronym>BIND</acronym>'s point of view, + <filename>/var/named</filename> is the root of the + filesystem. You will need to adjust the values of + options like <command>directory</command> and + <command>pid-file</command> to account for this. + </para> + <para> + Unlike with earlier versions of BIND, you typically will + <emphasis>not</emphasis> need to compile <command>named</command> + statically nor install shared libraries under the new root. + However, depending on your operating system, you may need + to set up things like + <filename>/dev/zero</filename>, + <filename>/dev/random</filename>, + <filename>/dev/log</filename>, and + <filename>/etc/localtime</filename>. + </para> + </section> + + <section xml:id="setuid"><info><title>Using the <command>setuid</command> Function</title></info> + + <para> + Prior to running the <command>named</command> daemon, + use + the <command>touch</command> utility (to change file + access and + modification times) or the <command>chown</command> + utility (to + set the user id and/or group id) on files + to which you want <acronym>BIND</acronym> + to write. + </para> + <note><simpara> + If the <command>named</command> daemon is running as an + unprivileged user, it will not be able to bind to new restricted + ports if the server is reloaded. + </simpara></note> + </section> + </section> + + <section xml:id="dynamic_update_security"><info><title>Dynamic Update Security</title></info> + + <para> + Access to the dynamic + update facility should be strictly limited. In earlier versions of + <acronym>BIND</acronym>, the only way to do this was + based on the IP + address of the host requesting the update, by listing an IP address + or + network prefix in the <command>allow-update</command> + zone option. + This method is insecure since the source address of the update UDP + packet + is easily forged. Also note that if the IP addresses allowed by the + <command>allow-update</command> option include the + address of a slave + server which performs forwarding of dynamic updates, the master can + be + trivially attacked by sending the update to the slave, which will + forward it to the master with its own source IP address causing the + master to approve it without question. + </para> + + <para> + For these reasons, we strongly recommend that updates be + cryptographically authenticated by means of transaction signatures + (TSIG). That is, the <command>allow-update</command> + option should + list only TSIG key names, not IP addresses or network + prefixes. Alternatively, the new <command>update-policy</command> + option can be used. + </para> + + <para> + Some sites choose to keep all dynamically-updated DNS data + in a subdomain and delegate that subdomain to a separate zone. This + way, the top-level zone containing critical data such as the IP + addresses + of public web and mail servers need not allow dynamic update at + all. + </para> + + </section> + </chapter> + + <chapter xml:id="Bv9ARM.ch08"><info><title>Troubleshooting</title></info> + + <section xml:id="common_problems"><info><title>Common Problems</title></info> + + <section><info><title>It's not working; how can I figure out what's wrong?</title></info> + + <para> + The best solution to solving installation and + configuration issues is to take preventative measures by setting + up logging files beforehand. The log files provide a + source of hints and information that can be used to figure out + what went wrong and how to fix the problem. + </para> + + </section> + </section> + <section><info><title>Incrementing and Changing the Serial Number</title></info> + + <para> + Zone serial numbers are just numbers — they aren't + date related. A lot of people set them to a number that + represents a date, usually of the form YYYYMMDDRR. + Occasionally they will make a mistake and set them to a + "date in the future" then try to correct them by setting + them to the "current date". This causes problems because + serial numbers are used to indicate that a zone has been + updated. If the serial number on the slave server is + lower than the serial number on the master, the slave + server will attempt to update its copy of the zone. + </para> + + <para> + Setting the serial number to a lower number on the master + server than the slave server means that the slave will not perform + updates to its copy of the zone. + </para> + + <para> + The solution to this is to add 2147483647 (2^31-1) to the + number, reload the zone and make sure all slaves have updated to + the new zone serial number, then reset the number to what you want + it to be, and reload the zone again. + </para> + + </section> + <section xml:id="more_help"><info><title>Where Can I Get Help?</title></info> + + <para> + The Internet Systems Consortium + (<acronym>ISC</acronym>) offers a wide range + of support and service agreements for <acronym>BIND</acronym> and <acronym>DHCP</acronym> servers. Four + levels of premium support are available and each level includes + support for all <acronym>ISC</acronym> programs, + significant discounts on products + and training, and a recognized priority on bug fixes and + non-funded feature requests. In addition, <acronym>ISC</acronym> offers a standard + support agreement package which includes services ranging from bug + fix announcements to remote support. It also includes training in + <acronym>BIND</acronym> and <acronym>DHCP</acronym>. + </para> + + <para> + To discuss arrangements for support, contact + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="mailto:info@isc.org">info@isc.org</link> or visit the + <acronym>ISC</acronym> web page at + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.isc.org/services/support/">http://www.isc.org/services/support/</link> + to read more. + </para> + </section> + </chapter> + + <appendix xml:id="Bv9ARM.ch09"><info><title>Release Notes</title></info> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="notes.xml"/> + </appendix> + + <appendix xml:id="Bv9ARM.ch10"><info><title>A Brief History of the <acronym>DNS</acronym> and <acronym>BIND</acronym></title></info> + <para xml:id="historical_dns_information"> + Although the "official" beginning of the Domain Name + System occurred in 1984 with the publication of RFC 920, the + core of the new system was described in 1983 in RFCs 882 and + 883. From 1984 to 1987, the ARPAnet (the precursor to today's + Internet) became a testbed of experimentation for developing the + new naming/addressing scheme in a rapidly expanding, + operational network environment. New RFCs were written and + published in 1987 that modified the original documents to + incorporate improvements based on the working model. RFC 1034, + "Domain Names-Concepts and Facilities", and RFC 1035, "Domain + Names-Implementation and Specification" were published and + became the standards upon which all <acronym>DNS</acronym> implementations are + built. + </para> + + <para> + The first working domain name server, called "Jeeves", was + written in 1983-84 by Paul Mockapetris for operation on DEC + Tops-20 + machines located at the University of Southern California's + Information + Sciences Institute (USC-ISI) and SRI International's Network + Information + Center (SRI-NIC). A <acronym>DNS</acronym> server for + Unix machines, the Berkeley Internet + Name Domain (<acronym>BIND</acronym>) package, was + written soon after by a group of + graduate students at the University of California at Berkeley + under + a grant from the US Defense Advanced Research Projects + Administration + (DARPA). + </para> + <para> + Versions of <acronym>BIND</acronym> through + 4.8.3 were maintained by the Computer + Systems Research Group (CSRG) at UC Berkeley. Douglas Terry, Mark + Painter, David Riggle and Songnian Zhou made up the initial <acronym>BIND</acronym> + project team. After that, additional work on the software package + was done by Ralph Campbell. Kevin Dunlap, a Digital Equipment + Corporation + employee on loan to the CSRG, worked on <acronym>BIND</acronym> for 2 years, from 1985 + to 1987. Many other people also contributed to <acronym>BIND</acronym> development + during that time: Doug Kingston, Craig Partridge, Smoot + Carl-Mitchell, + Mike Muuss, Jim Bloom and Mike Schwartz. <acronym>BIND</acronym> maintenance was subsequently + handled by Mike Karels and Øivind Kure. + </para> + <para> + <acronym>BIND</acronym> versions 4.9 and 4.9.1 were + released by Digital Equipment + Corporation (now Compaq Computer Corporation). Paul Vixie, then + a DEC employee, became <acronym>BIND</acronym>'s + primary caretaker. He was assisted + by Phil Almquist, Robert Elz, Alan Barrett, Paul Albitz, Bryan + Beecher, Andrew + Partan, Andy Cherenson, Tom Limoncelli, Berthold Paffrath, Fuat + Baran, Anant Kumar, Art Harkin, Win Treese, Don Lewis, Christophe + Wolfhugel, and others. + </para> + <para> + In 1994, <acronym>BIND</acronym> version 4.9.2 was sponsored by + Vixie Enterprises. Paul + Vixie became <acronym>BIND</acronym>'s principal + architect/programmer. + </para> + <para> + <acronym>BIND</acronym> versions from 4.9.3 onward + have been developed and maintained + by the Internet Systems Consortium and its predecessor, + the Internet Software Consortium, with support being provided + by ISC's sponsors. + </para> + <para> + As co-architects/programmers, Bob Halley and + Paul Vixie released the first production-ready version of + <acronym>BIND</acronym> version 8 in May 1997. + </para> + <para> + BIND version 9 was released in September 2000 and is a + major rewrite of nearly all aspects of the underlying + BIND architecture. + </para> + <para> + BIND versions 4 and 8 are officially deprecated. + No additional development is done + on BIND version 4 or BIND version 8. + </para> + <para> + <acronym>BIND</acronym> development work is made + possible today by the sponsorship + of several corporations, and by the tireless work efforts of + numerous individuals. + </para> + </appendix> + + <appendix xml:id="Bv9ARM.ch11"><info><title>General <acronym>DNS</acronym> Reference Information</title></info> + + <section xml:id="ipv6addresses"><info><title>IPv6 addresses (AAAA)</title></info> + + <para> + IPv6 addresses are 128-bit identifiers for interfaces and + sets of interfaces which were introduced in the <acronym>DNS</acronym> to facilitate + scalable Internet routing. There are three types of addresses: <emphasis>Unicast</emphasis>, + an identifier for a single interface; + <emphasis>Anycast</emphasis>, + an identifier for a set of interfaces; and <emphasis>Multicast</emphasis>, + an identifier for a set of interfaces. Here we describe the global + Unicast address scheme. For more information, see RFC 3587, + "Global Unicast Address Format." + </para> + <para> + IPv6 unicast addresses consist of a + <emphasis>global routing prefix</emphasis>, a + <emphasis>subnet identifier</emphasis>, and an + <emphasis>interface identifier</emphasis>. + </para> + <para> + The global routing prefix is provided by the + upstream provider or ISP, and (roughly) corresponds to the + IPv4 <emphasis>network</emphasis> section + of the address range. + + The subnet identifier is for local subnetting, much the + same as subnetting an + IPv4 /16 network into /24 subnets. + + The interface identifier is the address of an individual + interface on a given network; in IPv6, addresses belong to + interfaces rather than to machines. + </para> + <para> + The subnetting capability of IPv6 is much more flexible than + that of IPv4: subnetting can be carried out on bit boundaries, + in much the same way as Classless InterDomain Routing + (CIDR), and the DNS PTR representation ("nibble" format) + makes setting up reverse zones easier. + </para> + <para> + The Interface Identifier must be unique on the local link, + and is usually generated automatically by the IPv6 + implementation, although it is usually possible to + override the default setting if necessary. A typical IPv6 + address might look like: + <command>2001:db8:201:9:a00:20ff:fe81:2b32</command> + </para> + <para> + IPv6 address specifications often contain long strings + of zeros, so the architects have included a shorthand for + specifying + them. The double colon (`::') indicates the longest possible + string + of zeros that can fit, and can be used only once in an address. + </para> + </section> + <section xml:id="bibliography"><info><title>Bibliography (and Suggested Reading)</title></info> + + <section xml:id="rfcs"><info><title>Request for Comments (RFCs)</title></info> + + <para> + Specification documents for the Internet protocol suite, including + the <acronym>DNS</acronym>, are published as part of + the Request for Comments (RFCs) + series of technical notes. The standards themselves are defined + by the Internet Engineering Task Force (IETF) and the Internet + Engineering Steering Group (IESG). RFCs can be obtained online via FTP at: + </para> + <para> + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="ftp://www.isi.edu/in-notes/"> + ftp://www.isi.edu/in-notes/RFC<replaceable>xxxx</replaceable>.txt + </link> + </para> + <para> + (where <replaceable>xxxx</replaceable> is + the number of the RFC). RFCs are also available via the Web at: + </para> + <para> + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.ietf.org/rfc/">http://www.ietf.org/rfc/</link>. + </para> + <bibliography> + <bibliodiv><info><title>Standards</title></info> + <!-- one of (BIBLIOENTRY BIBLIOMIXED) --> + + <biblioentry> + <abbrev>RFC974</abbrev> + <author><personname><surname>Partridge</surname><firstname>C.</firstname></personname></author> + <citetitle>Mail Routing and the Domain System</citetitle> + <pubdate>January 1986</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC1034</abbrev> + <author><personname><surname>Mockapetris</surname><firstname>P.V.</firstname></personname></author> + <citetitle>Domain Names — Concepts and Facilities</citetitle> + <pubdate>November 1987</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC1035</abbrev> + <author><personname><surname>Mockapetris</surname><firstname>P. V.</firstname></personname></author> <citetitle>Domain Names — Implementation and + Specification</citetitle> + <pubdate>November 1987</pubdate> + </biblioentry> + </bibliodiv> + <bibliodiv xml:id="proposed_standards" xreflabel="Proposed Standards"><info><title>Proposed Standards</title></info> + + <!-- one of (BIBLIOENTRY BIBLIOMIXED) --> + <biblioentry> + <abbrev>RFC2181</abbrev> + <author><personname><surname>Elz</surname><firstname>R., R. Bush</firstname></personname></author> + <citetitle>Clarifications to the <acronym>DNS</acronym> + Specification</citetitle> + <pubdate>July 1997</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2308</abbrev> + <author><personname><surname>Andrews</surname><firstname>M.</firstname></personname></author> + <citetitle>Negative Caching of <acronym>DNS</acronym> + Queries</citetitle> + <pubdate>March 1998</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC1995</abbrev> + <author><personname><surname>Ohta</surname><firstname>M.</firstname></personname></author> + <citetitle>Incremental Zone Transfer in <acronym>DNS</acronym></citetitle> + <pubdate>August 1996</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC1996</abbrev> + <author><personname><surname>Vixie</surname><firstname>P.</firstname></personname></author> + <citetitle>A Mechanism for Prompt Notification of Zone Changes</citetitle> + <pubdate>August 1996</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2136</abbrev> + <authorgroup> + <author><personname><surname>Vixie</surname><firstname>P.</firstname></personname></author> + <author><personname><firstname>S.</firstname><surname>Thomson</surname></personname></author> + <author><personname><firstname>Y.</firstname><surname>Rekhter</surname></personname></author> + <author><personname><firstname>J.</firstname><surname>Bound</surname></personname></author> + </authorgroup> + <citetitle>Dynamic Updates in the Domain Name System</citetitle> + <pubdate>April 1997</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2671</abbrev> + <authorgroup> + <author><personname><firstname>P.</firstname><surname>Vixie</surname></personname></author> + </authorgroup> + <citetitle>Extension Mechanisms for DNS (EDNS0)</citetitle> + <pubdate>August 1997</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2672</abbrev> + <authorgroup> + <author><personname><firstname>M.</firstname><surname>Crawford</surname></personname></author> + </authorgroup> + <citetitle>Non-Terminal DNS Name Redirection</citetitle> + <pubdate>August 1999</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2845</abbrev> + <authorgroup> + <author><personname><surname>Vixie</surname><firstname>P.</firstname></personname></author> + <author><personname><firstname>O.</firstname><surname>Gudmundsson</surname></personname></author> + <author><personname><firstname>D.</firstname><surname>Eastlake</surname><lineage>3rd</lineage></personname></author> + <author><personname><firstname>B.</firstname><surname>Wellington</surname></personname></author> + </authorgroup> + <citetitle>Secret Key Transaction Authentication for <acronym>DNS</acronym> (TSIG)</citetitle> + <pubdate>May 2000</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2930</abbrev> + <authorgroup> + <author><personname><firstname>D.</firstname><surname>Eastlake</surname><lineage>3rd</lineage></personname></author> + </authorgroup> + <citetitle>Secret Key Establishment for DNS (TKEY RR)</citetitle> + <pubdate>September 2000</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2931</abbrev> + <authorgroup> + <author><personname><firstname>D.</firstname><surname>Eastlake</surname><lineage>3rd</lineage></personname></author> + </authorgroup> + <citetitle>DNS Request and Transaction Signatures (SIG(0)s)</citetitle> + <pubdate>September 2000</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC3007</abbrev> + <authorgroup> + <author><personname><firstname>B.</firstname><surname>Wellington</surname></personname></author> + </authorgroup> + <citetitle>Secure Domain Name System (DNS) Dynamic Update</citetitle> + <pubdate>November 2000</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC3645</abbrev> + <authorgroup> + <author><personname><firstname>S.</firstname><surname>Kwan</surname></personname></author> + <author><personname><firstname>P.</firstname><surname>Garg</surname></personname></author> + <author><personname><firstname>J.</firstname><surname>Gilroy</surname></personname></author> + <author><personname><firstname>L.</firstname><surname>Esibov</surname></personname></author> + <author><personname><firstname>J.</firstname><surname>Westhead</surname></personname></author> + <author><personname><firstname>R.</firstname><surname>Hall</surname></personname></author> + </authorgroup> + <citetitle>Generic Security Service Algorithm for Secret + Key Transaction Authentication for DNS + (GSS-TSIG)</citetitle> + <pubdate>October 2003</pubdate> + </biblioentry> + </bibliodiv> + <bibliodiv><info><title><acronym>DNS</acronym> Security Proposed Standards</title></info> + + <biblioentry> + <abbrev>RFC3225</abbrev> + <authorgroup> + <author><personname><firstname>D.</firstname><surname>Conrad</surname></personname></author> + </authorgroup> + <citetitle>Indicating Resolver Support of DNSSEC</citetitle> + <pubdate>December 2001</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC3833</abbrev> + <authorgroup> + <author><personname><firstname>D.</firstname><surname>Atkins</surname></personname></author> + <author><personname><firstname>R.</firstname><surname>Austein</surname></personname></author> + </authorgroup> + <citetitle>Threat Analysis of the Domain Name System (DNS)</citetitle> + <pubdate>August 2004</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC4033</abbrev> + <authorgroup> + <author><personname><firstname>R.</firstname><surname>Arends</surname></personname></author> + <author><personname><firstname>R.</firstname><surname>Austein</surname></personname></author> + <author><personname><firstname>M.</firstname><surname>Larson</surname></personname></author> + <author><personname><firstname>D.</firstname><surname>Massey</surname></personname></author> + <author><personname><firstname>S.</firstname><surname>Rose</surname></personname></author> + </authorgroup> + <citetitle>DNS Security Introduction and Requirements</citetitle> + <pubdate>March 2005</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC4034</abbrev> + <authorgroup> + <author><personname><firstname>R.</firstname><surname>Arends</surname></personname></author> + <author><personname><firstname>R.</firstname><surname>Austein</surname></personname></author> + <author><personname><firstname>M.</firstname><surname>Larson</surname></personname></author> + <author><personname><firstname>D.</firstname><surname>Massey</surname></personname></author> + <author><personname><firstname>S.</firstname><surname>Rose</surname></personname></author> + </authorgroup> + <citetitle>Resource Records for the DNS Security Extensions</citetitle> + <pubdate>March 2005</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC4035</abbrev> + <authorgroup> + <author><personname><firstname>R.</firstname><surname>Arends</surname></personname></author> + <author><personname><firstname>R.</firstname><surname>Austein</surname></personname></author> + <author><personname><firstname>M.</firstname><surname>Larson</surname></personname></author> + <author><personname><firstname>D.</firstname><surname>Massey</surname></personname></author> + <author><personname><firstname>S.</firstname><surname>Rose</surname></personname></author> + </authorgroup> + <citetitle>Protocol Modifications for the DNS + Security Extensions</citetitle> + <pubdate>March 2005</pubdate> + </biblioentry> + </bibliodiv> + <bibliodiv><info><title>Other Important RFCs About <acronym>DNS</acronym> + Implementation</title></info> + + <biblioentry> + <abbrev>RFC1535</abbrev> + <author><personname><surname>Gavron</surname><firstname>E.</firstname></personname></author> + <citetitle>A Security Problem and Proposed Correction With Widely + Deployed <acronym>DNS</acronym> Software</citetitle> + <pubdate>October 1993</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC1536</abbrev> + <authorgroup> + <author><personname><surname>Kumar</surname><firstname>A.</firstname></personname></author> + <author><personname><firstname>J.</firstname><surname>Postel</surname></personname></author> + <author><personname><firstname>C.</firstname><surname>Neuman</surname></personname></author> + <author><personname><firstname>P.</firstname><surname>Danzig</surname></personname></author> + <author><personname><firstname>S.</firstname><surname>Miller</surname></personname></author> + </authorgroup> + <citetitle>Common <acronym>DNS</acronym> Implementation + Errors and Suggested Fixes</citetitle> + <pubdate>October 1993</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC1982</abbrev> + <authorgroup> + <author><personname><surname>Elz</surname><firstname>R.</firstname></personname></author> + <author><personname><firstname>R.</firstname><surname>Bush</surname></personname></author> + </authorgroup> + <citetitle>Serial Number Arithmetic</citetitle> + <pubdate>August 1996</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC4074</abbrev> + <authorgroup> + <author><personname><surname>Morishita</surname><firstname>Y.</firstname></personname></author> + <author><personname><firstname>T.</firstname><surname>Jinmei</surname></personname></author> + </authorgroup> + <citetitle>Common Misbehaviour Against <acronym>DNS</acronym> + Queries for IPv6 Addresses</citetitle> + <pubdate>May 2005</pubdate> + </biblioentry> + </bibliodiv> + <bibliodiv><info><title>Resource Record Types</title></info> + + <biblioentry> + <abbrev>RFC1183</abbrev> + <authorgroup> + <author><personname><surname>Everhart</surname><firstname>C.F.</firstname></personname></author> + <author><personname><firstname>L. A.</firstname><surname>Mamakos</surname></personname></author> + <author><personname><firstname>R.</firstname><surname>Ullmann</surname></personname></author> + <author><personname><firstname>P.</firstname><surname>Mockapetris</surname></personname></author> + </authorgroup> + <citetitle>New <acronym>DNS</acronym> RR Definitions</citetitle> + <pubdate>October 1990</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC1706</abbrev> + <authorgroup> + <author><personname><surname>Manning</surname><firstname>B.</firstname></personname></author> + <author><personname><firstname>R.</firstname><surname>Colella</surname></personname></author> + </authorgroup> + <citetitle><acronym>DNS</acronym> NSAP Resource Records</citetitle> + <pubdate>October 1994</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2168</abbrev> + <authorgroup> + <author><personname><surname>Daniel</surname><firstname>R.</firstname></personname></author> + <author><personname><firstname>M.</firstname><surname>Mealling</surname></personname></author> + </authorgroup> + <citetitle>Resolution of Uniform Resource Identifiers using + the Domain Name System</citetitle> + <pubdate>June 1997</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC1876</abbrev> + <authorgroup> + <author><personname><surname>Davis</surname><firstname>C.</firstname></personname></author> + <author><personname><firstname>P.</firstname><surname>Vixie</surname></personname></author> + <author><personname><firstname>T.</firstname><firstname>Goodwin</firstname></personname></author> + <author><personname><firstname>I.</firstname><surname>Dickinson</surname></personname></author> + </authorgroup> + <citetitle>A Means for Expressing Location Information in the + Domain + Name System</citetitle> + <pubdate>January 1996</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2052</abbrev> + <authorgroup> + <author><personname><surname>Gulbrandsen</surname><firstname>A.</firstname></personname></author> + <author><personname><firstname>P.</firstname><surname>Vixie</surname></personname></author> + </authorgroup> + <citetitle>A <acronym>DNS</acronym> RR for Specifying the + Location of + Services</citetitle> + <pubdate>October 1996</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2163</abbrev> + <author><personname><surname>Allocchio</surname><firstname>A.</firstname></personname></author> + <citetitle>Using the Internet <acronym>DNS</acronym> to + Distribute MIXER + Conformant Global Address Mapping</citetitle> + <pubdate>January 1998</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2230</abbrev> + <author><personname><surname>Atkinson</surname><firstname>R.</firstname></personname></author> + <citetitle>Key Exchange Delegation Record for the <acronym>DNS</acronym></citetitle> + <pubdate>October 1997</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2536</abbrev> + <author><personname><surname>Eastlake</surname><firstname>D.</firstname><lineage>3rd</lineage></personname></author> + <citetitle>DSA KEYs and SIGs in the Domain Name System (DNS)</citetitle> + <pubdate>March 1999</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2537</abbrev> + <author><personname><surname>Eastlake</surname><firstname>D.</firstname><lineage>3rd</lineage></personname></author> + <citetitle>RSA/MD5 KEYs and SIGs in the Domain Name System (DNS)</citetitle> + <pubdate>March 1999</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2538</abbrev> + <authorgroup> + <author><personname><surname>Eastlake</surname><firstname>D.</firstname><lineage>3rd</lineage></personname></author> + <author><personname><surname>Gudmundsson</surname><firstname>O.</firstname></personname></author> + </authorgroup> + <citetitle>Storing Certificates in the Domain Name System (DNS)</citetitle> + <pubdate>March 1999</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2539</abbrev> + <authorgroup> + <author><personname><surname>Eastlake</surname><firstname>D.</firstname><lineage>3rd</lineage></personname></author> + </authorgroup> + <citetitle>Storage of Diffie-Hellman Keys in the Domain Name System (DNS)</citetitle> + <pubdate>March 1999</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2540</abbrev> + <authorgroup> + <author><personname><surname>Eastlake</surname><firstname>D.</firstname><lineage>3rd</lineage></personname></author> + </authorgroup> + <citetitle>Detached Domain Name System (DNS) Information</citetitle> + <pubdate>March 1999</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2782</abbrev> + <author><personname><surname>Gulbrandsen</surname><firstname>A.</firstname></personname></author> + <author><personname><surname>Vixie</surname><firstname>P.</firstname></personname></author> + <author><personname><surname>Esibov</surname><firstname>L.</firstname></personname></author> + <citetitle>A DNS RR for specifying the location of services (DNS SRV)</citetitle> + <pubdate>February 2000</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2915</abbrev> + <author><personname><surname>Mealling</surname><firstname>M.</firstname></personname></author> + <author><personname><surname>Daniel</surname><firstname>R.</firstname></personname></author> + <citetitle>The Naming Authority Pointer (NAPTR) DNS Resource Record</citetitle> + <pubdate>September 2000</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC3110</abbrev> + <author><personname><surname>Eastlake</surname><firstname>D.</firstname><lineage>3rd</lineage></personname></author> + <citetitle>RSA/SHA-1 SIGs and RSA KEYs in the Domain Name System (DNS)</citetitle> + <pubdate>May 2001</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC3123</abbrev> + <author><personname><surname>Koch</surname><firstname>P.</firstname></personname></author> + <citetitle>A DNS RR Type for Lists of Address Prefixes (APL RR)</citetitle> + <pubdate>June 2001</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC3596</abbrev> + <authorgroup> + <author><personname><surname>Thomson</surname><firstname>S.</firstname></personname></author> + <author><personname><firstname>C.</firstname><surname>Huitema</surname></personname></author> + <author><personname><firstname>V.</firstname><surname>Ksinant</surname></personname></author> + <author><personname><firstname>M.</firstname><surname>Souissi</surname></personname></author> + </authorgroup> + <citetitle><acronym>DNS</acronym> Extensions to support IP + version 6</citetitle> + <pubdate>October 2003</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC3597</abbrev> + <author><personname><surname>Gustafsson</surname><firstname>A.</firstname></personname></author> + <citetitle>Handling of Unknown DNS Resource Record (RR) Types</citetitle> + <pubdate>September 2003</pubdate> + </biblioentry> + </bibliodiv> + <bibliodiv><info><title><acronym>DNS</acronym> and the Internet</title></info> + + <biblioentry> + <abbrev>RFC1101</abbrev> + <author><personname><surname>Mockapetris</surname><firstname>P. V.</firstname></personname></author> + <citetitle><acronym>DNS</acronym> Encoding of Network Names + and Other Types</citetitle> + <pubdate>April 1989</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC1123</abbrev> + <author><personname><surname>Braden</surname><surname>R.</surname></personname></author> + <citetitle>Requirements for Internet Hosts - Application and + Support</citetitle> + <pubdate>October 1989</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC1591</abbrev> + <author><personname><surname>Postel</surname><firstname>J.</firstname></personname></author> + <citetitle>Domain Name System Structure and Delegation</citetitle> + <pubdate>March 1994</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2317</abbrev> + <authorgroup> + <author><personname><surname>Eidnes</surname><firstname>H.</firstname></personname></author> + <author><personname><firstname>G.</firstname><surname>de Groot</surname></personname></author> + <author><personname><firstname>P.</firstname><surname>Vixie</surname></personname></author> + </authorgroup> + <citetitle>Classless IN-ADDR.ARPA Delegation</citetitle> + <pubdate>March 1998</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2826</abbrev> + <authorgroup> + <author><personname><surname>Internet Architecture Board</surname></personname></author> + </authorgroup> + <citetitle>IAB Technical Comment on the Unique DNS Root</citetitle> + <pubdate>May 2000</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2929</abbrev> + <authorgroup> + <author><personname><surname>Eastlake</surname><firstname>D.</firstname><lineage>3rd</lineage></personname></author> + <author><personname><surname>Brunner-Williams</surname><firstname>E.</firstname></personname></author> + <author><personname><surname>Manning</surname><firstname>B.</firstname></personname></author> + </authorgroup> + <citetitle>Domain Name System (DNS) IANA Considerations</citetitle> + <pubdate>September 2000</pubdate> + </biblioentry> + </bibliodiv> + <bibliodiv><info><title><acronym>DNS</acronym> Operations</title></info> + + <biblioentry> + <abbrev>RFC1033</abbrev> + <author><personname><surname>Lottor</surname><firstname>M.</firstname></personname></author> + <citetitle>Domain administrators operations guide</citetitle> + <pubdate>November 1987</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC1537</abbrev> + <author><personname><surname>Beertema</surname><firstname>P.</firstname></personname></author> + <citetitle>Common <acronym>DNS</acronym> Data File + Configuration Errors</citetitle> + <pubdate>October 1993</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC1912</abbrev> + <author><personname><surname>Barr</surname><firstname>D.</firstname></personname></author> + <citetitle>Common <acronym>DNS</acronym> Operational and + Configuration Errors</citetitle> + <pubdate>February 1996</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2010</abbrev> + <authorgroup> + <author><personname><surname>Manning</surname><firstname>B.</firstname></personname></author> + <author><personname><firstname>P.</firstname><surname>Vixie</surname></personname></author> + </authorgroup> + <citetitle>Operational Criteria for Root Name Servers</citetitle> + <pubdate>October 1996</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2219</abbrev> + <authorgroup> + <author><personname><surname>Hamilton</surname><firstname>M.</firstname></personname></author> + <author><personname><firstname>R.</firstname><surname>Wright</surname></personname></author> + </authorgroup> + <citetitle>Use of <acronym>DNS</acronym> Aliases for + Network Services</citetitle> + <pubdate>October 1997</pubdate> + </biblioentry> + </bibliodiv> + <bibliodiv><info><title>Internationalized Domain Names</title></info> + + <biblioentry> + <abbrev>RFC2825</abbrev> + <authorgroup> + <author><personname><surname>IAB</surname></personname></author> + <author><personname><surname>Daigle</surname><firstname>R.</firstname></personname></author> + </authorgroup> + <citetitle>A Tangled Web: Issues of I18N, Domain Names, + and the Other Internet protocols</citetitle> + <pubdate>May 2000</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC3490</abbrev> + <authorgroup> + <author><personname><surname>Faltstrom</surname><firstname>P.</firstname></personname></author> + <author><personname><surname>Hoffman</surname><firstname>P.</firstname></personname></author> + <author><personname><surname>Costello</surname><firstname>A.</firstname></personname></author> + </authorgroup> + <citetitle>Internationalizing Domain Names in Applications (IDNA)</citetitle> + <pubdate>March 2003</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC3491</abbrev> + <authorgroup> + <author><personname><surname>Hoffman</surname><firstname>P.</firstname></personname></author> + <author><personname><surname>Blanchet</surname><firstname>M.</firstname></personname></author> + </authorgroup> + <citetitle>Nameprep: A Stringprep Profile for Internationalized Domain Names</citetitle> + <pubdate>March 2003</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC3492</abbrev> + <authorgroup> + <author><personname><surname>Costello</surname><firstname>A.</firstname></personname></author> + </authorgroup> + <citetitle>Punycode: A Bootstring encoding of Unicode + for Internationalized Domain Names in + Applications (IDNA)</citetitle> + <pubdate>March 2003</pubdate> + </biblioentry> + </bibliodiv> + <bibliodiv><info><title>Other <acronym>DNS</acronym>-related RFCs</title></info> + + <note> + <para> + Note: the following list of RFCs, although + <acronym>DNS</acronym>-related, are not + concerned with implementing software. + </para> + </note> + <biblioentry> + <abbrev>RFC1464</abbrev> + <author><personname><surname>Rosenbaum</surname><firstname>R.</firstname></personname></author> + <citetitle>Using the Domain Name System To Store Arbitrary String + Attributes</citetitle> + <pubdate>May 1993</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC1713</abbrev> + <author><personname><surname>Romao</surname><firstname>A.</firstname></personname></author> + <citetitle>Tools for <acronym>DNS</acronym> Debugging</citetitle> + <pubdate>November 1994</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC1794</abbrev> + <author><personname><surname>Brisco</surname><firstname>T.</firstname></personname></author> + <citetitle><acronym>DNS</acronym> Support for Load + Balancing</citetitle> + <pubdate>April 1995</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2240</abbrev> + <author><personname><surname>Vaughan</surname><firstname>O.</firstname></personname></author> + <citetitle>A Legal Basis for Domain Name Allocation</citetitle> + <pubdate>November 1997</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2345</abbrev> + <authorgroup> + <author><personname><surname>Klensin</surname><firstname>J.</firstname></personname></author> + <author><personname><firstname>T.</firstname><surname>Wolf</surname></personname></author> + <author><personname><firstname>G.</firstname><surname>Oglesby</surname></personname></author> + </authorgroup> + <citetitle>Domain Names and Company Name Retrieval</citetitle> + <pubdate>May 1998</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2352</abbrev> + <author><personname><surname>Vaughan</surname><firstname>O.</firstname></personname></author> + <citetitle>A Convention For Using Legal Names as Domain Names</citetitle> + <pubdate>May 1998</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC3071</abbrev> + <authorgroup> + <author><personname><surname>Klensin</surname><firstname>J.</firstname></personname></author> + </authorgroup> + <citetitle>Reflections on the DNS, RFC 1591, and Categories of Domains</citetitle> + <pubdate>February 2001</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC3258</abbrev> + <authorgroup> + <author><personname><surname>Hardie</surname><firstname>T.</firstname></personname></author> + </authorgroup> + <citetitle>Distributing Authoritative Name Servers via + Shared Unicast Addresses</citetitle> + <pubdate>April 2002</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC3901</abbrev> + <authorgroup> + <author><personname><surname>Durand</surname><firstname>A.</firstname></personname></author> + <author><personname><firstname>J.</firstname><surname>Ihren</surname></personname></author> + </authorgroup> + <citetitle>DNS IPv6 Transport Operational Guidelines</citetitle> + <pubdate>September 2004</pubdate> + </biblioentry> + </bibliodiv> + <bibliodiv><info><title>Obsolete and Unimplemented Experimental RFC</title></info> + + <biblioentry> + <abbrev>RFC1712</abbrev> + <authorgroup> + <author><personname><surname>Farrell</surname><firstname>C.</firstname></personname></author> + <author><personname><firstname>M.</firstname><surname>Schulze</surname></personname></author> + <author><personname><firstname>S.</firstname><surname>Pleitner</surname></personname></author> + <author><personname><firstname>D.</firstname><surname>Baldoni</surname></personname></author> + </authorgroup> + <citetitle><acronym>DNS</acronym> Encoding of Geographical + Location</citetitle> + <pubdate>November 1994</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2673</abbrev> + <authorgroup> + <author><personname><surname>Crawford</surname><firstname>M.</firstname></personname></author> + </authorgroup> + <citetitle>Binary Labels in the Domain Name System</citetitle> + <pubdate>August 1999</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2874</abbrev> + <authorgroup> + <author><personname><surname>Crawford</surname><firstname>M.</firstname></personname></author> + <author><personname><surname>Huitema</surname><firstname>C.</firstname></personname></author> + </authorgroup> + <citetitle>DNS Extensions to Support IPv6 Address Aggregation + and Renumbering</citetitle> + <pubdate>July 2000</pubdate> + </biblioentry> + </bibliodiv> + <bibliodiv><info><title>Obsoleted DNS Security RFCs</title></info> + + <note> + <para> + Most of these have been consolidated into RFC4033, + RFC4034 and RFC4035 which collectively describe DNSSECbis. + </para> + </note> + <biblioentry> + <abbrev>RFC2065</abbrev> + <authorgroup> + <author><personname><surname>Eastlake</surname><lineage>3rd</lineage><firstname>D.</firstname></personname></author> + <author><personname><firstname>C.</firstname><surname>Kaufman</surname></personname></author> + </authorgroup> + <citetitle>Domain Name System Security Extensions</citetitle> + <pubdate>January 1997</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2137</abbrev> + <author><personname><surname>Eastlake</surname><lineage>3rd</lineage><firstname>D.</firstname></personname></author> + <citetitle>Secure Domain Name System Dynamic Update</citetitle> + <pubdate>April 1997</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC2535</abbrev> + <authorgroup> + <author><personname><surname>Eastlake</surname><lineage>3rd</lineage><firstname>D.</firstname></personname></author> + </authorgroup> + <citetitle>Domain Name System Security Extensions</citetitle> + <pubdate>March 1999</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC3008</abbrev> + <authorgroup> + <author><personname><surname>Wellington</surname><firstname>B.</firstname></personname></author> + </authorgroup> + <citetitle>Domain Name System Security (DNSSEC) + Signing Authority</citetitle> + <pubdate>November 2000</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC3090</abbrev> + <authorgroup> + <author><personname><surname>Lewis</surname><firstname>E.</firstname></personname></author> + </authorgroup> + <citetitle>DNS Security Extension Clarification on Zone Status</citetitle> + <pubdate>March 2001</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC3445</abbrev> + <authorgroup> + <author><personname><surname>Massey</surname><firstname>D.</firstname></personname></author> + <author><personname><surname>Rose</surname><firstname>S.</firstname></personname></author> + </authorgroup> + <citetitle>Limiting the Scope of the KEY Resource Record (RR)</citetitle> + <pubdate>December 2002</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC3655</abbrev> + <authorgroup> + <author><personname><surname>Wellington</surname><firstname>B.</firstname></personname></author> + <author><personname><surname>Gudmundsson</surname><firstname>O.</firstname></personname></author> + </authorgroup> + <citetitle>Redefinition of DNS Authenticated Data (AD) bit</citetitle> + <pubdate>November 2003</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC3658</abbrev> + <authorgroup> + <author><personname><surname>Gudmundsson</surname><firstname>O.</firstname></personname></author> + </authorgroup> + <citetitle>Delegation Signer (DS) Resource Record (RR)</citetitle> + <pubdate>December 2003</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC3755</abbrev> + <authorgroup> + <author><personname><surname>Weiler</surname><firstname>S.</firstname></personname></author> + </authorgroup> + <citetitle>Legacy Resolver Compatibility for Delegation Signer (DS)</citetitle> + <pubdate>May 2004</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC3757</abbrev> + <authorgroup> + <author><personname><surname>Kolkman</surname><firstname>O.</firstname></personname></author> + <author><personname><surname>Schlyter</surname><firstname>J.</firstname></personname></author> + <author><personname><surname>Lewis</surname><firstname>E.</firstname></personname></author> + </authorgroup> + <citetitle>Domain Name System KEY (DNSKEY) Resource Record + (RR) Secure Entry Point (SEP) Flag</citetitle> + <pubdate>April 2004</pubdate> + </biblioentry> + <biblioentry> + <abbrev>RFC3845</abbrev> + <authorgroup> + <author><personname><surname>Schlyter</surname><firstname>J.</firstname></personname></author> + </authorgroup> + <citetitle>DNS Security (DNSSEC) NextSECure (NSEC) RDATA Format</citetitle> + <pubdate>August 2004</pubdate> + </biblioentry> + </bibliodiv> + </bibliography> + </section> + <section xml:id="internet_drafts"><info><title>Internet Drafts</title></info> + + <para> + Internet Drafts (IDs) are rough-draft working documents of + the Internet Engineering Task Force. They are, in essence, RFCs + in the preliminary stages of development. Implementors are + cautioned not + to regard IDs as archival, and they should not be quoted or cited + in any formal documents unless accompanied by the disclaimer that + they are "works in progress." IDs have a lifespan of six months + after which they are deleted unless updated by their authors. + </para> + </section> + <section xml:id="more_about_bind"><info><title>Other Documents About <acronym>BIND</acronym></title></info> + + <para/> + <bibliography> + <biblioentry> + <authorgroup> + <author><personname><surname>Albitz</surname><firstname>Paul</firstname></personname></author> + <author><personname><firstname>Cricket</firstname><surname>Liu</surname></personname></author> + </authorgroup> + <citetitle><acronym>DNS</acronym> and <acronym>BIND</acronym></citetitle> + <copyright> + <year>1998</year> + <holder>Sebastopol, CA: O'Reilly and Associates</holder> + </copyright> + </biblioentry> + </bibliography> + </section> + </section> + </appendix> + + <appendix xml:id="Bv9ARM.ch12"><info><title>BIND 9 DNS Library Support</title></info> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="libdns.xml"/> + </appendix> + + <reference xml:id="Bv9ARM.ch13"><info><title>Manual pages</title></info> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/dig/dig.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/tools/mdig.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/dig/host.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/delv/delv.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/dig/nslookup.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/python/dnssec-checkds.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/python/dnssec-coverage.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/dnssec/dnssec-dsfromkey.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/dnssec/dnssec-importkey.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/dnssec/dnssec-keyfromlabel.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/dnssec/dnssec-keygen.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/python/dnssec-keymgr.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/dnssec/dnssec-revoke.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/dnssec/dnssec-settime.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/dnssec/dnssec-signzone.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/dnssec/dnssec-verify.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/named/lwresd.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/named/named.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/named/named.conf.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/check/named-checkconf.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/check/named-checkzone.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/tools/named-journalprint.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/tools/named-nzd2nzf.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/tools/named-rrchecker.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/nsupdate/nsupdate.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/rndc/rndc.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/rndc/rndc.conf.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/confgen/rndc-confgen.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/confgen/ddns-confgen.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/tools/arpaname.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/tools/dnstap-read.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/tools/genrandom.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/tools/isc-hmac-fixup.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/tools/nsec3hash.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/pkcs11/pkcs11-destroy.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/pkcs11/pkcs11-list.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/pkcs11/pkcs11-keygen.docbook"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../bin/pkcs11/pkcs11-tokens.docbook"/> + </reference> + + </book> diff --git a/doc/arm/Bv9ARM.ch01.html b/doc/arm/Bv9ARM.ch01.html new file mode 100644 index 0000000..dcf2407 --- /dev/null +++ b/doc/arm/Bv9ARM.ch01.html @@ -0,0 +1,621 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Chapter 1. Introduction</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="prev" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="next" href="Bv9ARM.ch02.html" title="Chapter 2. BIND Resource Requirements"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center">Chapter 1. Introduction</th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="Bv9ARM.html">Prev</a> </td> +<th width="60%" align="center"> </th> +<td width="20%" align="right"> <a accesskey="n" href="Bv9ARM.ch02.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="chapter"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="Bv9ARM.ch01"></a>Chapter 1. Introduction</h1></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="Bv9ARM.ch01.html#doc_scope">Scope of Document</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch01.html#organization">Organization of This Document</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch01.html#conventions">Conventions Used in This Document</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch01.html#dns_overview">The Domain Name System (<acronym class="acronym">DNS</acronym>)</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch01.html#dns_fundamentals">DNS Fundamentals</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch01.html#domain_names">Domains and Domain Names</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch01.html#zones">Zones</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch01.html#auth_servers">Authoritative Name Servers</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch01.html#cache_servers">Caching Name Servers</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch01.html#multi_role">Name Servers in Multiple Roles</a></span></dt> +</dl></dd> +</dl> +</div> + + <p> + The Internet Domain Name System (<acronym class="acronym">DNS</acronym>) + consists of the syntax + to specify the names of entities in the Internet in a hierarchical + manner, the rules used for delegating authority over names, and the + system implementation that actually maps names to Internet + addresses. <acronym class="acronym">DNS</acronym> data is maintained in a + group of distributed + hierarchical databases. + </p> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="doc_scope"></a>Scope of Document</h2></div></div></div> + + <p> + The Berkeley Internet Name Domain + (<acronym class="acronym">BIND</acronym>) implements a + domain name server for a number of operating systems. This + document provides basic information about the installation and + care of the Internet Systems Consortium (<acronym class="acronym">ISC</acronym>) + <acronym class="acronym">BIND</acronym> version 9 software package for + system administrators. + </p> + <p>This version of the manual corresponds to BIND version 9.11.</p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="organization"></a>Organization of This Document</h2></div></div></div> + + <p> + In this document, <span class="emphasis"><em>Chapter 1</em></span> introduces + the basic <acronym class="acronym">DNS</acronym> and <acronym class="acronym">BIND</acronym> concepts. <span class="emphasis"><em>Chapter 2</em></span> + describes resource requirements for running <acronym class="acronym">BIND</acronym> in various + environments. Information in <span class="emphasis"><em>Chapter 3</em></span> is + <span class="emphasis"><em>task-oriented</em></span> in its presentation and is + organized functionally, to aid in the process of installing the + <acronym class="acronym">BIND</acronym> 9 software. The task-oriented + section is followed by + <span class="emphasis"><em>Chapter 4</em></span>, which contains more advanced + concepts that the system administrator may need for implementing + certain options. <span class="emphasis"><em>Chapter 5</em></span> + describes the <acronym class="acronym">BIND</acronym> 9 lightweight + resolver. The contents of <span class="emphasis"><em>Chapter 6</em></span> are + organized as in a reference manual to aid in the ongoing + maintenance of the software. <span class="emphasis"><em>Chapter 7</em></span> addresses + security considerations, and + <span class="emphasis"><em>Chapter 8</em></span> contains troubleshooting help. The + main body of the document is followed by several + <span class="emphasis"><em>appendices</em></span> which contain useful reference + information, such as a <span class="emphasis"><em>bibliography</em></span> and + historic information related to <acronym class="acronym">BIND</acronym> + and the Domain Name + System. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="conventions"></a>Conventions Used in This Document</h2></div></div></div> + + <p> + In this document, we use the following general typographic + conventions: + </p> + + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="3.000in" class="1"> +<col width="2.625in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p> + <span class="emphasis"><em>To describe:</em></span> + </p> + </td> +<td> + <p> + <span class="emphasis"><em>We use the style:</em></span> + </p> + </td> +</tr> +<tr> +<td> + <p> + a pathname, filename, URL, hostname, + mailing list name, or new term or concept + </p> + </td> +<td> + <p> + <code class="filename">Fixed width</code> + </p> + </td> +</tr> +<tr> +<td> + <p> + literal user + input + </p> + </td> +<td> + <p> + <strong class="userinput"><code>Fixed Width Bold</code></strong> + </p> + </td> +</tr> +<tr> +<td> + <p> + program output + </p> + </td> +<td> + <p> + <code class="computeroutput">Fixed Width</code> + </p> + </td> +</tr> +</tbody> +</table> + </div> + + <p> + The following conventions are used in descriptions of the + <acronym class="acronym">BIND</acronym> configuration file:</p> +<div class="informaltable"> + <table border="1"> +<colgroup> +<col width="3.000in" class="1"> +<col width="2.625in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p> + <span class="emphasis"><em>To describe:</em></span> + </p> + </td> +<td> + <p> + <span class="emphasis"><em>We use the style:</em></span> + </p> + </td> +</tr> +<tr> +<td> + <p> + keywords + </p> + </td> +<td> + <p> + <code class="literal">Fixed Width</code> + </p> + </td> +</tr> +<tr> +<td> + <p> + variables + </p> + </td> +<td> + <p> + <code class="varname">Fixed Width</code> + </p> + </td> +</tr> +<tr> +<td> + <p> + Optional input + </p> + </td> +<td> + <p> + [<span class="optional">Text is enclosed in square brackets</span>] + </p> + </td> +</tr> +</tbody> +</table> + </div> +<p> + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="dns_overview"></a>The Domain Name System (<acronym class="acronym">DNS</acronym>)</h2></div></div></div> + + <p> + The purpose of this document is to explain the installation + and upkeep of the <acronym class="acronym">BIND</acronym> (Berkeley Internet + Name Domain) software package, and we + begin by reviewing the fundamentals of the Domain Name System + (<acronym class="acronym">DNS</acronym>) as they relate to <acronym class="acronym">BIND</acronym>. + </p> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="dns_fundamentals"></a>DNS Fundamentals</h3></div></div></div> + + <p> + The Domain Name System (DNS) is a hierarchical, distributed + database. It stores information for mapping Internet host names to + IP + addresses and vice versa, mail routing information, and other data + used by Internet applications. + </p> + + <p> + Clients look up information in the DNS by calling a + <span class="emphasis"><em>resolver</em></span> library, which sends queries to one or + more <span class="emphasis"><em>name servers</em></span> and interprets the responses. + The <acronym class="acronym">BIND</acronym> 9 software distribution + contains a name server, <span class="command"><strong>named</strong></span>, and a + resolver library, <span class="command"><strong>liblwres</strong></span>. + </p> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="domain_names"></a>Domains and Domain Names</h3></div></div></div> + + <p> + The data stored in the DNS is identified by <span class="emphasis"><em>domain names</em></span> that are organized as a tree according to + organizational or administrative boundaries. Each node of the tree, + called a <span class="emphasis"><em>domain</em></span>, is given a label. The domain + name of the + node is the concatenation of all the labels on the path from the + node to the <span class="emphasis"><em>root</em></span> node. This is represented + in written form as a string of labels listed from right to left and + separated by dots. A label need only be unique within its parent + domain. + </p> + + <p> + For example, a domain name for a host at the + company <span class="emphasis"><em>Example, Inc.</em></span> could be + <code class="literal">ourhost.example.com</code>, + where <code class="literal">com</code> is the + top level domain to which + <code class="literal">ourhost.example.com</code> belongs, + <code class="literal">example</code> is + a subdomain of <code class="literal">com</code>, and + <code class="literal">ourhost</code> is the + name of the host. + </p> + + <p> + For administrative purposes, the name space is partitioned into + areas called <span class="emphasis"><em>zones</em></span>, each starting at a node and + extending down to the leaf nodes or to nodes where other zones + start. + The data for each zone is stored in a <span class="emphasis"><em>name server</em></span>, which answers queries about the zone using the + <span class="emphasis"><em>DNS protocol</em></span>. + </p> + + <p> + The data associated with each domain name is stored in the + form of <span class="emphasis"><em>resource records</em></span> (<acronym class="acronym">RR</acronym>s). + Some of the supported resource record types are described in + <a class="xref" href="Bv9ARM.ch06.html#types_of_resource_records_and_when_to_use_them" title="Types of Resource Records and When to Use Them">the section called “Types of Resource Records and When to Use Them”</a>. + </p> + + <p> + For more detailed information about the design of the DNS and + the DNS protocol, please refer to the standards documents listed in + <a class="xref" href="Bv9ARM.ch11.html#rfcs" title="Request for Comments (RFCs)">the section called “Request for Comments (RFCs)”</a>. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="zones"></a>Zones</h3></div></div></div> + + <p> + To properly operate a name server, it is important to understand + the difference between a <span class="emphasis"><em>zone</em></span> + and a <span class="emphasis"><em>domain</em></span>. + </p> + + <p> + As stated previously, a zone is a point of delegation in + the <acronym class="acronym">DNS</acronym> tree. A zone consists of + those contiguous parts of the domain + tree for which a name server has complete information and over which + it has authority. It contains all domain names from a certain point + downward in the domain tree except those which are delegated to + other zones. A delegation point is marked by one or more + <span class="emphasis"><em>NS records</em></span> in the + parent zone, which should be matched by equivalent NS records at + the root of the delegated zone. + </p> + + <p> + For instance, consider the <code class="literal">example.com</code> + domain which includes names + such as <code class="literal">host.aaa.example.com</code> and + <code class="literal">host.bbb.example.com</code> even though + the <code class="literal">example.com</code> zone includes + only delegations for the <code class="literal">aaa.example.com</code> and + <code class="literal">bbb.example.com</code> zones. A zone can + map + exactly to a single domain, but could also include only part of a + domain, the rest of which could be delegated to other + name servers. Every name in the <acronym class="acronym">DNS</acronym> + tree is a + <span class="emphasis"><em>domain</em></span>, even if it is + <span class="emphasis"><em>terminal</em></span>, that is, has no + <span class="emphasis"><em>subdomains</em></span>. Every subdomain is a domain and + every domain except the root is also a subdomain. The terminology is + not intuitive and we suggest that you read RFCs 1033, 1034 and 1035 + to + gain a complete understanding of this difficult and subtle + topic. + </p> + + <p> + Though <acronym class="acronym">BIND</acronym> is called a "domain name + server", + it deals primarily in terms of zones. The master and slave + declarations in the <code class="filename">named.conf</code> file + specify + zones, not domains. When you ask some other site if it is willing to + be a slave server for your <span class="emphasis"><em>domain</em></span>, you are + actually asking for slave service for some collection of zones. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="auth_servers"></a>Authoritative Name Servers</h3></div></div></div> + + <p> + Each zone is served by at least + one <span class="emphasis"><em>authoritative name server</em></span>, + which contains the complete data for the zone. + To make the DNS tolerant of server and network failures, + most zones have two or more authoritative servers, on + different networks. + </p> + + <p> + Responses from authoritative servers have the "authoritative + answer" (AA) bit set in the response packets. This makes them + easy to identify when debugging DNS configurations using tools like + <span class="command"><strong>dig</strong></span> (<a class="xref" href="Bv9ARM.ch03.html#diagnostic_tools" title="Diagnostic Tools">the section called “Diagnostic Tools”</a>). + </p> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="primary_master"></a>The Primary Master</h4></div></div></div> + + <p> + The authoritative server where the master copy of the zone + data is maintained is called the + <span class="emphasis"><em>primary master</em></span> server, or simply the + <span class="emphasis"><em>primary</em></span>. Typically it loads the zone + contents from some local file edited by humans or perhaps + generated mechanically from some other local file which is + edited by humans. This file is called the + <span class="emphasis"><em>zone file</em></span> or + <span class="emphasis"><em>master file</em></span>. + </p> + + <p> + In some cases, however, the master file may not be edited + by humans at all, but may instead be the result of + <span class="emphasis"><em>dynamic update</em></span> operations. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="slave_server"></a>Slave Servers</h4></div></div></div> + + <p> + The other authoritative servers, the <span class="emphasis"><em>slave</em></span> + servers (also known as <span class="emphasis"><em>secondary</em></span> servers) + load the zone contents from another server using a replication + process known as a <span class="emphasis"><em>zone transfer</em></span>. + Typically the data are transferred directly from the primary + master, but it is also possible to transfer it from another + slave. In other words, a slave server may itself act as a + master to a subordinate slave server. + </p> + <p> + Periodically, the slave server must send a refresh query to + determine whether the zone contents have been updated. This + is done by sending a query for the zone's SOA record and + checking whether the SERIAL field has been updated; if so, + a new transfer request is initiated. The timing of these + refresh queries is controlled by the SOA REFRESH and RETRY + fields, but can be overrridden with the + <span class="command"><strong>max-refresh-time</strong></span>, + <span class="command"><strong>min-refresh-time</strong></span>, + <span class="command"><strong>max-retry-time</strong></span>, and + <span class="command"><strong>min-retry-time</strong></span> options. + </p> + <p> + If the zone data cannot be updated within the time specified + by the SOA EXPIRE option (up to a hard-coded maximum of + 24 weeks) then the slave zone expires and will no longer + respond to queries. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="stealth_server"></a>Stealth Servers</h4></div></div></div> + + <p> + Usually all of the zone's authoritative servers are listed in + NS records in the parent zone. These NS records constitute + a <span class="emphasis"><em>delegation</em></span> of the zone from the parent. + The authoritative servers are also listed in the zone file itself, + at the <span class="emphasis"><em>top level</em></span> or <span class="emphasis"><em>apex</em></span> + of the zone. You can list servers in the zone's top-level NS + records that are not in the parent's NS delegation, but you cannot + list servers in the parent's delegation that are not present at + the zone's top level. + </p> + + <p> + A <span class="emphasis"><em>stealth server</em></span> is a server that is + authoritative for a zone but is not listed in that zone's NS + records. Stealth servers can be used for keeping a local copy of + a + zone to speed up access to the zone's records or to make sure that + the + zone is available even if all the "official" servers for the zone + are + inaccessible. + </p> + + <p> + A configuration where the primary master server itself is a + stealth server is often referred to as a "hidden primary" + configuration. One use for this configuration is when the primary + master + is behind a firewall and therefore unable to communicate directly + with the outside world. + </p> + + </div> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="cache_servers"></a>Caching Name Servers</h3></div></div></div> + + + + <p> + The resolver libraries provided by most operating systems are + <span class="emphasis"><em>stub resolvers</em></span>, meaning that they are not + capable of + performing the full DNS resolution process by themselves by talking + directly to the authoritative servers. Instead, they rely on a + local + name server to perform the resolution on their behalf. Such a + server + is called a <span class="emphasis"><em>recursive</em></span> name server; it performs + <span class="emphasis"><em>recursive lookups</em></span> for local clients. + </p> + + <p> + To improve performance, recursive servers cache the results of + the lookups they perform. Since the processes of recursion and + caching are intimately connected, the terms + <span class="emphasis"><em>recursive server</em></span> and + <span class="emphasis"><em>caching server</em></span> are often used synonymously. + </p> + + <p> + The length of time for which a record may be retained in + the cache of a caching name server is controlled by the + Time To Live (TTL) field associated with each resource record. + </p> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="forwarder"></a>Forwarding</h4></div></div></div> + + <p> + Even a caching name server does not necessarily perform + the complete recursive lookup itself. Instead, it can + <span class="emphasis"><em>forward</em></span> some or all of the queries + that it cannot satisfy from its cache to another caching name + server, + commonly referred to as a <span class="emphasis"><em>forwarder</em></span>. + </p> + + <p> + There may be one or more forwarders, + and they are queried in turn until the list is exhausted or an + answer + is found. Forwarders are typically used when you do not + wish all the servers at a given site to interact directly with the + rest of + the Internet servers. A typical scenario would involve a number + of internal <acronym class="acronym">DNS</acronym> servers and an + Internet firewall. Servers unable + to pass packets through the firewall would forward to the server + that can do it, and that server would query the Internet <acronym class="acronym">DNS</acronym> servers + on the internal server's behalf. + </p> + </div> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="multi_role"></a>Name Servers in Multiple Roles</h3></div></div></div> + + <p> + The <acronym class="acronym">BIND</acronym> name server can + simultaneously act as + a master for some zones, a slave for other zones, and as a caching + (recursive) server for a set of local clients. + </p> + + <p> + However, since the functions of authoritative name service + and caching/recursive name service are logically separate, it is + often advantageous to run them on separate server machines. + + A server that only provides authoritative name service + (an <span class="emphasis"><em>authoritative-only</em></span> server) can run with + recursion disabled, improving reliability and security. + + A server that is not authoritative for any zones and only provides + recursive service to local + clients (a <span class="emphasis"><em>caching-only</em></span> server) + does not need to be reachable from the Internet at large and can + be placed inside a firewall. + </p> + + </div> + </div> + + </div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="Bv9ARM.html">Prev</a> </td> +<td width="20%" align="center"> </td> +<td width="40%" align="right"> <a accesskey="n" href="Bv9ARM.ch02.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top">BIND 9 Administrator Reference Manual </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> Chapter 2. <acronym class="acronym">BIND</acronym> Resource Requirements</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/Bv9ARM.ch02.html b/doc/arm/Bv9ARM.ch02.html new file mode 100644 index 0000000..5c2a4e2 --- /dev/null +++ b/doc/arm/Bv9ARM.ch02.html @@ -0,0 +1,156 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Chapter 2. BIND Resource Requirements</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="prev" href="Bv9ARM.ch01.html" title="Chapter 1. Introduction"> +<link rel="next" href="Bv9ARM.ch03.html" title="Chapter 3. Name Server Configuration"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center">Chapter 2. <acronym class="acronym">BIND</acronym> Resource Requirements</th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="Bv9ARM.ch01.html">Prev</a> </td> +<th width="60%" align="center"> </th> +<td width="20%" align="right"> <a accesskey="n" href="Bv9ARM.ch03.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="chapter"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="Bv9ARM.ch02"></a>Chapter 2. <acronym class="acronym">BIND</acronym> Resource Requirements</h1></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="Bv9ARM.ch02.html#hw_req">Hardware requirements</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch02.html#cpu_req">CPU Requirements</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch02.html#mem_req">Memory Requirements</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch02.html#intensive_env">Name Server Intensive Environment Issues</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch02.html#supported_os">Supported Operating Systems</a></span></dt> +</dl> +</div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="hw_req"></a>Hardware requirements</h2></div></div></div> + <p> + <acronym class="acronym">DNS</acronym> hardware requirements have + traditionally been quite modest. + For many installations, servers that have been pensioned off from + active duty have performed admirably as <acronym class="acronym">DNS</acronym> servers. + </p> + <p> + The DNSSEC features of <acronym class="acronym">BIND</acronym> 9 + may prove to be quite + CPU intensive however, so organizations that make heavy use of these + features may wish to consider larger systems for these applications. + <acronym class="acronym">BIND</acronym> 9 is fully multithreaded, allowing + full utilization of + multiprocessor systems for installations that need it. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="cpu_req"></a>CPU Requirements</h2></div></div></div> + <p> + CPU requirements for <acronym class="acronym">BIND</acronym> 9 range from + i486-class machines + for serving of static zones without caching, to enterprise-class + machines if you intend to process many dynamic updates and DNSSEC + signed zones, serving many thousands of queries per second. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="mem_req"></a>Memory Requirements</h2></div></div></div> + <p> + The memory of the server has to be large enough to fit the + cache and zones loaded off disk. The <span class="command"><strong>max-cache-size</strong></span> + option can be used to limit the amount of memory used by the cache, + at the expense of reducing cache hit rates and causing more <acronym class="acronym">DNS</acronym> + traffic. + Additionally, if additional section caching + (<a class="xref" href="Bv9ARM.ch06.html#acache" title="Additional Section Caching">the section called “Additional Section Caching”</a>) is enabled, + the <span class="command"><strong>max-acache-size</strong></span> option can be used to + limit the amount + of memory used by the mechanism. + It is still good practice to have enough memory to load + all zone and cache data into memory — unfortunately, the best + way + to determine this for a given installation is to watch the name server + in operation. After a few weeks the server process should reach + a relatively stable size where entries are expiring from the cache as + fast as they are being inserted. + </p> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="intensive_env"></a>Name Server Intensive Environment Issues</h2></div></div></div> + + <p> + For name server intensive environments, there are two alternative + configurations that may be used. The first is where clients and + any second-level internal name servers query a main name server, which + has enough memory to build a large cache. This approach minimizes + the bandwidth used by external name lookups. The second alternative + is to set up second-level internal name servers to make queries + independently. + In this configuration, none of the individual machines needs to + have as much memory or CPU power as in the first alternative, but + this has the disadvantage of making many more external queries, + as none of the name servers share their cached data. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="supported_os"></a>Supported Operating Systems</h2></div></div></div> + + <p> + ISC <acronym class="acronym">BIND</acronym> 9 compiles and runs on a large + number + of Unix-like operating systems and on + Microsoft Windows Server 2003 and 2008, and Windows XP and Vista. + For an up-to-date + list of supported systems, see the README file in the top level + directory + of the BIND 9 source distribution. + </p> + </div> + </div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="Bv9ARM.ch01.html">Prev</a> </td> +<td width="20%" align="center"> </td> +<td width="40%" align="right"> <a accesskey="n" href="Bv9ARM.ch03.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top">Chapter 1. Introduction </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> Chapter 3. Name Server Configuration</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/Bv9ARM.ch03.html b/doc/arm/Bv9ARM.ch03.html new file mode 100644 index 0000000..70f29b8 --- /dev/null +++ b/doc/arm/Bv9ARM.ch03.html @@ -0,0 +1,764 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Chapter 3. Name Server Configuration</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="prev" href="Bv9ARM.ch02.html" title="Chapter 2. BIND Resource Requirements"> +<link rel="next" href="Bv9ARM.ch04.html" title="Chapter 4. Advanced DNS Features"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center">Chapter 3. Name Server Configuration</th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="Bv9ARM.ch02.html">Prev</a> </td> +<th width="60%" align="center"> </th> +<td width="20%" align="right"> <a accesskey="n" href="Bv9ARM.ch04.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="chapter"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="Bv9ARM.ch03"></a>Chapter 3. Name Server Configuration</h1></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="Bv9ARM.ch03.html#sample_configuration">Sample Configurations</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch03.html#cache_only_sample">A Caching-only Name Server</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch03.html#auth_only_sample">An Authoritative-only Name Server</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch03.html#load_balancing">Load Balancing</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch03.html#ns_operations">Name Server Operations</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch03.html#tools">Tools for Use With the Name Server Daemon</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch03.html#signals">Signals</a></span></dt> +</dl></dd> +</dl> +</div> + + <p> + In this chapter we provide some suggested configurations along + with guidelines for their use. We suggest reasonable values for + certain option settings. + </p> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="sample_configuration"></a>Sample Configurations</h2></div></div></div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="cache_only_sample"></a>A Caching-only Name Server</h3></div></div></div> + + <p> + The following sample configuration is appropriate for a caching-only + name server for use by clients internal to a corporation. All + queries + from outside clients are refused using the <span class="command"><strong>allow-query</strong></span> + option. Alternatively, the same effect could be achieved using + suitable + firewall rules. + </p> + +<pre class="programlisting"> +// Two corporate subnets we wish to allow queries from. +acl corpnets { 192.168.4.0/24; 192.168.7.0/24; }; +options { + // Working directory + directory "/etc/namedb"; + + allow-query { corpnets; }; +}; +// Provide a reverse mapping for the loopback +// address 127.0.0.1 +zone "0.0.127.in-addr.arpa" { + type master; + file "localhost.rev"; + notify no; +}; +</pre> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="auth_only_sample"></a>An Authoritative-only Name Server</h3></div></div></div> + + <p> + This sample configuration is for an authoritative-only server + that is the master server for "<code class="filename">example.com</code>" + and a slave for the subdomain "<code class="filename">eng.example.com</code>". + </p> + +<pre class="programlisting"> +options { + // Working directory + directory "/etc/namedb"; + // Do not allow access to cache + allow-query-cache { none; }; + // This is the default + allow-query { any; }; + // Do not provide recursive service + recursion no; +}; + +// Provide a reverse mapping for the loopback +// address 127.0.0.1 +zone "0.0.127.in-addr.arpa" { + type master; + file "localhost.rev"; + notify no; +}; +// We are the master server for example.com +zone "example.com" { + type master; + file "example.com.db"; + // IP addresses of slave servers allowed to + // transfer example.com + allow-transfer { + 192.168.4.14; + 192.168.5.53; + }; +}; +// We are a slave server for eng.example.com +zone "eng.example.com" { + type slave; + file "eng.example.com.bk"; + // IP address of eng.example.com master server + masters { 192.168.4.12; }; +}; +</pre> + + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="load_balancing"></a>Load Balancing</h2></div></div></div> + + + + <p> + A primitive form of load balancing can be achieved in + the <acronym class="acronym">DNS</acronym> by using multiple records + (such as multiple A records) for one name. + </p> + + <p> + For example, if you have three WWW servers with network addresses + of 10.0.0.1, 10.0.0.2 and 10.0.0.3, a set of records such as the + following means that clients will connect to each machine one third + of the time: + </p> + + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="0.875in" class="1"> +<col width="0.500in" class="2"> +<col width="0.750in" class="3"> +<col width="0.750in" class="4"> +<col width="2.028in" class="5"> +</colgroup> +<tbody> +<tr> +<td> + <p> + Name + </p> + </td> +<td> + <p> + TTL + </p> + </td> +<td> + <p> + CLASS + </p> + </td> +<td> + <p> + TYPE + </p> + </td> +<td> + <p> + Resource Record (RR) Data + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="literal">www</code> + </p> + </td> +<td> + <p> + <code class="literal">600</code> + </p> + </td> +<td> + <p> + <code class="literal">IN</code> + </p> + </td> +<td> + <p> + <code class="literal">A</code> + </p> + </td> +<td> + <p> + <code class="literal">10.0.0.1</code> + </p> + </td> +</tr> +<tr> +<td> + <p></p> + </td> +<td> + <p> + <code class="literal">600</code> + </p> + </td> +<td> + <p> + <code class="literal">IN</code> + </p> + </td> +<td> + <p> + <code class="literal">A</code> + </p> + </td> +<td> + <p> + <code class="literal">10.0.0.2</code> + </p> + </td> +</tr> +<tr> +<td> + <p></p> + </td> +<td> + <p> + <code class="literal">600</code> + </p> + </td> +<td> + <p> + <code class="literal">IN</code> + </p> + </td> +<td> + <p> + <code class="literal">A</code> + </p> + </td> +<td> + <p> + <code class="literal">10.0.0.3</code> + </p> + </td> +</tr> +</tbody> +</table> + </div> + <p> + When a resolver queries for these records, <acronym class="acronym">BIND</acronym> will rotate + them and respond to the query with the records in a different + order. In the example above, clients will randomly receive + records in the order 1, 2, 3; 2, 3, 1; and 3, 1, 2. Most clients + will use the first record returned and discard the rest. + </p> + <p> + For more detail on ordering responses, check the + <span class="command"><strong>rrset-order</strong></span> sub-statement in the + <span class="command"><strong>options</strong></span> statement, see + <a class="xref" href="Bv9ARM.ch06.html#rrset_ordering" title="RRset Ordering">RRset Ordering</a>. + </p> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ns_operations"></a>Name Server Operations</h2></div></div></div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="tools"></a>Tools for Use With the Name Server Daemon</h3></div></div></div> + <p> + This section describes several indispensable diagnostic, + administrative and monitoring tools available to the system + administrator for controlling and debugging the name server + daemon. + </p> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="diagnostic_tools"></a>Diagnostic Tools</h4></div></div></div> + <p> + The <span class="command"><strong>dig</strong></span>, <span class="command"><strong>host</strong></span>, and + <span class="command"><strong>nslookup</strong></span> programs are all command + line tools + for manually querying name servers. They differ in style and + output format. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><a name="dig"></a><span class="command"><strong>dig</strong></span></span></dt> +<dd> + <p> + <span class="command"><strong>dig</strong></span> + is the most versatile and complete of these lookup tools. + It has two modes: simple interactive + mode for a single query, and batch mode which executes a + query for + each in a list of several query lines. All query options are + accessible + from the command line. + </p> + <div class="cmdsynopsis"><p> + <code class="command">dig</code> + [@<em class="replaceable"><code>server</code></em>] + <em class="replaceable"><code>domain</code></em> + [<em class="replaceable"><code>query-type</code></em>] + [<em class="replaceable"><code>query-class</code></em>] + [+<em class="replaceable"><code>query-option</code></em>] + [-<em class="replaceable"><code>dig-option</code></em>] + [%<em class="replaceable"><code>comment</code></em>] + </p></div> + <p> + The usual simple use of <span class="command"><strong>dig</strong></span> will take the form + </p> + <p class="simpara"> + <span class="command"><strong>dig @server domain query-type query-class</strong></span> + </p> + <p> + For more information and a list of available commands and + options, see the <span class="command"><strong>dig</strong></span> man + page. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>host</strong></span></span></dt> +<dd> + <p> + The <span class="command"><strong>host</strong></span> utility emphasizes + simplicity + and ease of use. By default, it converts + between host names and Internet addresses, but its + functionality + can be extended with the use of options. + </p> + <div class="cmdsynopsis"><p> + <code class="command">host</code> + [-aCdlnrsTwv] + [-c <em class="replaceable"><code>class</code></em>] + [-N <em class="replaceable"><code>ndots</code></em>] + [-t <em class="replaceable"><code>type</code></em>] + [-W <em class="replaceable"><code>timeout</code></em>] + [-R <em class="replaceable"><code>retries</code></em>] + [-m <em class="replaceable"><code>flag</code></em>] + [-4] + [-6] + <em class="replaceable"><code>hostname</code></em> + [<em class="replaceable"><code>server</code></em>] + </p></div> + <p> + For more information and a list of available commands and + options, see the <span class="command"><strong>host</strong></span> man + page. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>nslookup</strong></span></span></dt> +<dd> + <p><span class="command"><strong>nslookup</strong></span> + has two modes: interactive and + non-interactive. Interactive mode allows the user to + query name servers for information about various + hosts and domains or to print a list of hosts in a + domain. Non-interactive mode is used to print just + the name and requested information for a host or + domain. + </p> + <div class="cmdsynopsis"><p> + <code class="command">nslookup</code> + [-option...] + [ + [<em class="replaceable"><code>host-to-find</code></em>] + | [- [server]] + ] + </p></div> + <p> + Interactive mode is entered when no arguments are given (the + default name server will be used) or when the first argument + is a + hyphen (`-') and the second argument is the host name or + Internet address + of a name server. + </p> + <p> + Non-interactive mode is used when the name or Internet + address + of the host to be looked up is given as the first argument. + The + optional second argument specifies the host name or address + of a name server. + </p> + <p> + Due to its arcane user interface and frequently inconsistent + behavior, we do not recommend the use of <span class="command"><strong>nslookup</strong></span>. + Use <span class="command"><strong>dig</strong></span> instead. + </p> + </dd> +</dl></div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="admin_tools"></a>Administrative Tools</h4></div></div></div> + <p> + Administrative tools play an integral part in the management + of a server. + </p> + <div class="variablelist"><dl class="variablelist"> +<dt> +<a name="named-checkconf"></a><span class="term"><span class="command"><strong>named-checkconf</strong></span></span> +</dt> +<dd> + <p> + The <span class="command"><strong>named-checkconf</strong></span> program + checks the syntax of a <code class="filename">named.conf</code> file. + </p> + <div class="cmdsynopsis"><p> + <code class="command">named-checkconf</code> + [-jvz] + [-t <em class="replaceable"><code>directory</code></em>] + [<em class="replaceable"><code>filename</code></em>] + </p></div> + </dd> +<dt> +<a name="named-checkzone"></a><span class="term"><span class="command"><strong>named-checkzone</strong></span></span> +</dt> +<dd> + <p> + The <span class="command"><strong>named-checkzone</strong></span> program + checks a master file for + syntax and consistency. + </p> + <div class="cmdsynopsis"><p> + <code class="command">named-checkzone</code> + [-djqvD] + [-c <em class="replaceable"><code>class</code></em>] + [-o <em class="replaceable"><code>output</code></em>] + [-t <em class="replaceable"><code>directory</code></em>] + [-w <em class="replaceable"><code>directory</code></em>] + [-k <em class="replaceable"><code>(ignore|warn|fail)</code></em>] + [-n <em class="replaceable"><code>(ignore|warn|fail)</code></em>] + [-W <em class="replaceable"><code>(ignore|warn)</code></em>] + <em class="replaceable"><code>zone</code></em> + [<em class="replaceable"><code>filename</code></em>] + </p></div> + </dd> +<dt> +<a name="named-compilezone"></a><span class="term"><span class="command"><strong>named-compilezone</strong></span></span> +</dt> +<dd> + <p> + Similar to <span class="command"><strong>named-checkzone,</strong></span> but + it always dumps the zone content to a specified file + (typically in a different format). + </p> + </dd> +<dt> +<a name="rndc"></a><span class="term"><span class="command"><strong>rndc</strong></span></span> +</dt> +<dd> + <p> + The remote name daemon control + (<span class="command"><strong>rndc</strong></span>) program allows the + system + administrator to control the operation of a name server. + Since <acronym class="acronym">BIND</acronym> 9.2, <span class="command"><strong>rndc</strong></span> + supports all the commands of the BIND 8 <span class="command"><strong>ndc</strong></span> + utility except <span class="command"><strong>ndc start</strong></span> and + <span class="command"><strong>ndc restart</strong></span>, which were also + not supported in <span class="command"><strong>ndc</strong></span>'s + channel mode. + If you run <span class="command"><strong>rndc</strong></span> without any + options + it will display a usage message as follows: + </p> + <div class="cmdsynopsis"><p> + <code class="command">rndc</code> + [-c <em class="replaceable"><code>config</code></em>] + [-s <em class="replaceable"><code>server</code></em>] + [-p <em class="replaceable"><code>port</code></em>] + [-y <em class="replaceable"><code>key</code></em>] + <em class="replaceable"><code>command</code></em> + [<em class="replaceable"><code>command</code></em>...] + </p></div> + + <p>See <a class="xref" href="man.rndc.html" title="rndc"><span class="refentrytitle"><span class="application">rndc</span></span>(8)</a> for details of + the available <span class="command"><strong>rndc</strong></span> commands. + </p> + + <p> + <span class="command"><strong>rndc</strong></span> requires a configuration file, + since all + communication with the server is authenticated with + digital signatures that rely on a shared secret, and + there is no way to provide that secret other than with a + configuration file. The default location for the + <span class="command"><strong>rndc</strong></span> configuration file is + <code class="filename">/etc/rndc.conf</code>, but an + alternate + location can be specified with the <code class="option">-c</code> + option. If the configuration file is not found, + <span class="command"><strong>rndc</strong></span> will also look in + <code class="filename">/etc/rndc.key</code> (or whatever + <code class="varname">sysconfdir</code> was defined when + the <acronym class="acronym">BIND</acronym> build was + configured). + The <code class="filename">rndc.key</code> file is + generated by + running <span class="command"><strong>rndc-confgen -a</strong></span> as + described in + <a class="xref" href="Bv9ARM.ch06.html#controls_statement_definition_and_usage" title="controls Statement Definition and Usage">the section called “<span class="command"><strong>controls</strong></span> Statement Definition and + Usage”</a>. + </p> + + <p> + The format of the configuration file is similar to + that of <code class="filename">named.conf</code>, but + limited to + only four statements, the <span class="command"><strong>options</strong></span>, + <span class="command"><strong>key</strong></span>, <span class="command"><strong>server</strong></span> and + <span class="command"><strong>include</strong></span> + statements. These statements are what associate the + secret keys to the servers with which they are meant to + be shared. The order of statements is not + significant. + </p> + + <p> + The <span class="command"><strong>options</strong></span> statement has + three clauses: + <span class="command"><strong>default-server</strong></span>, <span class="command"><strong>default-key</strong></span>, + and <span class="command"><strong>default-port</strong></span>. + <span class="command"><strong>default-server</strong></span> takes a + host name or address argument and represents the server + that will + be contacted if no <code class="option">-s</code> + option is provided on the command line. + <span class="command"><strong>default-key</strong></span> takes + the name of a key as its argument, as defined by a <span class="command"><strong>key</strong></span> statement. + <span class="command"><strong>default-port</strong></span> specifies the + port to which + <span class="command"><strong>rndc</strong></span> should connect if no + port is given on the command line or in a + <span class="command"><strong>server</strong></span> statement. + </p> + + <p> + The <span class="command"><strong>key</strong></span> statement defines a + key to be used + by <span class="command"><strong>rndc</strong></span> when authenticating + with + <span class="command"><strong>named</strong></span>. Its syntax is + identical to the + <span class="command"><strong>key</strong></span> statement in <code class="filename">named.conf</code>. + The keyword <strong class="userinput"><code>key</code></strong> is + followed by a key name, which must be a valid + domain name, though it need not actually be hierarchical; + thus, + a string like "<strong class="userinput"><code>rndc_key</code></strong>" is a valid + name. + The <span class="command"><strong>key</strong></span> statement has two + clauses: + <span class="command"><strong>algorithm</strong></span> and <span class="command"><strong>secret</strong></span>. + While the configuration parser will accept any string as the + argument + to algorithm, currently only the strings + "<strong class="userinput"><code>hmac-md5</code></strong>", + "<strong class="userinput"><code>hmac-sha1</code></strong>", + "<strong class="userinput"><code>hmac-sha224</code></strong>", + "<strong class="userinput"><code>hmac-sha256</code></strong>", + "<strong class="userinput"><code>hmac-sha384</code></strong>" + and "<strong class="userinput"><code>hmac-sha512</code></strong>" + have any meaning. The secret is a Base64 encoded string + as specified in RFC 3548. + </p> + + <p> + The <span class="command"><strong>server</strong></span> statement + associates a key + defined using the <span class="command"><strong>key</strong></span> + statement with a server. + The keyword <strong class="userinput"><code>server</code></strong> is followed by a + host name or address. The <span class="command"><strong>server</strong></span> statement + has two clauses: <span class="command"><strong>key</strong></span> and <span class="command"><strong>port</strong></span>. + The <span class="command"><strong>key</strong></span> clause specifies the + name of the key + to be used when communicating with this server, and the + <span class="command"><strong>port</strong></span> clause can be used to + specify the port <span class="command"><strong>rndc</strong></span> should + connect + to on the server. + </p> + + <p> + A sample minimal configuration file is as follows: + </p> + +<pre class="programlisting"> +key rndc_key { + algorithm "hmac-sha256"; + secret + "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K"; +}; +options { + default-server 127.0.0.1; + default-key rndc_key; +}; +</pre> + + <p> + This file, if installed as <code class="filename">/etc/rndc.conf</code>, + would allow the command: + </p> + + <p> + <code class="prompt">$ </code><strong class="userinput"><code>rndc reload</code></strong> + </p> + + <p> + to connect to 127.0.0.1 port 953 and cause the name server + to reload, if a name server on the local machine were + running with + following controls statements: + </p> + +<pre class="programlisting"> +controls { + inet 127.0.0.1 + allow { localhost; } keys { rndc_key; }; +}; +</pre> + + <p> + and it had an identical key statement for + <code class="literal">rndc_key</code>. + </p> + + <p> + Running the <span class="command"><strong>rndc-confgen</strong></span> + program will + conveniently create a <code class="filename">rndc.conf</code> + file for you, and also display the + corresponding <span class="command"><strong>controls</strong></span> + statement that you need to + add to <code class="filename">named.conf</code>. + Alternatively, + you can run <span class="command"><strong>rndc-confgen -a</strong></span> + to set up + a <code class="filename">rndc.key</code> file and not + modify + <code class="filename">named.conf</code> at all. + </p> + + </dd> +</dl></div> + + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="signals"></a>Signals</h3></div></div></div> + <p> + Certain UNIX signals cause the name server to take specific + actions, as described in the following table. These signals can + be sent using the <span class="command"><strong>kill</strong></span> command. + </p> + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.125in" class="1"> +<col width="4.000in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p><span class="command"><strong>SIGHUP</strong></span></p> + </td> +<td> + <p> + Causes the server to read <code class="filename">named.conf</code> and + reload the database. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>SIGTERM</strong></span></p> + </td> +<td> + <p> + Causes the server to clean up and exit. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>SIGINT</strong></span></p> + </td> +<td> + <p> + Causes the server to clean up and exit. + </p> + </td> +</tr> +</tbody> +</table> + </div> + </div> + </div> + </div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="Bv9ARM.ch02.html">Prev</a> </td> +<td width="20%" align="center"> </td> +<td width="40%" align="right"> <a accesskey="n" href="Bv9ARM.ch04.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top">Chapter 2. <acronym class="acronym">BIND</acronym> Resource Requirements </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> Chapter 4. Advanced DNS Features</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/Bv9ARM.ch04.html b/doc/arm/Bv9ARM.ch04.html new file mode 100644 index 0000000..1a86226 --- /dev/null +++ b/doc/arm/Bv9ARM.ch04.html @@ -0,0 +1,2872 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Chapter 4. Advanced DNS Features</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="prev" href="Bv9ARM.ch03.html" title="Chapter 3. Name Server Configuration"> +<link rel="next" href="Bv9ARM.ch05.html" title="Chapter 5. The BIND 9 Lightweight Resolver"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center">Chapter 4. Advanced DNS Features</th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="Bv9ARM.ch03.html">Prev</a> </td> +<th width="60%" align="center"> </th> +<td width="20%" align="right"> <a accesskey="n" href="Bv9ARM.ch05.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="chapter"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="Bv9ARM.ch04"></a>Chapter 4. Advanced DNS Features</h1></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="Bv9ARM.ch04.html#notify">Notify</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#dynamic_update">Dynamic Update</a></span></dt> +<dd><dl><dt><span class="section"><a href="Bv9ARM.ch04.html#journal">The journal file</a></span></dt></dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch04.html#incremental_zone_transfers">Incremental Zone Transfers (IXFR)</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#split_dns">Split DNS</a></span></dt> +<dd><dl><dt><span class="section"><a href="Bv9ARM.ch04.html#split_dns_sample">Example split DNS setup</a></span></dt></dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch04.html#tsig">TSIG</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.6.5">Generating a Shared Key</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.6.6">Loading A New Key</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.6.7">Instructing the Server to Use a Key</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.6.8">TSIG-Based Access Control</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.6.9">Errors</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch04.html#tkey">TKEY</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#sig0">SIG(0)</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#DNSSEC">DNSSEC</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch04.html#dnssec_keys">Generating Keys</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#dnssec_signing">Signing the Zone</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#dnssec_config">Configuring Servers</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch04.html#dnssec.dynamic.zones">DNSSEC, Dynamic Zones, and Automatic Signing</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.2">Converting from insecure to secure</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.7">Dynamic DNS update method</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.15">Fully automatic zone signing</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.24">Private-type records</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.31">DNSKEY rollovers</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.33">Dynamic DNS update method</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.38">Automatic key rollovers</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.40">NSEC3PARAM rollovers via UPDATE</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.42">Converting from NSEC to NSEC3</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.44">Converting from NSEC3 to NSEC</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.46">Converting from secure to insecure</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.50">Periodic re-signing</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.52">NSEC3 and OPTOUT</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch04.html#rfc5011.support">Dynamic Trust Anchor Management</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.11.3">Validating Resolver</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.11.4">Authoritative Server</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch04.html#pkcs11">PKCS#11 (Cryptoki) support</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.12.6">Prerequisites</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.12.7">Native PKCS#11</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.12.8">OpenSSL-based PKCS#11</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.12.9">PKCS#11 Tools</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.12.10">Using the HSM</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.12.11">Specifying the engine on the command line</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.12.12">Running named with automatic zone re-signing</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch04.html#dlz-info">DLZ (Dynamically Loadable Zones)</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.13.6">Configuring DLZ</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.13.7">Sample DLZ Driver</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch04.html#dyndb-info">DynDB (Dynamic Database)</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.14.5">Configuring DynDB</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.14.6">Sample DynDB Module</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch04.html#catz-info">Catalog Zones</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.15.4">Principle of Operation</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.15.5">Configuring Catalog Zones</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.15.6">Catalog Zone format</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch04.html#ipv6">IPv6 Support in <acronym class="acronym">BIND</acronym> 9</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.16.6">Address Lookups Using AAAA Records</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.16.7">Address to Name Lookups Using Nibble Format</a></span></dt> +</dl></dd> +</dl> +</div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="notify"></a>Notify</h2></div></div></div> + <p> + <acronym class="acronym">DNS</acronym> NOTIFY is a mechanism that allows master + servers to notify their slave servers of changes to a zone's data. In + response to a <span class="command"><strong>NOTIFY</strong></span> from a master server, the + slave will check to see that its version of the zone is the + current version and, if not, initiate a zone transfer. + </p> + + <p> + For more information about <acronym class="acronym">DNS</acronym> + <span class="command"><strong>NOTIFY</strong></span>, see the description of the + <span class="command"><strong>notify</strong></span> option in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a> and + the description of the zone option <span class="command"><strong>also-notify</strong></span> in + <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. The <span class="command"><strong>NOTIFY</strong></span> + protocol is specified in RFC 1996. + </p> + + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> +<p> + As a slave zone can also be a master to other slaves, <span class="command"><strong>named</strong></span>, + by default, sends <span class="command"><strong>NOTIFY</strong></span> messages for every zone + it loads. Specifying <span class="command"><strong>notify master-only;</strong></span> will + cause <span class="command"><strong>named</strong></span> to only send <span class="command"><strong>NOTIFY</strong></span> for master + zones that it loads. + </p> +</div> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="dynamic_update"></a>Dynamic Update</h2></div></div></div> + + <p> + Dynamic Update is a method for adding, replacing or deleting + records in a master server by sending it a special form of DNS + messages. The format and meaning of these messages is specified + in RFC 2136. + </p> + + <p> + Dynamic update is enabled by including an + <span class="command"><strong>allow-update</strong></span> or an <span class="command"><strong>update-policy</strong></span> + clause in the <span class="command"><strong>zone</strong></span> statement. + </p> + + <p> + If the zone's <span class="command"><strong>update-policy</strong></span> is set to + <strong class="userinput"><code>local</code></strong>, updates to the zone + will be permitted for the key <code class="varname">local-ddns</code>, + which will be generated by <span class="command"><strong>named</strong></span> at startup. + See <a class="xref" href="Bv9ARM.ch06.html#dynamic_update_policies" title="Dynamic Update Policies">the section called “Dynamic Update Policies”</a> for more details. + </p> + + <p> + Dynamic updates using Kerberos signed requests can be made + using the TKEY/GSS protocol by setting either the + <span class="command"><strong>tkey-gssapi-keytab</strong></span> option, or alternatively + by setting both the <span class="command"><strong>tkey-gssapi-credential</strong></span> + and <span class="command"><strong>tkey-domain</strong></span> options. Once enabled, + Kerberos signed requests will be matched against the update + policies for the zone, using the Kerberos principal as the + signer for the request. + </p> + + <p> + Updating of secure zones (zones using DNSSEC) follows RFC + 3007: RRSIG, NSEC and NSEC3 records affected by updates are + automatically regenerated by the server using an online + zone key. Update authorization is based on transaction + signatures and an explicit server policy. + </p> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="journal"></a>The journal file</h3></div></div></div> + + <p> + All changes made to a zone using dynamic update are stored + in the zone's journal file. This file is automatically created + by the server when the first dynamic update takes place. + The name of the journal file is formed by appending the extension + <code class="filename">.jnl</code> to the name of the + corresponding zone + file unless specifically overridden. The journal file is in a + binary format and should not be edited manually. + </p> + + <p> + The server will also occasionally write ("dump") + the complete contents of the updated zone to its zone file. + This is not done immediately after + each dynamic update, because that would be too slow when a large + zone is updated frequently. Instead, the dump is delayed by + up to 15 minutes, allowing additional updates to take place. + During the dump process, transient files will be created + with the extensions <code class="filename">.jnw</code> and + <code class="filename">.jbk</code>; under ordinary circumstances, these + will be removed when the dump is complete, and can be safely + ignored. + </p> + + <p> + When a server is restarted after a shutdown or crash, it will replay + the journal file to incorporate into the zone any updates that + took + place after the last zone dump. + </p> + + <p> + Changes that result from incoming incremental zone transfers are + also + journalled in a similar way. + </p> + + <p> + The zone files of dynamic zones cannot normally be edited by + hand because they are not guaranteed to contain the most recent + dynamic changes — those are only in the journal file. + The only way to ensure that the zone file of a dynamic zone + is up to date is to run <span class="command"><strong>rndc stop</strong></span>. + </p> + + <p> + If you have to make changes to a dynamic zone + manually, the following procedure will work: + Disable dynamic updates to the zone using + <span class="command"><strong>rndc freeze <em class="replaceable"><code>zone</code></em></strong></span>. + This will update the zone's master file with the changes + stored in its <code class="filename">.jnl</code> file. + Edit the zone file. Run + <span class="command"><strong>rndc thaw <em class="replaceable"><code>zone</code></em></strong></span> + to reload the changed zone and re-enable dynamic updates. + </p> + + <p> + <span class="command"><strong>rndc sync <em class="replaceable"><code>zone</code></em></strong></span> + will update the zone file with changes from the journal file + without stopping dynamic updates; this may be useful for viewing + the current zone state. To remove the <code class="filename">.jnl</code> + file after updating the zone file, use + <span class="command"><strong>rndc sync -clean</strong></span>. + </p> + + </div> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="incremental_zone_transfers"></a>Incremental Zone Transfers (IXFR)</h2></div></div></div> + + <p> + The incremental zone transfer (IXFR) protocol is a way for + slave servers to transfer only changed data, instead of having to + transfer the entire zone. The IXFR protocol is specified in RFC + 1995. See <a class="xref" href="Bv9ARM.ch11.html#proposed_standards" title="Proposed Standards">Proposed Standards</a>. + </p> + + <p> + When acting as a master, <acronym class="acronym">BIND</acronym> 9 + supports IXFR for those zones + where the necessary change history information is available. These + include master zones maintained by dynamic update and slave zones + whose data was obtained by IXFR. For manually maintained master + zones, and for slave zones obtained by performing a full zone + transfer (AXFR), IXFR is supported only if the option + <span class="command"><strong>ixfr-from-differences</strong></span> is set + to <strong class="userinput"><code>yes</code></strong>. + </p> + + <p> + When acting as a slave, <acronym class="acronym">BIND</acronym> 9 will + attempt to use IXFR unless + it is explicitly disabled. For more information about disabling + IXFR, see the description of the <span class="command"><strong>request-ixfr</strong></span> clause + of the <span class="command"><strong>server</strong></span> statement. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="split_dns"></a>Split DNS</h2></div></div></div> + + <p> + Setting up different views, or visibility, of the DNS space to + internal and external resolvers is usually referred to as a + <span class="emphasis"><em>Split DNS</em></span> setup. There are several + reasons an organization would want to set up its DNS this way. + </p> + <p> + One common reason for setting up a DNS system this way is + to hide "internal" DNS information from "external" clients on the + Internet. There is some debate as to whether or not this is actually + useful. + Internal DNS information leaks out in many ways (via email headers, + for example) and most savvy "attackers" can find the information + they need using other means. + However, since listing addresses of internal servers that + external clients cannot possibly reach can result in + connection delays and other annoyances, an organization may + choose to use a Split DNS to present a consistent view of itself + to the outside world. + </p> + <p> + Another common reason for setting up a Split DNS system is + to allow internal networks that are behind filters or in RFC 1918 + space (reserved IP space, as documented in RFC 1918) to resolve DNS + on the Internet. Split DNS can also be used to allow mail from outside + back in to the internal network. + </p> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="split_dns_sample"></a>Example split DNS setup</h3></div></div></div> + <p> + Let's say a company named <span class="emphasis"><em>Example, Inc.</em></span> + (<code class="literal">example.com</code>) + has several corporate sites that have an internal network with + reserved + Internet Protocol (IP) space and an external demilitarized zone (DMZ), + or "outside" section of a network, that is available to the public. + </p> + <p> + <span class="emphasis"><em>Example, Inc.</em></span> wants its internal clients + to be able to resolve external hostnames and to exchange mail with + people on the outside. The company also wants its internal resolvers + to have access to certain internal-only zones that are not available + at all outside of the internal network. + </p> + <p> + In order to accomplish this, the company will set up two sets + of name servers. One set will be on the inside network (in the + reserved + IP space) and the other set will be on bastion hosts, which are + "proxy" + hosts that can talk to both sides of its network, in the DMZ. + </p> + <p> + The internal servers will be configured to forward all queries, + except queries for <code class="filename">site1.internal</code>, <code class="filename">site2.internal</code>, <code class="filename">site1.example.com</code>, + and <code class="filename">site2.example.com</code>, to the servers + in the + DMZ. These internal servers will have complete sets of information + for <code class="filename">site1.example.com</code>, <code class="filename">site2.example.com</code>, <code class="filename">site1.internal</code>, + and <code class="filename">site2.internal</code>. + </p> + <p> + To protect the <code class="filename">site1.internal</code> and <code class="filename">site2.internal</code> domains, + the internal name servers must be configured to disallow all queries + to these domains from any external hosts, including the bastion + hosts. + </p> + <p> + The external servers, which are on the bastion hosts, will + be configured to serve the "public" version of the <code class="filename">site1</code> and <code class="filename">site2.example.com</code> zones. + This could include things such as the host records for public servers + (<code class="filename">www.example.com</code> and <code class="filename">ftp.example.com</code>), + and mail exchange (MX) records (<code class="filename">a.mx.example.com</code> and <code class="filename">b.mx.example.com</code>). + </p> + <p> + In addition, the public <code class="filename">site1</code> and <code class="filename">site2.example.com</code> zones + should have special MX records that contain wildcard (`*') records + pointing to the bastion hosts. This is needed because external mail + servers do not have any other way of looking up how to deliver mail + to those internal hosts. With the wildcard records, the mail will + be delivered to the bastion host, which can then forward it on to + internal hosts. + </p> + <p> + Here's an example of a wildcard MX record: + </p> + <pre class="programlisting">* IN MX 10 external1.example.com.</pre> + <p> + Now that they accept mail on behalf of anything in the internal + network, the bastion hosts will need to know how to deliver mail + to internal hosts. In order for this to work properly, the resolvers + on + the bastion hosts will need to be configured to point to the internal + name servers for DNS resolution. + </p> + <p> + Queries for internal hostnames will be answered by the internal + servers, and queries for external hostnames will be forwarded back + out to the DNS servers on the bastion hosts. + </p> + <p> + In order for all this to work properly, internal clients will + need to be configured to query <span class="emphasis"><em>only</em></span> the internal + name servers for DNS queries. This could also be enforced via + selective + filtering on the network. + </p> + <p> + If everything has been set properly, <span class="emphasis"><em>Example, Inc.</em></span>'s + internal clients will now be able to: + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + + Look up any hostnames in the <code class="literal">site1</code> + and + <code class="literal">site2.example.com</code> zones. + + </li> +<li class="listitem"> + + Look up any hostnames in the <code class="literal">site1.internal</code> and + <code class="literal">site2.internal</code> domains. + + </li> +<li class="listitem"> + Look up any hostnames on the Internet. + </li> +<li class="listitem"> + Exchange mail with both internal and external people. + </li> +</ul></div> + <p> + Hosts on the Internet will be able to: + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + + Look up any hostnames in the <code class="literal">site1</code> + and + <code class="literal">site2.example.com</code> zones. + + </li> +<li class="listitem"> + + Exchange mail with anyone in the <code class="literal">site1</code> and + <code class="literal">site2.example.com</code> zones. + + </li> +</ul></div> + + <p> + Here is an example configuration for the setup we just + described above. Note that this is only configuration information; + for information on how to configure your zone files, see <a class="xref" href="Bv9ARM.ch03.html#sample_configuration" title="Sample Configurations">the section called “Sample Configurations”</a>. + </p> + + <p> + Internal DNS server config: + </p> + +<pre class="programlisting"> + +acl internals { 172.16.72.0/24; 192.168.1.0/24; }; + +acl externals { <code class="varname">bastion-ips-go-here</code>; }; + +options { + ... + ... + forward only; + // forward to external servers + forwarders { + <code class="varname">bastion-ips-go-here</code>; + }; + // sample allow-transfer (no one) + allow-transfer { none; }; + // restrict query access + allow-query { internals; externals; }; + // restrict recursion + allow-recursion { internals; }; + ... + ... +}; + +// sample master zone +zone "site1.example.com" { + type master; + file "m/site1.example.com"; + // do normal iterative resolution (do not forward) + forwarders { }; + allow-query { internals; externals; }; + allow-transfer { internals; }; +}; + +// sample slave zone +zone "site2.example.com" { + type slave; + file "s/site2.example.com"; + masters { 172.16.72.3; }; + forwarders { }; + allow-query { internals; externals; }; + allow-transfer { internals; }; +}; + +zone "site1.internal" { + type master; + file "m/site1.internal"; + forwarders { }; + allow-query { internals; }; + allow-transfer { internals; } +}; + +zone "site2.internal" { + type slave; + file "s/site2.internal"; + masters { 172.16.72.3; }; + forwarders { }; + allow-query { internals }; + allow-transfer { internals; } +}; +</pre> + + <p> + External (bastion host) DNS server config: + </p> + +<pre class="programlisting"> +acl internals { 172.16.72.0/24; 192.168.1.0/24; }; + +acl externals { bastion-ips-go-here; }; + +options { + ... + ... + // sample allow-transfer (no one) + allow-transfer { none; }; + // default query access + allow-query { any; }; + // restrict cache access + allow-query-cache { internals; externals; }; + // restrict recursion + allow-recursion { internals; externals; }; + ... + ... +}; + +// sample slave zone +zone "site1.example.com" { + type master; + file "m/site1.foo.com"; + allow-transfer { internals; externals; }; +}; + +zone "site2.example.com" { + type slave; + file "s/site2.foo.com"; + masters { another_bastion_host_maybe; }; + allow-transfer { internals; externals; } +}; +</pre> + + <p> + In the <code class="filename">resolv.conf</code> (or equivalent) on + the bastion host(s): + </p> + +<pre class="programlisting"> +search ... +nameserver 172.16.72.2 +nameserver 172.16.72.3 +nameserver 172.16.72.4 +</pre> + + </div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="tsig"></a>TSIG</h2></div></div></div> + + <p> + TSIG (Transaction SIGnatures) is a mechanism for authenticating DNS + messages, originally specified in RFC 2845. It allows DNS messages + to be cryptographically signed using a shared secret. TSIG can + be used in any DNS transaction, as a way to restrict access to + certain server functions (e.g., recursive queries) to authorized + clients when IP-based access control is insufficient or needs to + be overridden, or as a way to ensure message authenticity when it + is critical to the integrity of the server, such as with dynamic + UPDATE messages or zone transfers from a master to a slave server. + </p> + <p> + This is a guide to setting up TSIG in <acronym class="acronym">BIND</acronym>. + It describes the configuration syntax and the process of creating + TSIG keys. + </p> + <p> + <span class="command"><strong>named</strong></span> supports TSIG for server-to-server + communication, and some of the tools included with + <acronym class="acronym">BIND</acronym> support it for sending messages to + <span class="command"><strong>named</strong></span>: + </p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <a class="xref" href="man.nsupdate.html" title="nsupdate"><span class="refentrytitle"><span class="application">nsupdate</span></span>(1)</a> supports TSIG via the + <code class="option">-k</code>, <code class="option">-l</code> and + <code class="option">-y</code> command line options, or via + the <span class="command"><strong>key</strong></span> command when running + interactively. + </li> +<li class="listitem"> + <a class="xref" href="man.dig.html" title="dig"><span class="refentrytitle">dig</span>(1)</a> supports TSIG via the + <code class="option">-k</code> and <code class="option">-y</code> command + line options. + </li> +</ul></div> +<p> + </p> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.6.5"></a>Generating a Shared Key</h3></div></div></div> + <p> + TSIG keys can be generated using the <span class="command"><strong>tsig-keygen</strong></span> + command; the output of the command is a <span class="command"><strong>key</strong></span> directive + suitable for inclusion in <code class="filename">named.conf</code>. The + key name, algorithm and size can be specified by command line parameters; + the defaults are "tsig-key", HMAC-SHA256, and 256 bits, respectively. + </p> + <p> + Any string which is a valid DNS name can be used as a key name. + For example, a key to be shared between servers called + <span class="emphasis"><em>host1</em></span> and <span class="emphasis"><em>host2</em></span> could + be called "host1-host2.", and this key could be generated using: + </p> +<pre class="programlisting"> + $ tsig-keygen host1-host2. > host1-host2.key +</pre> + <p> + This key may then be copied to both hosts. The key name and secret + must be identical on both hosts. + (Note: copying a shared secret from one server to another is beyond + the scope of the DNS. A secure transport mechanism should be used: + secure FTP, SSL, ssh, telephone, encrypted email, etc.) + </p> + <p> + <span class="command"><strong>tsig-keygen</strong></span> can also be run as + <span class="command"><strong>ddns-confgen</strong></span>, in which case its output includes + additional configuration text for setting up dynamic DNS in + <span class="command"><strong>named</strong></span>. See <a class="xref" href="man.ddns-confgen.html" title="ddns-confgen"><span class="refentrytitle"><span class="application">ddns-confgen</span></span>(8)</a> + for details. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.6.6"></a>Loading A New Key</h3></div></div></div> + <p> + For a key shared between servers called + <span class="emphasis"><em>host1</em></span> and <span class="emphasis"><em>host2</em></span>, + the following could be added to each server's + <code class="filename">named.conf</code> file: + </p> +<pre class="programlisting"> +key "host1-host2." { + algorithm hmac-sha256; + secret "DAopyf1mhCbFVZw7pgmNPBoLUq8wEUT7UuPoLENP2HY="; +}; +</pre> + <p> + (This is the same key generated above using + <span class="command"><strong>tsig-keygen</strong></span>.) + </p> + <p> + Since this text contains a secret, it + is recommended that either <code class="filename">named.conf</code> not be + world-readable, or that the <span class="command"><strong>key</strong></span> directive + be stored in a file which is not world-readable, and which is + included in <code class="filename">named.conf</code> via the + <span class="command"><strong>include</strong></span> directive. + </p> + <p> + Once a key has been added to <code class="filename">named.conf</code> and the + server has been restarted or reconfigured, the server can recognize + the key. If the server receives a message signed by the + key, it will be able to verify the signature. If the signature + is valid, the response will be signed using the same key. + </p> + <p> + TSIG keys that are known to a server can be listed using the + command <span class="command"><strong>rndc tsig-list</strong></span>. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.6.7"></a>Instructing the Server to Use a Key</h3></div></div></div> + <p> + A server sending a request to another server must be told whether + to use a key, and if so, which key to use. + </p> + <p> + For example, a key may be specified for each server in the + <span class="command"><strong>masters</strong></span> statement in the definition of a + slave zone; in this case, all SOA QUERY messages, NOTIFY + messages, and zone transfer requests (AXFR or IXFR) will be + signed using the specified key. Keys may also be specified + in the <span class="command"><strong>also-notify</strong></span> statement of a master + or slave zone, causing NOTIFY messages to be signed using + the specified key. + </p> + <p> + Keys can also be specified in a <span class="command"><strong>server</strong></span> + directive. Adding the following on <span class="emphasis"><em>host1</em></span>, + if the IP address of <span class="emphasis"><em>host2</em></span> is 10.1.2.3, would + cause <span class="emphasis"><em>all</em></span> requests from <span class="emphasis"><em>host1</em></span> + to <span class="emphasis"><em>host2</em></span>, including normal DNS queries, to be + signed using the <span class="command"><strong>host1-host2.</strong></span> key: + </p> +<pre class="programlisting"> +server 10.1.2.3 { + keys { host1-host2. ;}; +}; +</pre> + <p> + Multiple keys may be present in the <span class="command"><strong>keys</strong></span> + statement, but only the first one is used. As this directive does + not contain secrets, it can be used in a world-readable file. + </p> + <p> + Requests sent by <span class="emphasis"><em>host2</em></span> to <span class="emphasis"><em>host1</em></span> + would <span class="emphasis"><em>not</em></span> be signed, unless a similar + <span class="command"><strong>server</strong></span> directive were in <span class="emphasis"><em>host2</em></span>'s + configuration file. + </p> + <p> + Whenever any server sends a TSIG-signed DNS request, it will expect + the response to be signed with the same key. If a response is not + signed, or if the signature is not valid, the response will be + rejected. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.6.8"></a>TSIG-Based Access Control</h3></div></div></div> + <p> + TSIG keys may be specified in ACL definitions and ACL directives + such as <span class="command"><strong>allow-query</strong></span>, <span class="command"><strong>allow-transfer</strong></span> + and <span class="command"><strong>allow-update</strong></span>. + The above key would be denoted in an ACL element as + <span class="command"><strong>key host1-host2.</strong></span> + </p> + <p> + An example of an <span class="command"><strong>allow-update</strong></span> directive using + a TSIG key: + </p> +<pre class="programlisting"> +allow-update { !{ !localnets; any; }; key host1-host2. ;}; +</pre> + <p> + This allows dynamic updates to succeed only if the UPDATE + request comes from an address in <span class="command"><strong>localnets</strong></span>, + <span class="emphasis"><em>and</em></span> if it is signed using the + <span class="command"><strong>host1-host2.</strong></span> key. + </p> + <p> + See <a class="xref" href="Bv9ARM.ch06.html#dynamic_update_policies" title="Dynamic Update Policies">the section called “Dynamic Update Policies”</a> for a discussion of + the more flexible <span class="command"><strong>update-policy</strong></span> statement. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.6.9"></a>Errors</h3></div></div></div> + <p> + Processing of TSIG-signed messages can result in several errors: + </p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + If a TSIG-aware server receives a message signed by an + unknown key, the response will be unsigned, with the TSIG + extended error code set to BADKEY. + </li> +<li class="listitem"> + If a TSIG-aware server receives a message from a known key + but with an invalid signature, the response will be unsigned, + with the TSIG extended error code set to BADSIG. + </li> +<li class="listitem"> + If a TSIG-aware server receives a message with a time + outside of the allowed range, the response will be signed, with + the TSIG extended error code set to BADTIME, and the time values + will be adjusted so that the response can be successfully + verified. + </li> +</ul></div> +<p> + In all of the above cases, the server will return a response code + of NOTAUTH (not authenticated). + </p> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="tkey"></a>TKEY</h2></div></div></div> + + <p> + TKEY (Transaction KEY) is a mechanism for automatically negotiating + a shared secret between two hosts, originally specified in RFC 2930. + </p> + <p> + There are several TKEY "modes" that specify how a key is to be + generated or assigned. <acronym class="acronym">BIND</acronym> 9 implements only + one of these modes: Diffie-Hellman key exchange. Both hosts are + required to have a KEY record with algorithm DH (though this + record is not required to be present in a zone). + </p> + <p> + The TKEY process is initiated by a client or server by sending + a query of type TKEY to a TKEY-aware server. The query must include + an appropriate KEY record in the additional section, and + must be signed using either TSIG or SIG(0) with a previously + established key. The server's response, if successful, will + contain a TKEY record in its answer section. After this transaction, + both participants will have enough information to calculate a + shared secret using Diffie-Hellman key exchange. The shared secret + can then be used by to sign subsequent transactions between the + two servers. + </p> + <p> + TSIG keys known by the server, including TKEY-negotiated keys, can + be listed using <span class="command"><strong>rndc tsig-list</strong></span>. + </p> + <p> + TKEY-negotiated keys can be deleted from a server using + <span class="command"><strong>rndc tsig-delete</strong></span>. This can also be done via + the TKEY protocol itself, by sending an authenticated TKEY query + specifying the "key deletion" mode. + </p> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="sig0"></a>SIG(0)</h2></div></div></div> + + <p> + <acronym class="acronym">BIND</acronym> partially supports DNSSEC SIG(0) + transaction signatures as specified in RFC 2535 and RFC 2931. + SIG(0) uses public/private keys to authenticate messages. Access control + is performed in the same manner as TSIG keys; privileges can be + granted or denied in ACL directives based on the key name. + </p> + <p> + When a SIG(0) signed message is received, it will only be + verified if the key is known and trusted by the server. The + server will not attempt to recursively fetch or validate the + key. + </p> + <p> + SIG(0) signing of multiple-message TCP streams is not supported. + </p> + <p> + The only tool shipped with <acronym class="acronym">BIND</acronym> 9 that + generates SIG(0) signed messages is <span class="command"><strong>nsupdate</strong></span>. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="DNSSEC"></a>DNSSEC</h2></div></div></div> + <p> + Cryptographic authentication of DNS information is possible + through the DNS Security (<span class="emphasis"><em>DNSSEC-bis</em></span>) extensions, + defined in RFC 4033, RFC 4034, and RFC 4035. + This section describes the creation and use of DNSSEC signed zones. + </p> + + <p> + In order to set up a DNSSEC secure zone, there are a series + of steps which must be followed. <acronym class="acronym">BIND</acronym> + 9 ships + with several tools + that are used in this process, which are explained in more detail + below. In all cases, the <code class="option">-h</code> option prints a + full list of parameters. Note that the DNSSEC tools require the + keyset files to be in the working directory or the + directory specified by the <code class="option">-d</code> option, and + that the tools shipped with BIND 9.2.x and earlier are not compatible + with the current ones. + </p> + + <p> + There must also be communication with the administrators of + the parent and/or child zone to transmit keys. A zone's security + status must be indicated by the parent zone for a DNSSEC capable + resolver to trust its data. This is done through the presence + or absence of a <code class="literal">DS</code> record at the + delegation + point. + </p> + + <p> + For other servers to trust data in this zone, they must + either be statically configured with this zone's zone key or the + zone key of another zone above this one in the DNS tree. + </p> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="dnssec_keys"></a>Generating Keys</h3></div></div></div> + + <p> + The <span class="command"><strong>dnssec-keygen</strong></span> program is used to + generate keys. + </p> + + <p> + A secure zone must contain one or more zone keys. The + zone keys will sign all other records in the zone, as well as + the zone keys of any secure delegated zones. Zone keys must + have the same name as the zone, a name type of + <span class="command"><strong>ZONE</strong></span>, and must be usable for + authentication. + It is recommended that zone keys use a cryptographic algorithm + designated as "mandatory to implement" by the IETF; currently + the only one is RSASHA1. + </p> + + <p> + The following command will generate a 768-bit RSASHA1 key for + the <code class="filename">child.example</code> zone: + </p> + + <p> + <strong class="userinput"><code>dnssec-keygen -a RSASHA1 -b 768 -n ZONE child.example.</code></strong> + </p> + + <p> + Two output files will be produced: + <code class="filename">Kchild.example.+005+12345.key</code> and + <code class="filename">Kchild.example.+005+12345.private</code> + (where + 12345 is an example of a key tag). The key filenames contain + the key name (<code class="filename">child.example.</code>), + algorithm (3 + is DSA, 1 is RSAMD5, 5 is RSASHA1, etc.), and the key tag (12345 in + this case). + The private key (in the <code class="filename">.private</code> + file) is + used to generate signatures, and the public key (in the + <code class="filename">.key</code> file) is used for signature + verification. + </p> + + <p> + To generate another key with the same properties (but with + a different key tag), repeat the above command. + </p> + + <p> + The <span class="command"><strong>dnssec-keyfromlabel</strong></span> program is used + to get a key pair from a crypto hardware and build the key + files. Its usage is similar to <span class="command"><strong>dnssec-keygen</strong></span>. + </p> + + <p> + The public keys should be inserted into the zone file by + including the <code class="filename">.key</code> files using + <span class="command"><strong>$INCLUDE</strong></span> statements. + </p> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="dnssec_signing"></a>Signing the Zone</h3></div></div></div> + + <p> + The <span class="command"><strong>dnssec-signzone</strong></span> program is used + to sign a zone. + </p> + + <p> + Any <code class="filename">keyset</code> files corresponding to + secure subzones should be present. The zone signer will + generate <code class="literal">NSEC</code>, <code class="literal">NSEC3</code> + and <code class="literal">RRSIG</code> records for the zone, as + well as <code class="literal">DS</code> for the child zones if + <code class="literal">'-g'</code> is specified. If <code class="literal">'-g'</code> + is not specified, then DS RRsets for the secure child + zones need to be added manually. + </p> + + <p> + The following command signs the zone, assuming it is in a + file called <code class="filename">zone.child.example</code>. By + default, all zone keys which have an available private key are + used to generate signatures. + </p> + + <p> + <strong class="userinput"><code>dnssec-signzone -o child.example zone.child.example</code></strong> + </p> + + <p> + One output file is produced: + <code class="filename">zone.child.example.signed</code>. This + file + should be referenced by <code class="filename">named.conf</code> + as the + input file for the zone. + </p> + + <p><span class="command"><strong>dnssec-signzone</strong></span> + will also produce a keyset and dsset files and optionally a + dlvset file. These are used to provide the parent zone + administrators with the <code class="literal">DNSKEYs</code> (or their + corresponding <code class="literal">DS</code> records) that are the + secure entry point to the zone. + </p> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="dnssec_config"></a>Configuring Servers</h3></div></div></div> + + <p> + To enable <span class="command"><strong>named</strong></span> to respond appropriately + to DNS requests from DNSSEC aware clients, + <span class="command"><strong>dnssec-enable</strong></span> must be set to yes. + (This is the default setting.) + </p> + + <p> + To enable <span class="command"><strong>named</strong></span> to validate answers from + other servers, the <span class="command"><strong>dnssec-enable</strong></span> option + must be set to <strong class="userinput"><code>yes</code></strong>, and the + <span class="command"><strong>dnssec-validation</strong></span> options must be set to + <strong class="userinput"><code>yes</code></strong> or <strong class="userinput"><code>auto</code></strong>. + </p> + + <p> + If <span class="command"><strong>dnssec-validation</strong></span> is set to + <strong class="userinput"><code>auto</code></strong>, then a default + trust anchor for the DNS root zone will be used. + If it is set to <strong class="userinput"><code>yes</code></strong>, however, + then at least one trust anchor must be configured + with a <span class="command"><strong>trusted-keys</strong></span> or + <span class="command"><strong>managed-keys</strong></span> statement in + <code class="filename">named.conf</code>, or DNSSEC validation + will not occur. The default setting is + <strong class="userinput"><code>yes</code></strong>. + </p> + + <p> + <span class="command"><strong>trusted-keys</strong></span> are copies of DNSKEY RRs + for zones that are used to form the first link in the + cryptographic chain of trust. All keys listed in + <span class="command"><strong>trusted-keys</strong></span> (and corresponding zones) + are deemed to exist and only the listed keys will be used + to validated the DNSKEY RRset that they are from. + </p> + + <p> + <span class="command"><strong>managed-keys</strong></span> are trusted keys which are + automatically kept up to date via RFC 5011 trust anchor + maintenance. + </p> + + <p> + <span class="command"><strong>trusted-keys</strong></span> and + <span class="command"><strong>managed-keys</strong></span> are described in more detail + later in this document. + </p> + + <p> + Unlike <acronym class="acronym">BIND</acronym> 8, <acronym class="acronym">BIND</acronym> + 9 does not verify signatures on load, so zone keys for + authoritative zones do not need to be specified in the + configuration file. + </p> + + <p> + After DNSSEC gets established, a typical DNSSEC configuration + will look something like the following. It has one or + more public keys for the root. This allows answers from + outside the organization to be validated. It will also + have several keys for parts of the namespace the organization + controls. These are here to ensure that <span class="command"><strong>named</strong></span> + is immune to compromises in the DNSSEC components of the security + of parent zones. + </p> + +<pre class="programlisting"> +managed-keys { + /* Root Key */ + "." initial-key 257 3 3 "BNY4wrWM1nCfJ+CXd0rVXyYmobt7sEEfK3clRbGaTwS + JxrGkxJWoZu6I7PzJu/E9gx4UC1zGAHlXKdE4zYIpRh + aBKnvcC2U9mZhkdUpd1Vso/HAdjNe8LmMlnzY3zy2Xy + 4klWOADTPzSv9eamj8V18PHGjBLaVtYvk/ln5ZApjYg + hf+6fElrmLkdaz MQ2OCnACR817DF4BBa7UR/beDHyp + 5iWTXWSi6XmoJLbG9Scqc7l70KDqlvXR3M/lUUVRbke + g1IPJSidmK3ZyCllh4XSKbje/45SKucHgnwU5jefMtq + 66gKodQj+MiA21AfUVe7u99WzTLzY3qlxDhxYQQ20FQ + 97S+LKUTpQcq27R7AT3/V5hRQxScINqwcz4jYqZD2fQ + dgxbcDTClU0CRBdiieyLMNzXG3"; +}; + +trusted-keys { + /* Key for our organization's forward zone */ + example.com. 257 3 5 "AwEAAaxPMcR2x0HbQV4WeZB6oEDX+r0QM6 + 5KbhTjrW1ZaARmPhEZZe3Y9ifgEuq7vZ/z + GZUdEGNWy+JZzus0lUptwgjGwhUS1558Hb + 4JKUbbOTcM8pwXlj0EiX3oDFVmjHO444gL + kBOUKUf/mC7HvfwYH/Be22GnClrinKJp1O + g4ywzO9WglMk7jbfW33gUKvirTHr25GL7S + TQUzBb5Usxt8lgnyTUHs1t3JwCY5hKZ6Cq + FxmAVZP20igTixin/1LcrgX/KMEGd/biuv + F4qJCyduieHukuY3H4XMAcR+xia2nIUPvm + /oyWR8BW/hWdzOvnSCThlHf3xiYleDbt/o + 1OTQ09A0="; + + /* Key for our reverse zone. */ + 2.0.192.IN-ADDRPA.NET. 257 3 5 "AQOnS4xn/IgOUpBPJ3bogzwc + xOdNax071L18QqZnQQQAVVr+i + LhGTnNGp3HoWQLUIzKrJVZ3zg + gy3WwNT6kZo6c0tszYqbtvchm + gQC8CzKojM/W16i6MG/eafGU3 + siaOdS0yOI6BgPsw+YZdzlYMa + IJGf4M4dyoKIhzdZyQ2bYQrjy + Q4LB0lC7aOnsMyYKHHYeRvPxj + IQXmdqgOJGq+vsevG06zW+1xg + YJh9rCIfnm1GX/KMgxLPG2vXT + D/RnLX+D3T3UL7HJYHJhAZD5L + 59VvjSPsZJHeDCUyWYrvPZesZ + DIRvhDD52SKvbheeTJUm6Ehkz + ytNN2SN96QRk8j/iI8ib"; +}; + +options { + ... + dnssec-enable yes; + dnssec-validation yes; +}; +</pre> + + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> +<p> + None of the keys listed in this example are valid. In particular, + the root key is not valid. + </p> +</div> + + <p> + When DNSSEC validation is enabled and properly configured, + the resolver will reject any answers from signed, secure zones + which fail to validate, and will return SERVFAIL to the client. + </p> + + <p> + Responses may fail to validate for any of several reasons, + including missing, expired, or invalid signatures, a key which + does not match the DS RRset in the parent zone, or an insecure + response from a zone which, according to its parent, should have + been secure. + </p> + + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + When the validator receives a response from an unsigned zone + that has a signed parent, it must confirm with the parent + that the zone was intentionally left unsigned. It does + this by verifying, via signed and validated NSEC/NSEC3 records, + that the parent zone contains no DS records for the child. + </p> + <p> + If the validator <span class="emphasis"><em>can</em></span> prove that the zone + is insecure, then the response is accepted. However, if it + cannot, then it must assume an insecure response to be a + forgery; it rejects the response and logs an error. + </p> + <p> + The logged error reads "insecurity proof failed" and + "got insecure response; parent indicates it should be secure". + </p> + </div> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="dnssec.dynamic.zones"></a>DNSSEC, Dynamic Zones, and Automatic Signing</h2></div></div></div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.10.2"></a>Converting from insecure to secure</h3></div></div></div> + + </div> + <p>Changing a zone from insecure to secure can be done in two + ways: using a dynamic DNS update, or the + <span class="command"><strong>auto-dnssec</strong></span> zone option.</p> + <p>For either method, you need to configure + <span class="command"><strong>named</strong></span> so that it can see the + <code class="filename">K*</code> files which contain the public and private + parts of the keys that will be used to sign the zone. These files + will have been generated by + <span class="command"><strong>dnssec-keygen</strong></span>. You can do this by placing them + in the key-directory, as specified in + <code class="filename">named.conf</code>:</p> + <pre class="programlisting"> + zone example.net { + type master; + update-policy local; + file "dynamic/example.net/example.net"; + key-directory "dynamic/example.net"; + }; +</pre> + <p>If one KSK and one ZSK DNSKEY key have been generated, this + configuration will cause all records in the zone to be signed + with the ZSK, and the DNSKEY RRset to be signed with the KSK as + well. An NSEC chain will be generated as part of the initial + signing process.</p> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.10.7"></a>Dynamic DNS update method</h3></div></div></div> + + </div> + <p>To insert the keys via dynamic update:</p> + <pre class="screen"> + % nsupdate + > ttl 3600 + > update add example.net DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8= + > update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk= + > send +</pre> + <p>While the update request will complete almost immediately, + the zone will not be completely signed until + <span class="command"><strong>named</strong></span> has had time to walk the zone and + generate the NSEC and RRSIG records. The NSEC record at the apex + will be added last, to signal that there is a complete NSEC + chain.</p> + <p>If you wish to sign using NSEC3 instead of NSEC, you should + add an NSEC3PARAM record to the initial update request. If you + wish the NSEC3 chain to have the OPTOUT bit set, set it in the + flags field of the NSEC3PARAM record.</p> + <pre class="screen"> + % nsupdate + > ttl 3600 + > update add example.net DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8= + > update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk= + > update add example.net NSEC3PARAM 1 1 100 1234567890 + > send +</pre> + <p>Again, this update request will complete almost + immediately; however, the record won't show up until + <span class="command"><strong>named</strong></span> has had a chance to build/remove the + relevant chain. A private type record will be created to record + the state of the operation (see below for more details), and will + be removed once the operation completes.</p> + <p>While the initial signing and NSEC/NSEC3 chain generation + is happening, other updates are possible as well.</p> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.10.15"></a>Fully automatic zone signing</h3></div></div></div> + + </div> + <p>To enable automatic signing, add the + <span class="command"><strong>auto-dnssec</strong></span> option to the zone statement in + <code class="filename">named.conf</code>. + <span class="command"><strong>auto-dnssec</strong></span> has two possible arguments: + <code class="constant">allow</code> or + <code class="constant">maintain</code>.</p> + <p>With + <span class="command"><strong>auto-dnssec allow</strong></span>, + <span class="command"><strong>named</strong></span> can search the key directory for keys + matching the zone, insert them into the zone, and use them to + sign the zone. It will do so only when it receives an + <span class="command"><strong>rndc sign <zonename></strong></span>.</p> + <p> + + <span class="command"><strong>auto-dnssec maintain</strong></span> includes the above + functionality, but will also automatically adjust the zone's + DNSKEY records on schedule according to the keys' timing metadata. + (See <a class="xref" href="man.dnssec-keygen.html" title="dnssec-keygen"><span class="refentrytitle"><span class="application">dnssec-keygen</span></span>(8)</a> and + <a class="xref" href="man.dnssec-settime.html" title="dnssec-settime"><span class="refentrytitle"><span class="application">dnssec-settime</span></span>(8)</a> for more information.) + </p> + <p> + <span class="command"><strong>named</strong></span> will periodically search the key directory + for keys matching the zone, and if the keys' metadata indicates + that any change should be made the zone, such as adding, removing, + or revoking a key, then that action will be carried out. By default, + the key directory is checked for changes every 60 minutes; this period + can be adjusted with the <code class="option">dnssec-loadkeys-interval</code>, up + to a maximum of 24 hours. The <span class="command"><strong>rndc loadkeys</strong></span> forces + <span class="command"><strong>named</strong></span> to check for key updates immediately. + </p> + <p> + If keys are present in the key directory the first time the zone + is loaded, the zone will be signed immediately, without waiting for an + <span class="command"><strong>rndc sign</strong></span> or <span class="command"><strong>rndc loadkeys</strong></span> + command. (Those commands can still be used when there are unscheduled + key changes, however.) + </p> + <p> + When new keys are added to a zone, the TTL is set to match that + of any existing DNSKEY RRset. If there is no existing DNSKEY RRset, + then the TTL will be set to the TTL specified when the key was + created (using the <span class="command"><strong>dnssec-keygen -L</strong></span> option), if + any, or to the SOA TTL. + </p> + <p> + If you wish the zone to be signed using NSEC3 instead of NSEC, + submit an NSEC3PARAM record via dynamic update prior to the + scheduled publication and activation of the keys. If you wish the + NSEC3 chain to have the OPTOUT bit set, set it in the flags field + of the NSEC3PARAM record. The NSEC3PARAM record will not appear in + the zone immediately, but it will be stored for later reference. When + the zone is signed and the NSEC3 chain is completed, the NSEC3PARAM + record will appear in the zone. + </p> + <p>Using the + <span class="command"><strong>auto-dnssec</strong></span> option requires the zone to be + configured to allow dynamic updates, by adding an + <span class="command"><strong>allow-update</strong></span> or + <span class="command"><strong>update-policy</strong></span> statement to the zone + configuration. If this has not been done, the configuration will + fail.</p> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.10.24"></a>Private-type records</h3></div></div></div> + + </div> + <p>The state of the signing process is signaled by + private-type records (with a default type value of 65534). When + signing is complete, these records will have a nonzero value for + the final octet (for those records which have a nonzero initial + octet).</p> + <p>The private type record format: If the first octet is + non-zero then the record indicates that the zone needs to be + signed with the key matching the record, or that all signatures + that match the record should be removed.</p> + <p> + </p> +<div class="literallayout"><p><br> +<br> + algorithm (octet 1)<br> + key id in network order (octet 2 and 3)<br> + removal flag (octet 4)<br> + complete flag (octet 5)<br> +</p></div> +<p> + </p> + <p>Only records flagged as "complete" can be removed via + dynamic update. Attempts to remove other private type records + will be silently ignored.</p> + <p>If the first octet is zero (this is a reserved algorithm + number that should never appear in a DNSKEY record) then the + record indicates changes to the NSEC3 chains are in progress. The + rest of the record contains an NSEC3PARAM record. The flag field + tells what operation to perform based on the flag bits.</p> + <p> + </p> +<div class="literallayout"><p><br> +<br> + 0x01 OPTOUT<br> + 0x80 CREATE<br> + 0x40 REMOVE<br> + 0x20 NONSEC<br> +</p></div> +<p> + </p> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.10.31"></a>DNSKEY rollovers</h3></div></div></div> + + </div> + <p>As with insecure-to-secure conversions, rolling DNSSEC + keys can be done in two ways: using a dynamic DNS update, or the + <span class="command"><strong>auto-dnssec</strong></span> zone option.</p> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.10.33"></a>Dynamic DNS update method</h3></div></div></div> + + </div> + <p> To perform key rollovers via dynamic update, you need to add + the <code class="filename">K*</code> files for the new keys so that + <span class="command"><strong>named</strong></span> can find them. You can then add the new + DNSKEY RRs via dynamic update. + <span class="command"><strong>named</strong></span> will then cause the zone to be signed + with the new keys. When the signing is complete the private type + records will be updated so that the last octet is non + zero.</p> + <p>If this is for a KSK you need to inform the parent and any + trust anchor repositories of the new KSK.</p> + <p>You should then wait for the maximum TTL in the zone before + removing the old DNSKEY. If it is a KSK that is being updated, + you also need to wait for the DS RRset in the parent to be + updated and its TTL to expire. This ensures that all clients will + be able to verify at least one signature when you remove the old + DNSKEY.</p> + <p>The old DNSKEY can be removed via UPDATE. Take care to + specify the correct key. + <span class="command"><strong>named</strong></span> will clean out any signatures generated + by the old key after the update completes.</p> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.10.38"></a>Automatic key rollovers</h3></div></div></div> + + </div> + <p>When a new key reaches its activation date (as set by + <span class="command"><strong>dnssec-keygen</strong></span> or <span class="command"><strong>dnssec-settime</strong></span>), + if the <span class="command"><strong>auto-dnssec</strong></span> zone option is set to + <code class="constant">maintain</code>, <span class="command"><strong>named</strong></span> will + automatically carry out the key rollover. If the key's algorithm + has not previously been used to sign the zone, then the zone will + be fully signed as quickly as possible. However, if the new key + is replacing an existing key of the same algorithm, then the + zone will be re-signed incrementally, with signatures from the + old key being replaced with signatures from the new key as their + signature validity periods expire. By default, this rollover + completes in 30 days, after which it will be safe to remove the + old key from the DNSKEY RRset.</p> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.10.40"></a>NSEC3PARAM rollovers via UPDATE</h3></div></div></div> + + </div> + <p>Add the new NSEC3PARAM record via dynamic update. When the + new NSEC3 chain has been generated, the NSEC3PARAM flag field + will be zero. At this point you can remove the old NSEC3PARAM + record. The old chain will be removed after the update request + completes.</p> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.10.42"></a>Converting from NSEC to NSEC3</h3></div></div></div> + + </div> + <p>To do this, you just need to add an NSEC3PARAM record. When + the conversion is complete, the NSEC chain will have been removed + and the NSEC3PARAM record will have a zero flag field. The NSEC3 + chain will be generated before the NSEC chain is + destroyed.</p> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.10.44"></a>Converting from NSEC3 to NSEC</h3></div></div></div> + + </div> + <p>To do this, use <span class="command"><strong>nsupdate</strong></span> to + remove all NSEC3PARAM records with a zero flag + field. The NSEC chain will be generated before the NSEC3 chain is + removed.</p> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.10.46"></a>Converting from secure to insecure</h3></div></div></div> + + </div> + <p>To convert a signed zone to unsigned using dynamic DNS, + delete all the DNSKEY records from the zone apex using + <span class="command"><strong>nsupdate</strong></span>. All signatures, NSEC or NSEC3 chains, + and associated NSEC3PARAM records will be removed automatically. + This will take place after the update request completes.</p> + <p> This requires the + <span class="command"><strong>dnssec-secure-to-insecure</strong></span> option to be set to + <strong class="userinput"><code>yes</code></strong> in + <code class="filename">named.conf</code>.</p> + <p>In addition, if the <span class="command"><strong>auto-dnssec maintain</strong></span> + zone statement is used, it should be removed or changed to + <span class="command"><strong>allow</strong></span> instead (or it will re-sign). + </p> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.10.50"></a>Periodic re-signing</h3></div></div></div> + + </div> + <p>In any secure zone which supports dynamic updates, <span class="command"><strong>named</strong></span> + will periodically re-sign RRsets which have not been re-signed as + a result of some update action. The signature lifetimes will be + adjusted so as to spread the re-sign load over time rather than + all at once.</p> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.10.52"></a>NSEC3 and OPTOUT</h3></div></div></div> + + </div> + <p> + <span class="command"><strong>named</strong></span> only supports creating new NSEC3 chains + where all the NSEC3 records in the zone have the same OPTOUT + state. + <span class="command"><strong>named</strong></span> supports UPDATES to zones where the NSEC3 + records in the chain have mixed OPTOUT state. + <span class="command"><strong>named</strong></span> does not support changing the OPTOUT + state of an individual NSEC3 record, the entire chain needs to be + changed if the OPTOUT state of an individual NSEC3 needs to be + changed.</p> +</div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="rfc5011.support"></a>Dynamic Trust Anchor Management</h2></div></div></div> + + <p> + BIND is able to maintain DNSSEC trust anchors using RFC 5011 key + management. This feature allows <span class="command"><strong>named</strong></span> to keep track + of changes to critical DNSSEC keys without any need for the operator to + make changes to configuration files. + </p> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.11.3"></a>Validating Resolver</h3></div></div></div> + + + <p>To configure a validating resolver to use RFC 5011 to + maintain a trust anchor, configure the trust anchor using a + <span class="command"><strong>managed-keys</strong></span> statement. Information about + this can be found in + <a class="xref" href="Bv9ARM.ch06.html#managed-keys" title="managed-keys Statement Definition and Usage">the section called “<span class="command"><strong>managed-keys</strong></span> Statement Definition + and Usage”</a>.</p> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.11.4"></a>Authoritative Server</h3></div></div></div> + + <p>To set up an authoritative zone for RFC 5011 trust anchor + maintenance, generate two (or more) key signing keys (KSKs) for + the zone. Sign the zone with one of them; this is the "active" + KSK. All KSKs which do not sign the zone are "stand-by" + keys.</p> + <p>Any validating resolver which is configured to use the + active KSK as an RFC 5011-managed trust anchor will take note + of the stand-by KSKs in the zone's DNSKEY RRset, and store them + for future reference. The resolver will recheck the zone + periodically, and after 30 days, if the new key is still there, + then the key will be accepted by the resolver as a valid trust + anchor for the zone. Any time after this 30-day acceptance + timer has completed, the active KSK can be revoked, and the + zone can be "rolled over" to the newly accepted key.</p> + <p>The easiest way to place a stand-by key in a zone is to + use the "smart signing" features of + <span class="command"><strong>dnssec-keygen</strong></span> and + <span class="command"><strong>dnssec-signzone</strong></span>. If a key with a publication + date in the past, but an activation date which is unset or in + the future, " + <span class="command"><strong>dnssec-signzone -S</strong></span>" will include the DNSKEY + record in the zone, but will not sign with it:</p> + <pre class="screen"> +$ <strong class="userinput"><code>dnssec-keygen -K keys -f KSK -P now -A now+2y example.net</code></strong> +$ <strong class="userinput"><code>dnssec-signzone -S -K keys example.net</code></strong> +</pre> + <p>To revoke a key, the new command + <span class="command"><strong>dnssec-revoke</strong></span> has been added. This adds the + REVOKED bit to the key flags and re-generates the + <code class="filename">K*.key</code> and + <code class="filename">K*.private</code> files.</p> + <p>After revoking the active key, the zone must be signed + with both the revoked KSK and the new active KSK. (Smart + signing takes care of this automatically.)</p> + <p>Once a key has been revoked and used to sign the DNSKEY + RRset in which it appears, that key will never again be + accepted as a valid trust anchor by the resolver. However, + validation can proceed using the new active key (which had been + accepted by the resolver when it was a stand-by key).</p> + <p>See RFC 5011 for more details on key rollover + scenarios.</p> + <p>When a key has been revoked, its key ID changes, + increasing by 128, and wrapping around at 65535. So, for + example, the key "<code class="filename">Kexample.com.+005+10000</code>" becomes + "<code class="filename">Kexample.com.+005+10128</code>".</p> + <p>If two keys have IDs exactly 128 apart, and one is + revoked, then the two key IDs will collide, causing several + problems. To prevent this, + <span class="command"><strong>dnssec-keygen</strong></span> will not generate a new key if + another key is present which may collide. This checking will + only occur if the new keys are written to the same directory + which holds all other keys in use for that zone.</p> + <p>Older versions of BIND 9 did not have this precaution. + Exercise caution if using key revocation on keys that were + generated by previous releases, or if using keys stored in + multiple directories or on multiple machines.</p> + <p>It is expected that a future release of BIND 9 will + address this problem in a different way, by storing revoked + keys with their original unrevoked key IDs.</p> + </div> +</div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="pkcs11"></a>PKCS#11 (Cryptoki) support</h2></div></div></div> + + <p> + PKCS#11 (Public Key Cryptography Standard #11) defines a + platform-independent API for the control of hardware security + modules (HSMs) and other cryptographic support devices. + </p> + <p> + BIND 9 is known to work with three HSMs: The AEP Keyper, which has + been tested with Debian Linux, Solaris x86 and Windows Server 2003; + the Thales nShield, tested with Debian Linux; and the Sun SCA 6000 + cryptographic acceleration board, tested with Solaris x86. In + addition, BIND can be used with all current versions of SoftHSM, + a software-based HSM simulator library produced by the OpenDNSSEC + project. + </p> + <p> + PKCS#11 makes use of a "provider library": a dynamically loadable + library which provides a low-level PKCS#11 interface to drive the HSM + hardware. The PKCS#11 provider library comes from the HSM vendor, and + it is specific to the HSM to be controlled. + </p> + <p> + There are two available mechanisms for PKCS#11 support in BIND 9: + OpenSSL-based PKCS#11 and native PKCS#11. When using the first + mechanism, BIND uses a modified version of OpenSSL, which loads + the provider library and operates the HSM indirectly; any + cryptographic operations not supported by the HSM can be carried + out by OpenSSL instead. The second mechanism enables BIND to bypass + OpenSSL completely; BIND loads the provider library itself, and uses + the PKCS#11 API to drive the HSM directly. + </p> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.12.6"></a>Prerequisites</h3></div></div></div> + + <p> + See the documentation provided by your HSM vendor for + information about installing, initializing, testing and + troubleshooting the HSM. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.12.7"></a>Native PKCS#11</h3></div></div></div> + + <p> + Native PKCS#11 mode will only work with an HSM capable of carrying + out <span class="emphasis"><em>every</em></span> cryptographic operation BIND 9 may + need. The HSM's provider library must have a complete implementation + of the PKCS#11 API, so that all these functions are accessible. As of + this writing, only the Thales nShield HSM and SoftHSMv2 can be used + in this fashion. For other HSMs, including the AEP Keyper, Sun SCA + 6000 and older versions of SoftHSM, use OpenSSL-based PKCS#11. + (Note: Eventually, when more HSMs become capable of supporting + native PKCS#11, it is expected that OpenSSL-based PKCS#11 will + be deprecated.) + </p> + <p> + To build BIND with native PKCS#11, configure as follows: + </p> + <pre class="screen"> +$ <strong class="userinput"><code>cd bind9</code></strong> +$ <strong class="userinput"><code>./configure --enable-native-pkcs11 \ + --with-pkcs11=<em class="replaceable"><code>provider-library-path</code></em></code></strong> + </pre> + <p> + This will cause all BIND tools, including <span class="command"><strong>named</strong></span> + and the <span class="command"><strong>dnssec-*</strong></span> and <span class="command"><strong>pkcs11-*</strong></span> + tools, to use the PKCS#11 provider library specified in + <em class="replaceable"><code>provider-library-path</code></em> for cryptography. + (The provider library path can be overridden using the + <code class="option">-E</code> in <span class="command"><strong>named</strong></span> and the + <span class="command"><strong>dnssec-*</strong></span> tools, or the <code class="option">-m</code> in + the <span class="command"><strong>pkcs11-*</strong></span> tools.) + </p> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.5.12.7.6"></a>Building SoftHSMv2</h4></div></div></div> + + <p> + SoftHSMv2, the latest development version of SoftHSM, is available + from + <a class="link" href="https://github.com/opendnssec/SoftHSMv2" target="_top"> + https://github.com/opendnssec/SoftHSMv2 + </a>. + It is a software library developed by the OpenDNSSEC project + (<a class="link" href="http://www.opendnssec.org" target="_top"> + http://www.opendnssec.org + </a>) + which provides a PKCS#11 interface to a virtual HSM, implemented in + the form of a SQLite3 database on the local filesystem. It provides + less security than a true HSM, but it allows you to experiment with + native PKCS#11 when an HSM is not available. SoftHSMv2 can be + configured to use either OpenSSL or the Botan library to perform + cryptographic functions, but when using it for native PKCS#11 in + BIND, OpenSSL is required. + </p> + <p> + By default, the SoftHSMv2 configuration file is + <em class="replaceable"><code>prefix</code></em>/etc/softhsm2.conf (where + <em class="replaceable"><code>prefix</code></em> is configured at compile time). + This location can be overridden by the SOFTHSM2_CONF environment + variable. The SoftHSMv2 cryptographic store must be installed and + initialized before using it with BIND. + </p> + <pre class="screen"> +$ <strong class="userinput"><code> cd SoftHSMv2 </code></strong> +$ <strong class="userinput"><code> configure --with-crypto-backend=openssl --prefix=/opt/pkcs11/usr --enable-gost </code></strong> +$ <strong class="userinput"><code> make </code></strong> +$ <strong class="userinput"><code> make install </code></strong> +$ <strong class="userinput"><code> /opt/pkcs11/usr/bin/softhsm-util --init-token 0 --slot 0 --label softhsmv2 </code></strong> + </pre> + </div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.12.8"></a>OpenSSL-based PKCS#11</h3></div></div></div> + + <p> + OpenSSL-based PKCS#11 mode uses a modified version of the + OpenSSL library; stock OpenSSL does not fully support PKCS#11. + ISC provides a patch to OpenSSL to correct this. This patch is + based on work originally done by the OpenSolaris project; it has been + modified by ISC to provide new features such as PIN management and + key-by-reference. + </p> + <p> + There are two "flavors" of PKCS#11 support provided by + the patched OpenSSL, one of which must be chosen at + configuration time. The correct choice depends on the HSM + hardware: + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <p> + Use 'crypto-accelerator' with HSMs that have hardware + cryptographic acceleration features, such as the SCA 6000 + board. This causes OpenSSL to run all supported + cryptographic operations in the HSM. + </p> + </li> +<li class="listitem"> + <p> + Use 'sign-only' with HSMs that are designed to + function primarily as secure key storage devices, but lack + hardware acceleration. These devices are highly secure, but + are not necessarily any faster at cryptography than the + system CPU — often, they are slower. It is therefore + most efficient to use them only for those cryptographic + functions that require access to the secured private key, + such as zone signing, and to use the system CPU for all + other computationally-intensive operations. The AEP Keyper + is an example of such a device. + </p> + </li> +</ul></div> + <p> + The modified OpenSSL code is included in the BIND 9 release, + in the form of a context diff against the latest versions of + OpenSSL. OpenSSL 0.9.8, 1.0.0, 1.0.1 and 1.0.2 are supported; + there are separate diffs for each version. In the examples to + follow, we use OpenSSL 0.9.8, but the same methods work with + OpenSSL 1.0.0 through 1.0.2. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> +<p> + The OpenSSL patches as of this writing (January 2016) + support versions 0.9.8zh, 1.0.0t, 1.0.1q and 1.0.2f. + ISC will provide updated patches as new versions of OpenSSL + are released. The version number in the following examples + is expected to change. + </p> +</div> + <p> + Before building BIND 9 with PKCS#11 support, it will be + necessary to build OpenSSL with the patch in place, and configure + it with the path to your HSM's PKCS#11 provider library. + </p> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.5.12.8.8"></a>Patching OpenSSL</h4></div></div></div> + + <pre class="screen"> +$ <strong class="userinput"><code>wget <a class="link" href="" target="_top">http://www.openssl.org/source/openssl-0.9.8zc.tar.gz</a></code></strong> + </pre> + <p>Extract the tarball:</p> + <pre class="screen"> +$ <strong class="userinput"><code>tar zxf openssl-0.9.8zc.tar.gz</code></strong> +</pre> + <p>Apply the patch from the BIND 9 release:</p> + <pre class="screen"> +$ <strong class="userinput"><code>patch -p1 -d openssl-0.9.8zc \ + < bind9/bin/pkcs11/openssl-0.9.8zc-patch</code></strong> +</pre> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> +<p> + The patch file may not be compatible with the + "patch" utility on all operating systems. You may need to + install GNU patch. + </p> +</div> + <p> + When building OpenSSL, place it in a non-standard + location so that it does not interfere with OpenSSL libraries + elsewhere on the system. In the following examples, we choose + to install into "/opt/pkcs11/usr". We will use this location + when we configure BIND 9. + </p> + <p> + Later, when building BIND 9, the location of the custom-built + OpenSSL library will need to be specified via configure. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.5.12.8.9"></a>Building OpenSSL for the AEP Keyper on Linux</h4></div></div></div> + + + <p> + The AEP Keyper is a highly secure key storage device, + but does not provide hardware cryptographic acceleration. It + can carry out cryptographic operations, but it is probably + slower than your system's CPU. Therefore, we choose the + 'sign-only' flavor when building OpenSSL. + </p> + <p> + The Keyper-specific PKCS#11 provider library is + delivered with the Keyper software. In this example, we place + it /opt/pkcs11/usr/lib: + </p> + <pre class="screen"> +$ <strong class="userinput"><code>cp pkcs11.GCC4.0.2.so.4.05 /opt/pkcs11/usr/lib/libpkcs11.so</code></strong> +</pre> + <p> + The Keyper library requires threads, so we + must specify -pthread. + </p> + <pre class="screen"> +$ <strong class="userinput"><code>cd openssl-0.9.8zc</code></strong> +$ <strong class="userinput"><code>./Configure linux-x86_64 -pthread \ + --pk11-libname=/opt/pkcs11/usr/lib/libpkcs11.so \ + --pk11-flavor=sign-only \ + --prefix=/opt/pkcs11/usr</code></strong> +</pre> + <p> + After configuring, run "<span class="command"><strong>make</strong></span>" + and "<span class="command"><strong>make test</strong></span>". If "<span class="command"><strong>make + test</strong></span>" fails with "pthread_atfork() not found", you forgot to + add the -pthread above. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.5.12.8.10"></a>Building OpenSSL for the SCA 6000 on Solaris</h4></div></div></div> + + + <p> + The SCA-6000 PKCS#11 provider is installed as a system + library, libpkcs11. It is a true crypto accelerator, up to 4 + times faster than any CPU, so the flavor shall be + 'crypto-accelerator'. + </p> + <p> + In this example, we are building on Solaris x86 on an + AMD64 system. + </p> + <pre class="screen"> +$ <strong class="userinput"><code>cd openssl-0.9.8zc</code></strong> +$ <strong class="userinput"><code>./Configure solaris64-x86_64-cc \ + --pk11-libname=/usr/lib/64/libpkcs11.so \ + --pk11-flavor=crypto-accelerator \ + --prefix=/opt/pkcs11/usr</code></strong> +</pre> + <p> + (For a 32-bit build, use "solaris-x86-cc" and /usr/lib/libpkcs11.so.) + </p> + <p> + After configuring, run + <span class="command"><strong>make</strong></span> and + <span class="command"><strong>make test</strong></span>. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.5.12.8.11"></a>Building OpenSSL for SoftHSM</h4></div></div></div> + + + <p> + SoftHSM (version 1) is a software library developed by the + OpenDNSSEC project + (<a class="link" href="http://www.opendnssec.org" target="_top"> + http://www.opendnssec.org + </a>) + which provides a + PKCS#11 interface to a virtual HSM, implemented in the form of + a SQLite3 database on the local filesystem. SoftHSM uses + the Botan library to perform cryptographic functions. Though + less secure than a true HSM, it can allow you to experiment + with PKCS#11 when an HSM is not available. + </p> + <p> + The SoftHSM cryptographic store must be installed and + initialized before using it with OpenSSL, and the SOFTHSM_CONF + environment variable must always point to the SoftHSM configuration + file: + </p> + <pre class="screen"> +$ <strong class="userinput"><code> cd softhsm-1.3.7 </code></strong> +$ <strong class="userinput"><code> configure --prefix=/opt/pkcs11/usr </code></strong> +$ <strong class="userinput"><code> make </code></strong> +$ <strong class="userinput"><code> make install </code></strong> +$ <strong class="userinput"><code> export SOFTHSM_CONF=/opt/pkcs11/softhsm.conf </code></strong> +$ <strong class="userinput"><code> echo "0:/opt/pkcs11/softhsm.db" > $SOFTHSM_CONF </code></strong> +$ <strong class="userinput"><code> /opt/pkcs11/usr/bin/softhsm --init-token 0 --slot 0 --label softhsm </code></strong> +</pre> + <p> + SoftHSM can perform all cryptographic operations, but + since it only uses your system CPU, there is no advantage to using + it for anything but signing. Therefore, we choose the 'sign-only' + flavor when building OpenSSL. + </p> + <pre class="screen"> +$ <strong class="userinput"><code>cd openssl-0.9.8zc</code></strong> +$ <strong class="userinput"><code>./Configure linux-x86_64 -pthread \ + --pk11-libname=/opt/pkcs11/usr/lib/libsofthsm.so \ + --pk11-flavor=sign-only \ + --prefix=/opt/pkcs11/usr</code></strong> +</pre> + <p> + After configuring, run "<span class="command"><strong>make</strong></span>" + and "<span class="command"><strong>make test</strong></span>". + </p> + </div> + <p> + Once you have built OpenSSL, run + "<span class="command"><strong>apps/openssl engine pkcs11</strong></span>" to confirm + that PKCS#11 support was compiled in correctly. The output + should be one of the following lines, depending on the flavor + selected: + </p> + <pre class="screen"> + (pkcs11) PKCS #11 engine support (sign only) +</pre> + <p>Or:</p> + <pre class="screen"> + (pkcs11) PKCS #11 engine support (crypto accelerator) +</pre> + <p> + Next, run + "<span class="command"><strong>apps/openssl engine pkcs11 -t</strong></span>". This will + attempt to initialize the PKCS#11 engine. If it is able to + do so successfully, it will report + <span class="quote">“<span class="quote"><code class="literal">[ available ]</code></span>”</span>. + </p> + <p> + If the output is correct, run + "<span class="command"><strong>make install</strong></span>" which will install the + modified OpenSSL suite to <code class="filename">/opt/pkcs11/usr</code>. + </p> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.5.12.8.18"></a>Configuring BIND 9 for Linux with the AEP Keyper</h4></div></div></div> + + + <p> + To link with the PKCS#11 provider, threads must be + enabled in the BIND 9 build. + </p> + <pre class="screen"> +$ <strong class="userinput"><code>cd ../bind9</code></strong> +$ <strong class="userinput"><code>./configure --enable-threads \ + --with-openssl=/opt/pkcs11/usr \ + --with-pkcs11=/opt/pkcs11/usr/lib/libpkcs11.so</code></strong> +</pre> + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.5.12.8.19"></a>Configuring BIND 9 for Solaris with the SCA 6000</h4></div></div></div> + + + <p> + To link with the PKCS#11 provider, threads must be + enabled in the BIND 9 build. + </p> + <pre class="screen"> +$ <strong class="userinput"><code>cd ../bind9</code></strong> +$ <strong class="userinput"><code>./configure CC="cc -xarch=amd64" --enable-threads \ + --with-openssl=/opt/pkcs11/usr \ + --with-pkcs11=/usr/lib/64/libpkcs11.so</code></strong> +</pre> + <p>(For a 32-bit build, omit CC="cc -xarch=amd64".)</p> + <p> + If configure complains about OpenSSL not working, you + may have a 32/64-bit architecture mismatch. Or, you may have + incorrectly specified the path to OpenSSL (it should be the + same as the --prefix argument to the OpenSSL + Configure). + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.5.12.8.20"></a>Configuring BIND 9 for SoftHSM</h4></div></div></div> + + + <pre class="screen"> +$ <strong class="userinput"><code>cd ../bind9</code></strong> +$ <strong class="userinput"><code>./configure --enable-threads \ + --with-openssl=/opt/pkcs11/usr \ + --with-pkcs11=/opt/pkcs11/usr/lib/libsofthsm.so</code></strong> +</pre> + </div> + <p> + After configuring, run + "<span class="command"><strong>make</strong></span>", + "<span class="command"><strong>make test</strong></span>" and + "<span class="command"><strong>make install</strong></span>". + </p> + <p> + (Note: If "make test" fails in the "pkcs11" system test, you may + have forgotten to set the SOFTHSM_CONF environment variable.) + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.12.9"></a>PKCS#11 Tools</h3></div></div></div> + + <p> + BIND 9 includes a minimal set of tools to operate the + HSM, including + <span class="command"><strong>pkcs11-keygen</strong></span> to generate a new key pair + within the HSM, + <span class="command"><strong>pkcs11-list</strong></span> to list objects currently + available, + <span class="command"><strong>pkcs11-destroy</strong></span> to remove objects, and + <span class="command"><strong>pkcs11-tokens</strong></span> to list available tokens. + </p> + <p> + In UNIX/Linux builds, these tools are built only if BIND + 9 is configured with the --with-pkcs11 option. (Note: If + --with-pkcs11 is set to "yes", rather than to the path of the + PKCS#11 provider, then the tools will be built but the + provider will be left undefined. Use the -m option or the + PKCS11_PROVIDER environment variable to specify the path to the + provider.) + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.12.10"></a>Using the HSM</h3></div></div></div> + + <p> + For OpenSSL-based PKCS#11, we must first set up the runtime + environment so the OpenSSL and PKCS#11 libraries can be loaded: + </p> + <pre class="screen"> +$ <strong class="userinput"><code>export LD_LIBRARY_PATH=/opt/pkcs11/usr/lib:${LD_LIBRARY_PATH}</code></strong> +</pre> + <p> + This causes <span class="command"><strong>named</strong></span> and other binaries to load + the OpenSSL library from <code class="filename">/opt/pkcs11/usr/lib</code> + rather than from the default location. This step is not necessary + when using native PKCS#11. + </p> + <p> + Some HSMs require other environment variables to be set. + For example, when operating an AEP Keyper, it is necessary to + specify the location of the "machine" file, which stores + information about the Keyper for use by the provider + library. If the machine file is in + <code class="filename">/opt/Keyper/PKCS11Provider/machine</code>, + use: + </p> + <pre class="screen"> +$ <strong class="userinput"><code>export KEYPER_LIBRARY_PATH=/opt/Keyper/PKCS11Provider</code></strong> +</pre> + <p> + Such environment variables must be set whenever running + any tool that uses the HSM, including + <span class="command"><strong>pkcs11-keygen</strong></span>, + <span class="command"><strong>pkcs11-list</strong></span>, + <span class="command"><strong>pkcs11-destroy</strong></span>, + <span class="command"><strong>dnssec-keyfromlabel</strong></span>, + <span class="command"><strong>dnssec-signzone</strong></span>, + <span class="command"><strong>dnssec-keygen</strong></span>, and + <span class="command"><strong>named</strong></span>. + </p> + <p> + We can now create and use keys in the HSM. In this case, + we will create a 2048 bit key and give it the label + "sample-ksk": + </p> + <pre class="screen"> +$ <strong class="userinput"><code>pkcs11-keygen -b 2048 -l sample-ksk</code></strong> +</pre> + <p>To confirm that the key exists:</p> + <pre class="screen"> +$ <strong class="userinput"><code>pkcs11-list</code></strong> +Enter PIN: +object[0]: handle 2147483658 class 3 label[8] 'sample-ksk' id[0] +object[1]: handle 2147483657 class 2 label[8] 'sample-ksk' id[0] +</pre> + <p> + Before using this key to sign a zone, we must create a + pair of BIND 9 key files. The "dnssec-keyfromlabel" utility + does this. In this case, we will be using the HSM key + "sample-ksk" as the key-signing key for "example.net": + </p> + <pre class="screen"> +$ <strong class="userinput"><code>dnssec-keyfromlabel -l sample-ksk -f KSK example.net</code></strong> +</pre> + <p> + The resulting K*.key and K*.private files can now be used + to sign the zone. Unlike normal K* files, which contain both + public and private key data, these files will contain only the + public key data, plus an identifier for the private key which + remains stored within the HSM. Signing with the private key takes + place inside the HSM. + </p> + <p> + If you wish to generate a second key in the HSM for use + as a zone-signing key, follow the same procedure above, using a + different keylabel, a smaller key size, and omitting "-f KSK" + from the dnssec-keyfromlabel arguments: + </p> + <p> + (Note: When using OpenSSL-based PKCS#11 the label is an arbitrary + string which identifies the key. With native PKCS#11, the label is + a PKCS#11 URI string which may include other details about the key + and the HSM, including its PIN. See + <a class="xref" href="man.dnssec-keyfromlabel.html" title="dnssec-keyfromlabel"><span class="refentrytitle"><span class="application">dnssec-keyfromlabel</span></span>(8)</a> for details.) + </p> + <pre class="screen"> +$ <strong class="userinput"><code>pkcs11-keygen -b 1024 -l sample-zsk</code></strong> +$ <strong class="userinput"><code>dnssec-keyfromlabel -l sample-zsk example.net</code></strong> +</pre> + <p> + Alternatively, you may prefer to generate a conventional + on-disk key, using dnssec-keygen: + </p> + <pre class="screen"> +$ <strong class="userinput"><code>dnssec-keygen example.net</code></strong> +</pre> + <p> + This provides less security than an HSM key, but since + HSMs can be slow or cumbersome to use for security reasons, it + may be more efficient to reserve HSM keys for use in the less + frequent key-signing operation. The zone-signing key can be + rolled more frequently, if you wish, to compensate for a + reduction in key security. (Note: When using native PKCS#11, + there is no speed advantage to using on-disk keys, as cryptographic + operations will be done by the HSM regardless.) + </p> + <p> + Now you can sign the zone. (Note: If not using the -S + option to <span class="command"><strong>dnssec-signzone</strong></span>, it will be + necessary to add the contents of both <code class="filename">K*.key</code> + files to the zone master file before signing it.) + </p> + <pre class="screen"> +$ <strong class="userinput"><code>dnssec-signzone -S example.net</code></strong> +Enter PIN: +Verifying the zone using the following algorithms: +NSEC3RSASHA1. +Zone signing complete: +Algorithm: NSEC3RSASHA1: ZSKs: 1, KSKs: 1 active, 0 revoked, 0 stand-by +example.net.signed +</pre> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.12.11"></a>Specifying the engine on the command line</h3></div></div></div> + + <p> + When using OpenSSL-based PKCS#11, the "engine" to be used by + OpenSSL can be specified in <span class="command"><strong>named</strong></span> and all of + the BIND <span class="command"><strong>dnssec-*</strong></span> tools by using the "-E + <engine>" command line option. If BIND 9 is built with + the --with-pkcs11 option, this option defaults to "pkcs11". + Specifying the engine will generally not be necessary unless + for some reason you wish to use a different OpenSSL + engine. + </p> + <p> + If you wish to disable use of the "pkcs11" engine — + for troubleshooting purposes, or because the HSM is unavailable + — set the engine to the empty string. For example: + </p> + <pre class="screen"> +$ <strong class="userinput"><code>dnssec-signzone -E '' -S example.net</code></strong> +</pre> + <p> + This causes + <span class="command"><strong>dnssec-signzone</strong></span> to run as if it were compiled + without the --with-pkcs11 option. + </p> + <p> + When built with native PKCS#11 mode, the "engine" option has a + different meaning: it specifies the path to the PKCS#11 provider + library. This may be useful when testing a new provider library. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.12.12"></a>Running named with automatic zone re-signing</h3></div></div></div> + + <p> + If you want <span class="command"><strong>named</strong></span> to dynamically re-sign zones + using HSM keys, and/or to to sign new records inserted via nsupdate, + then <span class="command"><strong>named</strong></span> must have access to the HSM PIN. In OpenSSL-based PKCS#11, + this is accomplished by placing the PIN into the openssl.cnf file + (in the above examples, + <code class="filename">/opt/pkcs11/usr/ssl/openssl.cnf</code>). + </p> + <p> + The location of the openssl.cnf file can be overridden by + setting the OPENSSL_CONF environment variable before running + <span class="command"><strong>named</strong></span>. + </p> + <p>Sample openssl.cnf:</p> + <pre class="programlisting"> + openssl_conf = openssl_def + [ openssl_def ] + engines = engine_section + [ engine_section ] + pkcs11 = pkcs11_section + [ pkcs11_section ] + PIN = <em class="replaceable"><code><PLACE PIN HERE></code></em> +</pre> + <p> + This will also allow the dnssec-* tools to access the HSM + without PIN entry. (The pkcs11-* tools access the HSM directly, + not via OpenSSL, so a PIN will still be required to use + them.) + </p> + <p> + In native PKCS#11 mode, the PIN can be provided in a file specified + as an attribute of the key's label. For example, if a key had the label + <strong class="userinput"><code>pkcs11:object=local-zsk;pin-source=/etc/hsmpin</code></strong>, + then the PIN would be read from the file + <code class="filename">/etc/hsmpin</code>. + </p> + <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Warning</h3> + <p> + Placing the HSM's PIN in a text file in this manner may reduce the + security advantage of using an HSM. Be sure this is what you want to + do before configuring the system in this way. + </p> + </div> + </div> +</div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="dlz-info"></a>DLZ (Dynamically Loadable Zones)</h2></div></div></div> + + <p> + DLZ (Dynamically Loadable Zones) is an extension to BIND 9 that allows + zone data to be retrieved directly from an external database. There is + no required format or schema. DLZ drivers exist for several different + database backends including PostgreSQL, MySQL, and LDAP and can be + written for any other. + </p> + <p> + Historically, DLZ drivers had to be statically linked with the <span class="command"><strong>named</strong></span> + binary and were turned on via a configure option at compile time (for + example, <strong class="userinput"><code>"configure --with-dlz-ldap"</code></strong>). + Currently, the drivers provided in the BIND 9 tarball in + <code class="filename">contrib/dlz/drivers</code> are still linked this + way. + </p> + <p> + In BIND 9.8 and higher, it is possible to link some DLZ modules + dynamically at runtime, via the DLZ "dlopen" driver, which acts as a + generic wrapper around a shared object implementing the DLZ API. The + "dlopen" driver is linked into <span class="command"><strong>named</strong></span> by default, so configure options + are no longer necessary when using these dynamically linkable drivers, + but are still needed for the older drivers in + <code class="filename">contrib/dlz/drivers</code>. + </p> + + <p> + When the DLZ module provides data to <span class="command"><strong>named</strong></span>, it does so in text format. + The response is converted to DNS wire format by <span class="command"><strong>named</strong></span>. This + conversion, and the lack of any internal caching, places significant + limits on the query performance of DLZ modules. Consequently, DLZ is + not recommended for use on high-volume servers. However, it can be + used in a hidden master configuration, with slaves retrieving zone + updates via AXFR. (Note, however, that DLZ has no built-in support for + DNS notify; slaves are not automatically informed of changes to the + zones in the database.) + </p> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.13.6"></a>Configuring DLZ</h3></div></div></div> + + <p> + A DLZ database is configured with a <span class="command"><strong>dlz</strong></span> + statement in <code class="filename">named.conf</code>: + </p> + <pre class="screen"> + dlz example { + database "dlopen driver.so <code class="option">args</code>"; + search yes; + }; + </pre> + <p> + This specifies a DLZ module to search when answering queries; the + module is implemented in <code class="filename">driver.so</code> and is + loaded at runtime by the dlopen DLZ driver. Multiple + <span class="command"><strong>dlz</strong></span> statements can be specified; when + answering a query, all DLZ modules with <code class="option">search</code> + set to <code class="literal">yes</code> will be queried to find out if + they contain an answer for the query name; the best available + answer will be returned to the client. + </p> + <p> + The <code class="option">search</code> option in the above example can be + omitted, because <code class="literal">yes</code> is the default value. + </p> + <p> + If <code class="option">search</code> is set to <code class="literal">no</code>, then + this DLZ module is <span class="emphasis"><em>not</em></span> searched for the best + match when a query is received. Instead, zones in this DLZ must be + separately specified in a zone statement. This allows you to + configure a zone normally using standard zone option semantics, + but specify a different database back-end for storage of the + zone's data. For example, to implement NXDOMAIN redirection using + a DLZ module for back-end storage of redirection rules: + </p> + <pre class="screen"> + dlz other { + database "dlopen driver.so <code class="option">args</code>"; + search no; + }; + + zone "." { + type redirect; + dlz other; + }; + </pre> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.13.7"></a>Sample DLZ Driver</h3></div></div></div> + + <p> + For guidance in implementation of DLZ modules, the directory + <code class="filename">contrib/dlz/example</code> contains a basic + dynamically-linkable DLZ module--i.e., one which can be + loaded at runtime by the "dlopen" DLZ driver. + The example sets up a single zone, whose name is passed + to the module as an argument in the <span class="command"><strong>dlz</strong></span> + statement: + </p> + <pre class="screen"> + dlz other { + database "dlopen driver.so example.nil"; + }; + </pre> + <p> + In the above example, the module is configured to create a zone + "example.nil", which can answer queries and AXFR requests, and + accept DDNS updates. At runtime, prior to any updates, the zone + contains an SOA, NS, and a single A record at the apex: + </p> + <pre class="screen"> + example.nil. 3600 IN SOA example.nil. hostmaster.example.nil. ( + 123 900 600 86400 3600 + ) + example.nil. 3600 IN NS example.nil. + example.nil. 1800 IN A 10.53.0.1 + </pre> + <p> + The sample driver is capable of retrieving information about the + querying client, and altering its response on the basis of this + information. To demonstrate this feature, the example driver + responds to queries for "source-addr.<code class="option">zonename</code>>/TXT" + with the source address of the query. Note, however, that this + record will *not* be included in AXFR or ANY responses. Normally, + this feature would be used to alter responses in some other fashion, + e.g., by providing different address records for a particular name + depending on the network from which the query arrived. + </p> + <p> + Documentation of the DLZ module API can be found in + <code class="filename">contrib/dlz/example/README</code>. This directory also + contains the header file <code class="filename">dlz_minimal.h</code>, which + defines the API and should be included by any dynamically-linkable + DLZ module. + </p> + </div> +</div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="dyndb-info"></a>DynDB (Dynamic Database)</h2></div></div></div> + + <p> + DynDB is an extension to BIND 9 which, like DLZ + (see <a class="xref" href="Bv9ARM.ch04.html#dlz-info" title="DLZ (Dynamically Loadable Zones)">the section called “DLZ (Dynamically Loadable Zones)”</a>), allows zone data to be + retrieved from an external database. Unlike DLZ, a DynDB module + provides a full-featured BIND zone database interface. Where + DLZ translates DNS queries into real-time database lookups, + resulting in relatively poor query performance, and is unable + to handle DNSSEC-signed data due to its limited API, a DynDB + module can pre-load an in-memory database from the external + data source, providing the same performance and functionality + as zones served natively by BIND. + </p> + <p> + A DynDB module supporting LDAP has been created by Red Hat + and is available from + <a class="link" href="https://fedorahosted.org/bind-dyndb-ldap/" target="_top">https://fedorahosted.org/bind-dyndb-ldap/</a>. + </p> + <p> + A sample DynDB module for testing and developer guidance + is included with the BIND source code, in the directory + <code class="filename">bin/tests/system/dyndb/driver</code>. + </p> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.14.5"></a>Configuring DynDB</h3></div></div></div> + + <p> + A DynDB database is configured with a <span class="command"><strong>dyndb</strong></span> + statement in <code class="filename">named.conf</code>: + </p> + <pre class="screen"> + dyndb example "driver.so" { + <em class="replaceable"><code>parameters</code></em> + }; + </pre> + <p> + The file <code class="filename">driver.so</code> is a DynDB module which + implements the full DNS database API. Multiple + <span class="command"><strong>dyndb</strong></span> statements can be specified, to load + different drivers or multiple instances of the same driver. + Zones provided by a DynDB module are added to the view's zone + table, and are treated as normal authoritative zones when BIND + is responding to queries. Zone configuration is handled internally + by the DynDB module. + </p> + <p> + The <em class="replaceable"><code>parameters</code></em> are passed as an opaque + string to the DynDB module's initialization routine. Configuration + syntax will differ depending on the driver. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.14.6"></a>Sample DynDB Module</h3></div></div></div> + + <p> + For guidance in implementation of DynDB modules, the directory + <code class="filename">bin/tests/system/dyndb/driver</code>. + contains a basic DynDB module. + The example sets up two zones, whose names are passed + to the module as arguments in the <span class="command"><strong>dyndb</strong></span> + statement: + </p> + <pre class="screen"> + dyndb sample "sample.so" { example.nil. arpa. }; + </pre> + <p> + In the above example, the module is configured to create a zone + "example.nil", which can answer queries and AXFR requests, and + accept DDNS updates. At runtime, prior to any updates, the zone + contains an SOA, NS, and a single A record at the apex: + </p> + <pre class="screen"> + example.nil. 86400 IN SOA example.nil. example.nil. ( + 0 28800 7200 604800 86400 + ) + example.nil. 86400 IN NS example.nil. + example.nil. 86400 IN A 127.0.0.1 + </pre> + <p> + When the zone is updated dynamically, the DynDB module will determine + whether the updated RR is an address (i.e., type A or AAAA) and if + so, it will automatically update the corresponding PTR record in a + reverse zone. (Updates are not stored permanently; all updates are + lost when the server is restarted.) + </p> + </div> +</div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="catz-info"></a>Catalog Zones</h2></div></div></div> + + <p> + A "catalog zone" is a special DNS zone that contains a list of + other zones to be served, along with their configuration parameters. + Zones listed in a catalog zone are called "member zones". + When a catalog zone is loaded or transferred to a slave server + which supports this functionality, the slave server will create + the member zones automatically. When the catalog zone is updated + (for example, to add or delete member zones, or change + their configuration parameters) those changes are immediately put + into effect. Because the catalog zone is a normal DNS zone, these + configuration changes can be propagated using the standard AXFR/IXFR + zone transfer mechanism. + </p> + <p> + Catalog zones' format and behavior are specified as an internet draft + for interoperability among DNS implementations. As of this release, the + latest revision of the DNS catalog zones draft can be found here: + https://datatracker.ietf.org/doc/draft-muks-dnsop-dns-catalog-zones/ + </p> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.15.4"></a>Principle of Operation</h3></div></div></div> + <p> + Normally, if a zone is to be served by a slave server, the + <code class="filename">named.conf</code> file on the server must list the + zone, or the zone must be added using <span class="command"><strong>rndc addzone</strong></span>. + In environments with a large number of slave servers and/or where + the zones being served are changing frequently, the overhead involved + in maintaining consistent zone configuration on all the slave + servers can be significant. + </p> + <p> + A catalog zone is a way to ease this administrative burden. It is a + DNS zone that lists member zones that should be served by slave servers. + When a slave server receives an update to the catalog zone, it adds, + removes, or reconfigures member zones based on the data received. + </p> + <p> + To use a catalog zone, it must first be set up as a normal zone on + the master and the on slave servers that will be configured to use + it. It must also be added to a <code class="option">catalog-zones</code> list + in the <code class="option">options</code> or <code class="option">view</code> statement + in <code class="filename">named.conf</code>. (This is comparable to the way + a policy zone is configured as a normal zone and also listed in + a <code class="option">response-policy</code> statement.) + </p> + <p> + To use the catalog zone feature to serve a new member zone: + </p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <p> + Set up the the member zone to be served on the master as normal. + This could be done by editing <code class="filename">named.conf</code>, + or by running <span class="command"><strong>rndc addzone</strong></span>. + </p> + </li> +<li class="listitem"> + <p> + Add an entry to the catalog zone for the new member zone. + This could be done by editing the catalog zone's master file + and running <span class="command"><strong>rndc reload</strong></span>, or by updating + the zone using <span class="command"><strong>nsupdate</strong></span>. + </p> + </li> +</ul></div> +<p> + The change to the catalog zone will be propagated from the master to all + slaves using the normal AXFR/IXFR mechanism. When the slave receives the + update to the catalog zone, it will detect the entry for the new member + zone, create an instance of of that zone on the slave server, and point + that instance to the <code class="option">masters</code> specified in the catalog + zone data. The newly created member zone is a normal slave zone, so + BIND will immediately initiate a transfer of zone contents from the + master. Once complete, the slave will start serving the member zone. + </p> + <p> + Removing a member zone from a slave server requires nothing more than + deleting the member zone's entry in the catalog zone. The change to the + catalog zone is propagated to the slave server using the normal AXFR/IXFR + transfer mechanism. The slave server, on processing the update, will + notice that the member zone has been removed. It will stop serving the + zone and remove it from its list of configured zones. (Removing the + member zone from the master server has to be done in the normal way, + by editing the configuration file or running + <span class="command"><strong>rndc delzone</strong></span>.) + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.15.5"></a>Configuring Catalog Zones</h3></div></div></div> + <p> + Catalog zones are configured with a <span class="command"><strong>catalog-zones</strong></span> + statement in the <code class="literal">options</code> or <code class="literal">view</code> + section of <code class="filename">named.conf</code>. For example, + </p> +<pre class="screen"> +catalog-zones { + zone "catalog.example" + default-masters { 10.53.0.1; } + in-memory no + zone-directory "catzones" + min-update-interval 10; +}; +</pre> + <p> + This statement specifies that the zone + <code class="literal">catalog.example</code> is a catalog zone. This zone must be + properly configured in the same view. In most configurations, it would + be a slave zone. + </p> + <p> + The options following the zone name are not required, and may be + specified in any order: + </p> + <p> + The <code class="option">default-masters</code> option defines the default masters + for member zones listed in a catalog zone. This can be overridden by + options within a catalog zone. If no such options are included, then + member zones will transfer their contents from the servers listed in + this option. + </p> + <p> + The <code class="option">in-memory</code> option, if set to <code class="literal">yes</code>, + causes member zones to be stored only in memory. This is functionally + equivalent to configuring a slave zone without a <code class="option">file</code>. + option. The default is <code class="literal">no</code>; member zones' content + will be stored locally in a file whose name is automatically generated + from the view name, catalog zone name, and member zone name. + </p> + <p> + The <code class="option">zone-directory</code> option causes local copies of + member zones' master files (if <code class="option">in-memory</code> is not set + to <code class="literal">yes</code>) to be stored in the specified directory. + The default is to store zone files in the server's working directory. + A non-absolute pathname in <code class="option">zone-directory</code> is + assumed to be relative to the working directory. + </p> + <p> + The <code class="option">min-update-interval</code> option sets the minimum + interval between processing of updates to catalog zones, in seconds. + If an update to a catalog zone (for example, via IXFR) happens less + than <code class="option">min-update-interval</code> seconds after the most + recent update, then the changes will not be carried out until this + interval has elapsed. The default is <code class="literal">5</code> seconds. + </p> + <p> + Catalog zones are defined on a per-view basis. Configuring a non-empty + <code class="option">catalog-zones</code> statement in a view will automatically + turn on <code class="option">allow-new-zones</code> for that view. (Note: this + means <span class="command"><strong>rndc addzone</strong></span> and <span class="command"><strong>rndc delzone</strong></span> + will also work in any view that supports catalog zones.) + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.15.6"></a>Catalog Zone format</h3></div></div></div> + <p> + A catalog zone is a regular DNS zone; therefore, it has to have a + single <code class="literal">SOA</code> and at least one <code class="literal">NS</code> + record. + </p> + <p> + A record stating the version of the catalog zone format is + also required. If the version number listed is not supported by + the server, then a catalog zone may not be used by that server. + </p> +<pre class="screen"> +catalog.example. IN SOA . . 2016022901 900 600 86400 1 +catalog.example. IN NS nsexample. +version.catalog.example. IN TXT "1" +</pre> + <p> + Note that this record must have the domain name + version.<em class="replaceable"><code>catalog-zone-name</code></em>. This illustrates + how the meaning of data stored in a catalog zone is indicated by the + the domain name label immediately before the catalog zone domain. + </p> + <p> + Catalog zone options can be set either globally for the whole catalog + zone or for a single member zone. Global options override the settings + in the configuration file and member zone options override global + options. + </p> + <p> + Global options are set at the apex of the catalog zone, e.g.: +</p> +<pre class="screen"> + masters.catalog.example. IN AAAA 2001:db8::1 +</pre> + <p>BIND currently supports the following options:</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <p>A simple <code class="option">masters</code> definition:</p> + <pre class="screen"> + masters.catalog.example. IN A 192.0.2.1 + </pre> + <p> + This option defines a master server for the member zones - it + can be either an A or AAAA record. If multiple masters are set the + order in which they are used is random. + </p> + </li> +<li class="listitem"> + <p>A <code class="option">masters</code> with a TSIG key defined:</p> + <pre class="screen"> + label.masters.catalog.example. IN A 192.0.2.2 + label.masters.catalog.example. IN TXT "tsig_key_name" + </pre> + <p> + This option defines a master server for the member zone with a TSIG + key set. The TSIG key must be configured in the configuration file. + <code class="option">label</code> can be any valid DNS label. + </p> + </li> +<li class="listitem"> + <p><code class="option">allow-query</code> and + <code class="option">allow-transfer</code> ACLs:</p> + <pre class="screen"> + allow-query.catalog.example. IN APL 1:10.0.0.1/24 + allow-transfer.catalog.example. IN APL !1:10.0.0.1/32 1:10.0.0.0/24 + </pre> + <p> + These options are the equivalents of <code class="option">allow-query</code> + and <code class="option">allow-transfer</code> in a zone declaration in the + <code class="filename">named.conf</code> configuration file. The ACL is + processed in order - if there's no match to any rule the default + policy is to deny access. For the syntax of the APL RR see RFC + 3123 + </p> + </li> +</ul></div> + <p> + A member zone is added by including a <code class="literal">PTR</code> + resource record in the <code class="literal">zones</code> sub-domain of the + catalog zone. The record label is a <code class="literal">SHA-1</code> hash + of the member zone name in wire format. The target of the PTR + record is the member zone name. For example, to add the member + zone <code class="literal">domain.example</code>: + </p> +<pre class="screen"> +5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN PTR domain.example. +</pre> + <p> + The hash is necessary to identify options for a specific member + zone. The member zone-specific options are defined the same way as + global options, but in the member zone subdomain: + </p> +<pre class="screen"> +masters.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN A 192.0.2.2 +label.masters.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN AAAA 2001:db8::2 +label.masters.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN TXT "tsig_key" +allow-query.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN APL 1:10.0.0.0/24 +</pre> + <p> + As would be expected, options defined for a specific zone override + the global options defined in the catalog zone. These in turn override + the global options defined in the <code class="literal">catalog-zones</code> + statement in the configuration file. + </p> + <p> + (Note that none of the global records an option will be inherited if + any records are defined for that option for the specific zone. For + example, if the zone had a <code class="literal">masters</code> record of type + A but not AAAA, then it would <span class="emphasis"><em>not</em></span> inherit the + type AAAA record from the global option.) + </p> + </div> +</div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ipv6"></a>IPv6 Support in <acronym class="acronym">BIND</acronym> 9</h2></div></div></div> + <p> + <acronym class="acronym">BIND</acronym> 9 fully supports all currently + defined forms of IPv6 name to address and address to name + lookups. It will also use IPv6 addresses to make queries when + running on an IPv6 capable system. + </p> + + <p> + For forward lookups, <acronym class="acronym">BIND</acronym> 9 supports + only AAAA records. RFC 3363 deprecated the use of A6 records, + and client-side support for A6 records was accordingly removed + from <acronym class="acronym">BIND</acronym> 9. + However, authoritative <acronym class="acronym">BIND</acronym> 9 name servers still + load zone files containing A6 records correctly, answer queries + for A6 records, and accept zone transfer for a zone containing A6 + records. + </p> + + <p> + For IPv6 reverse lookups, <acronym class="acronym">BIND</acronym> 9 supports + the traditional "nibble" format used in the + <span class="emphasis"><em>ip6.arpa</em></span> domain, as well as the older, deprecated + <span class="emphasis"><em>ip6.int</em></span> domain. + Older versions of <acronym class="acronym">BIND</acronym> 9 + supported the "binary label" (also known as "bitstring") format, + but support of binary labels has been completely removed per + RFC 3363. + Many applications in <acronym class="acronym">BIND</acronym> 9 do not understand + the binary label format at all any more, and will return an + error if given. + In particular, an authoritative <acronym class="acronym">BIND</acronym> 9 + name server will not load a zone file containing binary labels. + </p> + + <p> + For an overview of the format and structure of IPv6 addresses, + see <a class="xref" href="Bv9ARM.ch11.html#ipv6addresses" title="IPv6 addresses (AAAA)">the section called “IPv6 addresses (AAAA)”</a>. + </p> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.16.6"></a>Address Lookups Using AAAA Records</h3></div></div></div> + + <p> + The IPv6 AAAA record is a parallel to the IPv4 A record, + and, unlike the deprecated A6 record, specifies the entire + IPv6 address in a single record. For example, + </p> + +<pre class="programlisting"> +$ORIGIN example.com. +host 3600 IN AAAA 2001:db8::1 +</pre> + + <p> + Use of IPv4-in-IPv6 mapped addresses is not recommended. + If a host has an IPv4 address, use an A record, not + a AAAA, with <code class="literal">::ffff:192.168.42.1</code> as + the address. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.5.16.7"></a>Address to Name Lookups Using Nibble Format</h3></div></div></div> + + <p> + When looking up an address in nibble format, the address + components are simply reversed, just as in IPv4, and + <code class="literal">ip6.arpa.</code> is appended to the + resulting name. + For example, the following would provide reverse name lookup for + a host with address + <code class="literal">2001:db8::1</code>. + </p> + +<pre class="programlisting"> +$ORIGIN 0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa. +1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0 14400 IN PTR ( + host.example.com. ) +</pre> + + </div> + </div> + </div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="Bv9ARM.ch03.html">Prev</a> </td> +<td width="20%" align="center"> </td> +<td width="40%" align="right"> <a accesskey="n" href="Bv9ARM.ch05.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top">Chapter 3. Name Server Configuration </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> Chapter 5. The <acronym class="acronym">BIND</acronym> 9 Lightweight Resolver</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/Bv9ARM.ch05.html b/doc/arm/Bv9ARM.ch05.html new file mode 100644 index 0000000..aa2b8d7 --- /dev/null +++ b/doc/arm/Bv9ARM.ch05.html @@ -0,0 +1,147 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Chapter 5. The BIND 9 Lightweight Resolver</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="prev" href="Bv9ARM.ch04.html" title="Chapter 4. Advanced DNS Features"> +<link rel="next" href="Bv9ARM.ch06.html" title="Chapter 6. BIND 9 Configuration Reference"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center">Chapter 5. The <acronym class="acronym">BIND</acronym> 9 Lightweight Resolver</th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="Bv9ARM.ch04.html">Prev</a> </td> +<th width="60%" align="center"> </th> +<td width="20%" align="right"> <a accesskey="n" href="Bv9ARM.ch06.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="chapter"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="Bv9ARM.ch05"></a>Chapter 5. The <acronym class="acronym">BIND</acronym> 9 Lightweight Resolver</h1></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="Bv9ARM.ch05.html#lightweight_resolver">The Lightweight Resolver Library</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch05.html#lwresd">Running a Resolver Daemon</a></span></dt> +</dl> +</div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="lightweight_resolver"></a>The Lightweight Resolver Library</h2></div></div></div> + + <p> + Traditionally applications have been linked with a stub resolver + library that sends recursive DNS queries to a local caching name + server. + </p> + <p> + IPv6 once introduced new complexity into the resolution process, + such as following A6 chains and DNAME records, and simultaneous + lookup of IPv4 and IPv6 addresses. Though most of the complexity was + then removed, these are hard or impossible + to implement in a traditional stub resolver. + </p> + <p> + <acronym class="acronym">BIND</acronym> 9 therefore can also provide resolution + services to local clients + using a combination of a lightweight resolver library and a resolver + daemon process running on the local host. These communicate using + a simple UDP-based protocol, the "lightweight resolver protocol" + that is distinct from and simpler than the full DNS protocol. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="lwresd"></a>Running a Resolver Daemon</h2></div></div></div> + + <p> + To use the lightweight resolver interface, the system must + run the resolver daemon <span class="command"><strong>lwresd</strong></span> or a + local + name server configured with a <span class="command"><strong>lwres</strong></span> + statement. + </p> + + <p> + By default, applications using the lightweight resolver library will + make + UDP requests to the IPv4 loopback address (127.0.0.1) on port 921. + The + address can be overridden by <span class="command"><strong>lwserver</strong></span> + lines in + <code class="filename">/etc/resolv.conf</code>. + </p> + + <p> + The daemon currently only looks in the DNS, but in the future + it may use other sources such as <code class="filename">/etc/hosts</code>, + NIS, etc. + </p> + + <p> + The <span class="command"><strong>lwresd</strong></span> daemon is essentially a + caching-only name server that responds to requests using the + lightweight + resolver protocol rather than the DNS protocol. Because it needs + to run on each host, it is designed to require no or minimal + configuration. + Unless configured otherwise, it uses the name servers listed on + <span class="command"><strong>nameserver</strong></span> lines in <code class="filename">/etc/resolv.conf</code> + as forwarders, but is also capable of doing the resolution + autonomously if + none are specified. + </p> + <p> + The <span class="command"><strong>lwresd</strong></span> daemon may also be + configured with a + <code class="filename">named.conf</code> style configuration file, + in + <code class="filename">/etc/lwresd.conf</code> by default. A name + server may also + be configured to act as a lightweight resolver daemon using the + <span class="command"><strong>lwres</strong></span> statement in <code class="filename">named.conf</code>. + </p> + <p> + The number of client queries that the <span class="command"><strong>lwresd</strong></span> + daemon is able to serve can be set using the + <code class="option">lwres-tasks</code> and <code class="option">lwres-clients</code> + statements in the configuration. + </p> + </div> + </div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="Bv9ARM.ch04.html">Prev</a> </td> +<td width="20%" align="center"> </td> +<td width="40%" align="right"> <a accesskey="n" href="Bv9ARM.ch06.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top">Chapter 4. Advanced DNS Features </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> Chapter 6. <acronym class="acronym">BIND</acronym> 9 Configuration Reference</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/Bv9ARM.ch06.html b/doc/arm/Bv9ARM.ch06.html new file mode 100644 index 0000000..8b35d8a --- /dev/null +++ b/doc/arm/Bv9ARM.ch06.html @@ -0,0 +1,14665 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Chapter 6. BIND 9 Configuration Reference</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="prev" href="Bv9ARM.ch05.html" title="Chapter 5. The BIND 9 Lightweight Resolver"> +<link rel="next" href="Bv9ARM.ch07.html" title="Chapter 7. BIND 9 Security Considerations"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center">Chapter 6. <acronym class="acronym">BIND</acronym> 9 Configuration Reference</th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="Bv9ARM.ch05.html">Prev</a> </td> +<th width="60%" align="center"> </th> +<td width="20%" align="right"> <a accesskey="n" href="Bv9ARM.ch07.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="chapter"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="Bv9ARM.ch06"></a>Chapter 6. <acronym class="acronym">BIND</acronym> 9 Configuration Reference</h1></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="Bv9ARM.ch06.html#configuration_file_elements">Configuration File Elements</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch06.html#address_match_lists">Address Match Lists</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#comment_syntax">Comment Syntax</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch06.html#Configuration_File_Grammar">Configuration File Grammar</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch06.html#acl_grammar"><span class="command"><strong>acl</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#acl"><span class="command"><strong>acl</strong></span> Statement Definition and + Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#controls_grammar"><span class="command"><strong>controls</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#controls_statement_definition_and_usage"><span class="command"><strong>controls</strong></span> Statement Definition and + Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#include_grammar"><span class="command"><strong>include</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#include_statement"><span class="command"><strong>include</strong></span> Statement Definition and Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#key_grammar"><span class="command"><strong>key</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#key_statement"><span class="command"><strong>key</strong></span> Statement Definition and Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#logging_grammar"><span class="command"><strong>logging</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#logging_statement"><span class="command"><strong>logging</strong></span> Statement Definition and Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#lwres_grammar"><span class="command"><strong>lwres</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#lwres_statement"><span class="command"><strong>lwres</strong></span> Statement Definition and Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#masters_grammar"><span class="command"><strong>masters</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#masters_statement"><span class="command"><strong>masters</strong></span> Statement Definition and + Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#options_grammar"><span class="command"><strong>options</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#options"><span class="command"><strong>options</strong></span> Statement Definition and + Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#server_statement_grammar"><span class="command"><strong>server</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#server_statement_definition_and_usage"><span class="command"><strong>server</strong></span> Statement Definition and + Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#statschannels"><span class="command"><strong>statistics-channels</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#statistics_channels"><span class="command"><strong>statistics-channels</strong></span> Statement Definition and + Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#trusted-keys"><span class="command"><strong>trusted-keys</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#trusted_keys"><span class="command"><strong>trusted-keys</strong></span> Statement Definition + and Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#managed_keys"><span class="command"><strong>managed-keys</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#managed-keys"><span class="command"><strong>managed-keys</strong></span> Statement Definition + and Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#view_statement_grammar"><span class="command"><strong>view</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#view_statement"><span class="command"><strong>view</strong></span> Statement Definition and Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#zone_statement_grammar"><span class="command"><strong>zone</strong></span> + Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#zone_statement"><span class="command"><strong>zone</strong></span> Statement Definition and Usage</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch06.html#zone_file">Zone File</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch06.html#types_of_resource_records_and_when_to_use_them">Types of Resource Records and When to Use Them</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#mx_records">Discussion of MX Records</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#Setting_TTLs">Setting TTLs</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#ipv4_reverse">Inverse Mapping in IPv4</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#zone_directives">Other Zone File Directives</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#generate_directive"><acronym class="acronym">BIND</acronym> Master File Extension: the <span class="command"><strong>$GENERATE</strong></span> Directive</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#zonefile_format">Additional File Formats</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch06.html#statistics">BIND9 Statistics</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch06.html#statsfile">The Statistics File</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#statistics_counters">Statistics Counters</a></span></dt> +</dl></dd> +</dl> +</div> + + <p> + <acronym class="acronym">BIND</acronym> 9 configuration is broadly similar + to <acronym class="acronym">BIND</acronym> 8; however, there are a few new + areas + of configuration, such as views. <acronym class="acronym">BIND</acronym> + 8 configuration files should work with few alterations in <acronym class="acronym">BIND</acronym> + 9, although more complex configurations should be reviewed to check + if they can be more efficiently implemented using the new features + found in <acronym class="acronym">BIND</acronym> 9. + </p> + + <p> + <acronym class="acronym">BIND</acronym> 4 configuration files can be + converted to the new format + using the shell script + <code class="filename">contrib/named-bootconf/named-bootconf.sh</code>. + </p> + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="configuration_file_elements"></a>Configuration File Elements</h2></div></div></div> + + <p> + Following is a list of elements used throughout the <acronym class="acronym">BIND</acronym> configuration + file documentation: + </p> + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.855in" class="1"> +<col width="3.770in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p> + <code class="varname">acl_name</code> + </p> + </td> +<td> + <p> + The name of an <code class="varname">address_match_list</code> as + defined by the <span class="command"><strong>acl</strong></span> statement. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">address_match_list</code> + </p> + </td> +<td> + <p> + A list of one or more + <code class="varname">ip_addr</code>, + <code class="varname">ip_prefix</code>, <code class="varname">key_id</code>, + or <code class="varname">acl_name</code> elements, see + <a class="xref" href="Bv9ARM.ch06.html#address_match_lists" title="Address Match Lists">the section called “Address Match Lists”</a>. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">masters_list</code> + </p> + </td> +<td> + <p> + A named list of one or more <code class="varname">ip_addr</code> + with optional <code class="varname">key_id</code> and/or + <code class="varname">ip_port</code>. + A <code class="varname">masters_list</code> may include other + <code class="varname">masters_lists</code>. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">domain_name</code> + </p> + </td> +<td> + <p> + A quoted string which will be used as + a DNS name, for example "<code class="literal">my.test.domain</code>". + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">namelist</code> + </p> + </td> +<td> + <p> + A list of one or more <code class="varname">domain_name</code> + elements. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">dotted_decimal</code> + </p> + </td> +<td> + <p> + One to four integers valued 0 through + 255 separated by dots (`.'), such as <span class="command"><strong>123</strong></span>, + <span class="command"><strong>45.67</strong></span> or <span class="command"><strong>89.123.45.67</strong></span>. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">ip4_addr</code> + </p> + </td> +<td> + <p> + An IPv4 address with exactly four elements + in <code class="varname">dotted_decimal</code> notation. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">ip6_addr</code> + </p> + </td> +<td> + <p> + An IPv6 address, such as <span class="command"><strong>2001:db8::1234</strong></span>. + IPv6 scoped addresses that have ambiguity on their + scope zones must be disambiguated by an appropriate + zone ID with the percent character (`%') as + delimiter. It is strongly recommended to use + string zone names rather than numeric identifiers, + in order to be robust against system configuration + changes. However, since there is no standard + mapping for such names and identifier values, + currently only interface names as link identifiers + are supported, assuming one-to-one mapping between + interfaces and links. For example, a link-local + address <span class="command"><strong>fe80::1</strong></span> on the link + attached to the interface <span class="command"><strong>ne0</strong></span> + can be specified as <span class="command"><strong>fe80::1%ne0</strong></span>. + Note that on most systems link-local addresses + always have the ambiguity, and need to be + disambiguated. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">ip_addr</code> + </p> + </td> +<td> + <p> + An <code class="varname">ip4_addr</code> or <code class="varname">ip6_addr</code>. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">ip_dscp</code> + </p> + </td> +<td> + <p> + A <code class="varname">number</code> between 0 and 63, used + to select a differentiated services code point (DSCP) + value for use with outgoing traffic on operating systems + that support DSCP. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">ip_port</code> + </p> + </td> +<td> + <p> + An IP port <code class="varname">number</code>. + The <code class="varname">number</code> is limited to 0 + through 65535, with values + below 1024 typically restricted to use by processes running + as root. + In some cases, an asterisk (`*') character can be used as a + placeholder to + select a random high-numbered port. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">ip_prefix</code> + </p> + </td> +<td> + <p> + An IP network specified as an <code class="varname">ip_addr</code>, + followed by a slash (`/') and then the number of bits in the + netmask. + Trailing zeros in a <code class="varname">ip_addr</code> + may omitted. + For example, <span class="command"><strong>127/8</strong></span> is the + network <span class="command"><strong>127.0.0.0</strong></span> with + netmask <span class="command"><strong>255.0.0.0</strong></span> and <span class="command"><strong>1.2.3.0/28</strong></span> is + network <span class="command"><strong>1.2.3.0</strong></span> with netmask <span class="command"><strong>255.255.255.240</strong></span>. + </p> + <p> + When specifying a prefix involving a IPv6 scoped address + the scope may be omitted. In that case the prefix will + match packets from any scope. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">key_id</code> + </p> + </td> +<td> + <p> + A <code class="varname">domain_name</code> representing + the name of a shared key, to be used for transaction + security. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">key_list</code> + </p> + </td> +<td> + <p> + A list of one or more + <code class="varname">key_id</code>s, + separated by semicolons and ending with a semicolon. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">number</code> + </p> + </td> +<td> + <p> + A non-negative 32-bit integer + (i.e., a number between 0 and 4294967295, inclusive). + Its acceptable value might be further + limited by the context in which it is used. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">fixedpoint</code> + </p> + </td> +<td> + <p> + A non-negative real number that can be specified to + the nearest one hundredth. Up to five digits can be + specified before a decimal point, and up to two + digits after, so the maximum value is 99999.99. + Acceptable values might be further limited by the + context in which it is used. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">path_name</code> + </p> + </td> +<td> + <p> + A quoted string which will be used as + a pathname, such as <code class="filename">zones/master/my.test.domain</code>. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">port_list</code> + </p> + </td> +<td> + <p> + A list of an <code class="varname">ip_port</code> or a port + range. + A port range is specified in the form of + <strong class="userinput"><code>range</code></strong> followed by + two <code class="varname">ip_port</code>s, + <code class="varname">port_low</code> and + <code class="varname">port_high</code>, which represents + port numbers from <code class="varname">port_low</code> through + <code class="varname">port_high</code>, inclusive. + <code class="varname">port_low</code> must not be larger than + <code class="varname">port_high</code>. + For example, + <strong class="userinput"><code>range 1024 65535</code></strong> represents + ports from 1024 through 65535. + In either case an asterisk (`*') character is not + allowed as a valid <code class="varname">ip_port</code>. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">size_spec</code> + </p> + </td> +<td> + <p> + A 64-bit unsigned integer, or the keywords + <strong class="userinput"><code>unlimited</code></strong> or + <strong class="userinput"><code>default</code></strong>. + </p> + <p> + Integers may take values + 0 <= value <= 18446744073709551615, though + certain parameters + (such as <span class="command"><strong>max-journal-size</strong></span>) may + use a more limited range within these extremes. + In most cases, setting a value to 0 does not + literally mean zero; it means "undefined" or + "as big as possible", depending on the context. + See the explanations of particular parameters + that use <code class="varname">size_spec</code> + for details on how they interpret its use. + </p> + <p> + Numeric values can optionally be followed by a + scaling factor: + <strong class="userinput"><code>K</code></strong> or <strong class="userinput"><code>k</code></strong> + for kilobytes, + <strong class="userinput"><code>M</code></strong> or <strong class="userinput"><code>m</code></strong> + for megabytes, and + <strong class="userinput"><code>G</code></strong> or <strong class="userinput"><code>g</code></strong> + for gigabytes, which scale by 1024, 1024*1024, and + 1024*1024*1024 respectively. + </p> + <p> + <code class="varname">unlimited</code> generally means + "as big as possible", and is usually the best + way to safely set a very large number. + </p> + <p> + <code class="varname">default</code> + uses the limit that was in force when the server was started. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">size_or_percent</code> + </p> + </td> +<td> + <p> + <code class="varname">size_spec</code> or integer value + followed by '%' to represent percents. + </p> + <p> + The behavior is exactly the same as + <code class="varname">size_spec</code>, but + <code class="varname">size_or_percent</code> allows also + to specify a positive integer value followed by + '%' sign to represent percents. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">yes_or_no</code> + </p> + </td> +<td> + <p> + Either <strong class="userinput"><code>yes</code></strong> or <strong class="userinput"><code>no</code></strong>. + The words <strong class="userinput"><code>true</code></strong> and <strong class="userinput"><code>false</code></strong> are + also accepted, as are the numbers <strong class="userinput"><code>1</code></strong> + and <strong class="userinput"><code>0</code></strong>. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">dialup_option</code> + </p> + </td> +<td> + <p> + One of <strong class="userinput"><code>yes</code></strong>, + <strong class="userinput"><code>no</code></strong>, <strong class="userinput"><code>notify</code></strong>, + <strong class="userinput"><code>notify-passive</code></strong>, <strong class="userinput"><code>refresh</code></strong> or + <strong class="userinput"><code>passive</code></strong>. + When used in a zone, <strong class="userinput"><code>notify-passive</code></strong>, + <strong class="userinput"><code>refresh</code></strong>, and <strong class="userinput"><code>passive</code></strong> + are restricted to slave and stub zones. + </p> + </td> +</tr> +</tbody> +</table> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="address_match_lists"></a>Address Match Lists</h3></div></div></div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.7.4.4.2"></a>Syntax</h4></div></div></div> + +<pre class="programlisting"><em class="replaceable"><code>address_match_list</code></em> = <em class="replaceable"><code>address_match_list_element</code></em> <span class="command"><strong>;</strong></span> ... + +<em class="replaceable"><code>address_match_list_element</code></em> = [ <span class="command"><strong>!</strong></span> ] ( <em class="replaceable"><code>ip_address</code></em> | <em class="replaceable"><code>ip_prefix</code></em> | + <span class="command"><strong>key</strong></span> <em class="replaceable"><code>key_id</code></em> | <em class="replaceable"><code>acl_name</code></em> | <span class="command"><strong>{</strong></span> <em class="replaceable"><code>address_match_list</code></em> <span class="command"><strong>}</strong></span> ) +</pre> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.7.4.4.3"></a>Definition and Usage</h4></div></div></div> + + <p> + Address match lists are primarily used to determine access + control for various server operations. They are also used in + the <span class="command"><strong>listen-on</strong></span> and <span class="command"><strong>sortlist</strong></span> + statements. The elements which constitute an address match + list can be any of the following: + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + an IP address (IPv4 or IPv6) + </li> +<li class="listitem"> + an IP prefix (in `/' notation) + </li> +<li class="listitem"> + + a key ID, as defined by the <span class="command"><strong>key</strong></span> + statement + + </li> +<li class="listitem"> + the name of an address match list defined with + the <span class="command"><strong>acl</strong></span> statement + + </li> +<li class="listitem"> + a nested address match list enclosed in braces + </li> +</ul></div> + + <p> + Elements can be negated with a leading exclamation mark (`!'), + and the match list names "any", "none", "localhost", and + "localnets" are predefined. More information on those names + can be found in the description of the acl statement. + </p> + + <p> + The addition of the key clause made the name of this syntactic + element something of a misnomer, since security keys can be used + to validate access without regard to a host or network address. + Nonetheless, the term "address match list" is still used + throughout the documentation. + </p> + + <p> + When a given IP address or prefix is compared to an address + match list, the comparison takes place in approximately O(1) + time. However, key comparisons require that the list of keys + be traversed until a matching key is found, and therefore may + be somewhat slower. + </p> + + <p> + The interpretation of a match depends on whether the list is being + used for access control, defining <span class="command"><strong>listen-on</strong></span> ports, or in a + <span class="command"><strong>sortlist</strong></span>, and whether the element was negated. + </p> + + <p> + When used as an access control list, a non-negated match + allows access and a negated match denies access. If + there is no match, access is denied. The clauses + <span class="command"><strong>allow-notify</strong></span>, + <span class="command"><strong>allow-recursion</strong></span>, + <span class="command"><strong>allow-recursion-on</strong></span>, + <span class="command"><strong>allow-query</strong></span>, + <span class="command"><strong>allow-query-on</strong></span>, + <span class="command"><strong>allow-query-cache</strong></span>, + <span class="command"><strong>allow-query-cache-on</strong></span>, + <span class="command"><strong>allow-transfer</strong></span>, + <span class="command"><strong>allow-update</strong></span>, + <span class="command"><strong>allow-update-forwarding</strong></span>, + <span class="command"><strong>blackhole</strong></span>, and + <span class="command"><strong>keep-response-order</strong></span> all use address match + lists. Similarly, the <span class="command"><strong>listen-on</strong></span> option will cause the + server to refuse queries on any of the machine's + addresses which do not match the list. + </p> + + <p> + Order of insertion is significant. If more than one element + in an ACL is found to match a given IP address or prefix, + preference will be given to the one that came + <span class="emphasis"><em>first</em></span> in the ACL definition. + Because of this first-match behavior, an element that + defines a subset of another element in the list should + come before the broader element, regardless of whether + either is negated. For example, in + <span class="command"><strong>1.2.3/24; ! 1.2.3.13;</strong></span> + the 1.2.3.13 element is completely useless because the + algorithm will match any lookup for 1.2.3.13 to the 1.2.3/24 + element. Using <span class="command"><strong>! 1.2.3.13; 1.2.3/24</strong></span> fixes + that problem by having 1.2.3.13 blocked by the negation, but + all other 1.2.3.* hosts fall through. + </p> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="comment_syntax"></a>Comment Syntax</h3></div></div></div> + + <p> + The <acronym class="acronym">BIND</acronym> 9 comment syntax allows for + comments to appear + anywhere that whitespace may appear in a <acronym class="acronym">BIND</acronym> configuration + file. To appeal to programmers of all kinds, they can be written + in the C, C++, or shell/perl style. + </p> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.7.4.5.3"></a>Syntax</h4></div></div></div> + + <p> + </p> +<pre class="programlisting">/* This is a <acronym class="acronym">BIND</acronym> comment as in C */</pre> +<p> + </p> +<pre class="programlisting">// This is a <acronym class="acronym">BIND</acronym> comment as in C++</pre> +<p> + </p> +<pre class="programlisting"># This is a <acronym class="acronym">BIND</acronym> comment as in common UNIX shells +# and perl</pre> +<p> + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.7.4.5.4"></a>Definition and Usage</h4></div></div></div> + + <p> + Comments may appear anywhere that whitespace may appear in + a <acronym class="acronym">BIND</acronym> configuration file. + </p> + <p> + C-style comments start with the two characters /* (slash, + star) and end with */ (star, slash). Because they are completely + delimited with these characters, they can be used to comment only + a portion of a line or to span multiple lines. + </p> + <p> + C-style comments cannot be nested. For example, the following + is not valid because the entire comment ends with the first */: + </p> + <p> + +</p> +<pre class="programlisting">/* This is the start of a comment. + This is still part of the comment. +/* This is an incorrect attempt at nesting a comment. */ + This is no longer in any comment. */ +</pre> +<p> + + </p> + + <p> + C++-style comments start with the two characters // (slash, + slash) and continue to the end of the physical line. They cannot + be continued across multiple physical lines; to have one logical + comment span multiple lines, each line must use the // pair. + For example: + </p> + <p> + +</p> +<pre class="programlisting">// This is the start of a comment. The next line +// is a new comment, even though it is logically +// part of the previous comment. +</pre> +<p> + + </p> + <p> + Shell-style (or perl-style, if you prefer) comments start + with the character <code class="literal">#</code> (number sign) + and continue to the end of the + physical line, as in C++ comments. + For example: + </p> + + <p> + +</p> +<pre class="programlisting"># This is the start of a comment. The next line +# is a new comment, even though it is logically +# part of the previous comment. +</pre> +<p> + + </p> + + <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Warning</h3> + <p> + You cannot use the semicolon (`;') character + to start a comment such as you would in a zone file. The + semicolon indicates the end of a configuration + statement. + </p> + </div> + </div> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="Configuration_File_Grammar"></a>Configuration File Grammar</h2></div></div></div> + + <p> + A <acronym class="acronym">BIND</acronym> 9 configuration consists of + statements and comments. + Statements end with a semicolon. Statements and comments are the + only elements that can appear without enclosing braces. Many + statements contain a block of sub-statements, which are also + terminated with a semicolon. + </p> + + <p> + The following statements are supported: + </p> + + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.336in" class="1"> +<col width="3.778in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p><span class="command"><strong>acl</strong></span></p> + </td> +<td> + <p> + defines a named IP address + matching list, for access control and other uses. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>controls</strong></span></p> + </td> +<td> + <p> + declares control channels to be used + by the <span class="command"><strong>rndc</strong></span> utility. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>include</strong></span></p> + </td> +<td> + <p> + includes a file. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>key</strong></span></p> + </td> +<td> + <p> + specifies key information for use in + authentication and authorization using TSIG. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>logging</strong></span></p> + </td> +<td> + <p> + specifies what the server logs, and where + the log messages are sent. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>lwres</strong></span></p> + </td> +<td> + <p> + configures <span class="command"><strong>named</strong></span> to + also act as a light-weight resolver daemon (<span class="command"><strong>lwresd</strong></span>). + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>masters</strong></span></p> + </td> +<td> + <p> + defines a named masters list for + inclusion in stub and slave zones' + <span class="command"><strong>masters</strong></span> or + <span class="command"><strong>also-notify</strong></span> lists. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>options</strong></span></p> + </td> +<td> + <p> + controls global server configuration + options and sets defaults for other statements. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>server</strong></span></p> + </td> +<td> + <p> + sets certain configuration options on + a per-server basis. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>statistics-channels</strong></span></p> + </td> +<td> + <p> + declares communication channels to get access to + <span class="command"><strong>named</strong></span> statistics. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>trusted-keys</strong></span></p> + </td> +<td> + <p> + defines trusted DNSSEC keys. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>managed-keys</strong></span></p> + </td> +<td> + <p> + lists DNSSEC keys to be kept up to date + using RFC 5011 trust anchor maintenance. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>view</strong></span></p> + </td> +<td> + <p> + defines a view. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>zone</strong></span></p> + </td> +<td> + <p> + defines a zone. + </p> + </td> +</tr> +</tbody> +</table> + </div> + + <p> + The <span class="command"><strong>logging</strong></span> and + <span class="command"><strong>options</strong></span> statements may only occur once + per + configuration. + </p> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="acl_grammar"></a><span class="command"><strong>acl</strong></span> Statement Grammar</h3></div></div></div> + <pre class="programlisting"> +<span class="command"><strong>acl</strong></span> <em class="replaceable"><code>string</code></em> { <em class="replaceable"><code>address_match_element</code></em>; ... }; +</pre> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="acl"></a><span class="command"><strong>acl</strong></span> Statement Definition and + Usage</h3></div></div></div> + + <p> + The <span class="command"><strong>acl</strong></span> statement assigns a symbolic + name to an address match list. It gets its name from a primary + use of address match lists: Access Control Lists (ACLs). + </p> + + <p> + The following ACLs are built-in: + </p> + + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.130in" class="1"> +<col width="4.000in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p><span class="command"><strong>any</strong></span></p> + </td> +<td> + <p> + Matches all hosts. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>none</strong></span></p> + </td> +<td> + <p> + Matches no hosts. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>localhost</strong></span></p> + </td> +<td> + <p> + Matches the IPv4 and IPv6 addresses of all network + interfaces on the system. When addresses are + added or removed, the <span class="command"><strong>localhost</strong></span> + ACL element is updated to reflect the changes. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>localnets</strong></span></p> + </td> +<td> + <p> + Matches any host on an IPv4 or IPv6 network + for which the system has an interface. + When addresses are added or removed, + the <span class="command"><strong>localnets</strong></span> + ACL element is updated to reflect the changes. + Some systems do not provide a way to determine the prefix + lengths of + local IPv6 addresses. + In such a case, <span class="command"><strong>localnets</strong></span> + only matches the local + IPv6 addresses, just like <span class="command"><strong>localhost</strong></span>. + </p> + </td> +</tr> +</tbody> +</table> + </div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="controls_grammar"></a><span class="command"><strong>controls</strong></span> Statement Grammar</h3></div></div></div> + <pre class="programlisting"> +<span class="command"><strong>controls</strong></span> { + <span class="command"><strong>inet</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | <em class="replaceable"><code>ipv6_address</code></em> | + * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] allow + { <em class="replaceable"><code>address_match_element</code></em>; ... } [ + <span class="command"><strong>keys</strong></span> { <em class="replaceable"><code>string</code></em>; ... } ] [ read-only + <em class="replaceable"><code>boolean</code></em> ]; + <span class="command"><strong>unix</strong></span> <em class="replaceable"><code>quoted_string</code></em> perm <em class="replaceable"><code>integer</code></em> + <span class="command"><strong>owner</strong></span> <em class="replaceable"><code>integer</code></em> group <em class="replaceable"><code>integer</code></em> [ + <span class="command"><strong>keys</strong></span> { <em class="replaceable"><code>string</code></em>; ... } ] [ read-only + <em class="replaceable"><code>boolean</code></em> ]; +}; +</pre> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="controls_statement_definition_and_usage"></a><span class="command"><strong>controls</strong></span> Statement Definition and + Usage</h3></div></div></div> + + <p> + The <span class="command"><strong>controls</strong></span> statement declares control + channels to be used by system administrators to control the + operation of the name server. These control channels are + used by the <span class="command"><strong>rndc</strong></span> utility to send + commands to and retrieve non-DNS results from a name server. + </p> + + <p> + An <span class="command"><strong>inet</strong></span> control channel is a TCP socket + listening at the specified <span class="command"><strong>ip_port</strong></span> on the + specified <span class="command"><strong>ip_addr</strong></span>, which can be an IPv4 or IPv6 + address. An <span class="command"><strong>ip_addr</strong></span> of <code class="literal">*</code> (asterisk) is + interpreted as the IPv4 wildcard address; connections will be + accepted on any of the system's IPv4 addresses. + To listen on the IPv6 wildcard address, + use an <span class="command"><strong>ip_addr</strong></span> of <code class="literal">::</code>. + If you will only use <span class="command"><strong>rndc</strong></span> on the local host, + using the loopback address (<code class="literal">127.0.0.1</code> + or <code class="literal">::1</code>) is recommended for maximum security. + </p> + + <p> + If no port is specified, port 953 is used. The asterisk + "<code class="literal">*</code>" cannot be used for <span class="command"><strong>ip_port</strong></span>. + </p> + + <p> + The ability to issue commands over the control channel is + restricted by the <span class="command"><strong>allow</strong></span> and + <span class="command"><strong>keys</strong></span> clauses. + Connections to the control channel are permitted based on the + <span class="command"><strong>address_match_list</strong></span>. This is for simple + IP address based filtering only; any <span class="command"><strong>key_id</strong></span> + elements of the <span class="command"><strong>address_match_list</strong></span> + are ignored. + </p> + + <p> + A <span class="command"><strong>unix</strong></span> control channel is a UNIX domain + socket listening at the specified path in the file system. + Access to the socket is specified by the <span class="command"><strong>perm</strong></span>, + <span class="command"><strong>owner</strong></span> and <span class="command"><strong>group</strong></span> clauses. + Note on some platforms (SunOS and Solaris) the permissions + (<span class="command"><strong>perm</strong></span>) are applied to the parent directory + as the permissions on the socket itself are ignored. + </p> + + <p> + The primary authorization mechanism of the command + channel is the <span class="command"><strong>key_list</strong></span>, which + contains a list of <span class="command"><strong>key_id</strong></span>s. + Each <span class="command"><strong>key_id</strong></span> in the <span class="command"><strong>key_list</strong></span> + is authorized to execute commands over the control channel. + See <a class="xref" href="Bv9ARM.ch03.html#rndc">Remote Name Daemon Control application</a> in <a class="xref" href="Bv9ARM.ch03.html#admin_tools" title="Administrative Tools">the section called “Administrative Tools”</a>) + for information about configuring keys in <span class="command"><strong>rndc</strong></span>. + </p> + + <p> + If the <span class="command"><strong>read-only</strong></span> clause is enabled, the + control channel is limited to the following set of read-only + commands: <span class="command"><strong>nta -dump</strong></span>, + <span class="command"><strong>null</strong></span>, <span class="command"><strong>status</strong></span>, + <span class="command"><strong>showzone</strong></span>, <span class="command"><strong>testgen</strong></span>, and + <span class="command"><strong>zonestatus</strong></span>. By default, + <span class="command"><strong>read-only</strong></span> is not enabled and the control + channel allows read-write access. + </p> + + <p> + If no <span class="command"><strong>controls</strong></span> statement is present, + <span class="command"><strong>named</strong></span> will set up a default + control channel listening on the loopback address 127.0.0.1 + and its IPv6 counterpart ::1. + In this case, and also when the <span class="command"><strong>controls</strong></span> statement + is present but does not have a <span class="command"><strong>keys</strong></span> clause, + <span class="command"><strong>named</strong></span> will attempt to load the command channel key + from the file <code class="filename">rndc.key</code> in + <code class="filename">/etc</code> (or whatever <code class="varname">sysconfdir</code> + was specified as when <acronym class="acronym">BIND</acronym> was built). + To create a <code class="filename">rndc.key</code> file, run + <strong class="userinput"><code>rndc-confgen -a</code></strong>. + </p> + + <p> + The <code class="filename">rndc.key</code> feature was created to + ease the transition of systems from <acronym class="acronym">BIND</acronym> 8, + which did not have digital signatures on its command channel + messages and thus did not have a <span class="command"><strong>keys</strong></span> clause. + + It makes it possible to use an existing <acronym class="acronym">BIND</acronym> 8 + configuration file in <acronym class="acronym">BIND</acronym> 9 unchanged, + and still have <span class="command"><strong>rndc</strong></span> work the same way + <span class="command"><strong>ndc</strong></span> worked in BIND 8, simply by executing the + command <strong class="userinput"><code>rndc-confgen -a</code></strong> after BIND 9 is + installed. + </p> + + <p> + Since the <code class="filename">rndc.key</code> feature + is only intended to allow the backward-compatible usage of + <acronym class="acronym">BIND</acronym> 8 configuration files, this + feature does not + have a high degree of configurability. You cannot easily change + the key name or the size of the secret, so you should make a + <code class="filename">rndc.conf</code> with your own key if you + wish to change + those things. The <code class="filename">rndc.key</code> file + also has its + permissions set such that only the owner of the file (the user that + <span class="command"><strong>named</strong></span> is running as) can access it. + If you + desire greater flexibility in allowing other users to access + <span class="command"><strong>rndc</strong></span> commands, then you need to create + a + <code class="filename">rndc.conf</code> file and make it group + readable by a group + that contains the users who should have access. + </p> + + <p> + To disable the command channel, use an empty + <span class="command"><strong>controls</strong></span> statement: + <span class="command"><strong>controls { };</strong></span>. + </p> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="include_grammar"></a><span class="command"><strong>include</strong></span> Statement Grammar</h3></div></div></div> + + <pre class="programlisting"><span class="command"><strong>include</strong></span> <em class="replaceable"><code>filename</code></em><span class="command"><strong>;</strong></span></pre> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="include_statement"></a><span class="command"><strong>include</strong></span> Statement Definition and Usage</h3></div></div></div> + + <p> + The <span class="command"><strong>include</strong></span> statement inserts the + specified file at the point where the <span class="command"><strong>include</strong></span> + statement is encountered. The <span class="command"><strong>include</strong></span> + statement facilitates the administration of configuration + files + by permitting the reading or writing of some things but not + others. For example, the statement could include private keys + that are readable only by the name server. + </p> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="key_grammar"></a><span class="command"><strong>key</strong></span> Statement Grammar</h3></div></div></div> + <pre class="programlisting"> +<span class="command"><strong>key</strong></span> <em class="replaceable"><code>string</code></em> { + <span class="command"><strong>algorithm</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>secret</strong></span> <em class="replaceable"><code>string</code></em>; +}; +</pre> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="key_statement"></a><span class="command"><strong>key</strong></span> Statement Definition and Usage</h3></div></div></div> + + <p> + The <span class="command"><strong>key</strong></span> statement defines a shared + secret key for use with TSIG (see <a class="xref" href="Bv9ARM.ch04.html#tsig" title="TSIG">the section called “TSIG”</a>) + or the command channel + (see <a class="xref" href="Bv9ARM.ch06.html#controls_statement_definition_and_usage" title="controls Statement Definition and Usage">the section called “<span class="command"><strong>controls</strong></span> Statement Definition and + Usage”</a>). + </p> + + <p> + The <span class="command"><strong>key</strong></span> statement can occur at the + top level + of the configuration file or inside a <span class="command"><strong>view</strong></span> + statement. Keys defined in top-level <span class="command"><strong>key</strong></span> + statements can be used in all views. Keys intended for use in + a <span class="command"><strong>controls</strong></span> statement + (see <a class="xref" href="Bv9ARM.ch06.html#controls_statement_definition_and_usage" title="controls Statement Definition and Usage">the section called “<span class="command"><strong>controls</strong></span> Statement Definition and + Usage”</a>) + must be defined at the top level. + </p> + + <p> + The <em class="replaceable"><code>key_id</code></em>, also known as the + key name, is a domain name uniquely identifying the key. It can + be used in a <span class="command"><strong>server</strong></span> + statement to cause requests sent to that + server to be signed with this key, or in address match lists to + verify that incoming requests have been signed with a key + matching this name, algorithm, and secret. + </p> + + <p> + The <em class="replaceable"><code>algorithm_id</code></em> is a string + that specifies a security/authentication algorithm. The + <span class="command"><strong>named</strong></span> server supports <code class="literal">hmac-md5</code>, + <code class="literal">hmac-sha1</code>, <code class="literal">hmac-sha224</code>, + <code class="literal">hmac-sha256</code>, <code class="literal">hmac-sha384</code> + and <code class="literal">hmac-sha512</code> TSIG authentication. + Truncated hashes are supported by appending the minimum + number of required bits preceded by a dash, e.g. + <code class="literal">hmac-sha1-80</code>. The + <em class="replaceable"><code>secret_string</code></em> is the secret + to be used by the algorithm, and is treated as a Base64 + encoded string. + </p> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="logging_grammar"></a><span class="command"><strong>logging</strong></span> Statement Grammar</h3></div></div></div> + <pre class="programlisting"> +<span class="command"><strong>logging</strong></span> { + <span class="command"><strong>category</strong></span> <em class="replaceable"><code>string</code></em> { <em class="replaceable"><code>string</code></em>; ... }; + <span class="command"><strong>channel</strong></span> <em class="replaceable"><code>string</code></em> { + <span class="command"><strong>buffered</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>file</strong></span> <em class="replaceable"><code>quoted_string</code></em> [ versions ( "unlimited" | <em class="replaceable"><code>integer</code></em> ) + ] [ size <em class="replaceable"><code>size</code></em> ]; + <span class="command"><strong>null</strong></span>; + <span class="command"><strong>print-category</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>print-severity</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>print-time</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>severity</strong></span> <em class="replaceable"><code>log_severity</code></em>; + <span class="command"><strong>stderr</strong></span>; + <span class="command"><strong>syslog</strong></span> [ <em class="replaceable"><code>syslog_facility</code></em> ]; + }; +}; +</pre> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="logging_statement"></a><span class="command"><strong>logging</strong></span> Statement Definition and Usage</h3></div></div></div> + + <p> + The <span class="command"><strong>logging</strong></span> statement configures a + wide + variety of logging options for the name server. Its <span class="command"><strong>channel</strong></span> phrase + associates output methods, format options and severity levels with + a name that can then be used with the <span class="command"><strong>category</strong></span> phrase + to select how various classes of messages are logged. + </p> + <p> + Only one <span class="command"><strong>logging</strong></span> statement is used to + define + as many channels and categories as are wanted. If there is no <span class="command"><strong>logging</strong></span> statement, + the logging configuration will be: + </p> + +<pre class="programlisting">logging { + category default { default_syslog; default_debug; }; + category unmatched { null; }; +}; +</pre> + + <p> + If <span class="command"><strong>named</strong></span> is started with the + <code class="option">-L</code> option, it logs to the specified file + at startup, instead of using syslog. In this case the logging + configuration will be: + </p> + +<pre class="programlisting">logging { + category default { default_logfile; default_debug; }; + category unmatched { null; }; +}; +</pre> + + <p> + In <acronym class="acronym">BIND</acronym> 9, the logging configuration + is only established when + the entire configuration file has been parsed. In <acronym class="acronym">BIND</acronym> 8, it was + established as soon as the <span class="command"><strong>logging</strong></span> + statement + was parsed. When the server is starting up, all logging messages + regarding syntax errors in the configuration file go to the default + channels, or to standard error if the <code class="option">-g</code> option + was specified. + </p> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="channel"></a>The <span class="command"><strong>channel</strong></span> Phrase</h4></div></div></div> + + <p> + All log output goes to one or more <span class="emphasis"><em>channels</em></span>; + you can make as many of them as you want. + </p> + + <p> + Every channel definition must include a destination clause that + says whether messages selected for the channel go to a file, to a + particular syslog facility, to the standard error stream, or are + discarded. It can optionally also limit the message severity level + that will be accepted by the channel (the default is + <span class="command"><strong>info</strong></span>), and whether to include a + <span class="command"><strong>named</strong></span>-generated time stamp, the + category name + and/or severity level (the default is not to include any). + </p> + + <p> + The <span class="command"><strong>null</strong></span> destination clause + causes all messages sent to the channel to be discarded; + in that case, other options for the channel are meaningless. + </p> + + <p> + The <span class="command"><strong>file</strong></span> destination clause directs + the channel + to a disk file. It can include limitations + both on how large the file is allowed to become, and how many + versions + of the file will be saved each time the file is opened. + </p> + + <p> + If you use the <span class="command"><strong>versions</strong></span> log file + option, then + <span class="command"><strong>named</strong></span> will retain that many backup + versions of the file by + renaming them when opening. For example, if you choose to keep + three old versions + of the file <code class="filename">lamers.log</code>, then just + before it is opened + <code class="filename">lamers.log.1</code> is renamed to + <code class="filename">lamers.log.2</code>, <code class="filename">lamers.log.0</code> is renamed + to <code class="filename">lamers.log.1</code>, and <code class="filename">lamers.log</code> is + renamed to <code class="filename">lamers.log.0</code>. + You can say <span class="command"><strong>versions unlimited</strong></span> to + not limit + the number of versions. + If a <span class="command"><strong>size</strong></span> option is associated with + the log file, + then renaming is only done when the file being opened exceeds the + indicated size. No backup versions are kept by default; any + existing + log file is simply appended. + </p> + + <p> + The <span class="command"><strong>size</strong></span> option for files is used + to limit log + growth. If the file ever exceeds the size, then <span class="command"><strong>named</strong></span> will + stop writing to the file unless it has a <span class="command"><strong>versions</strong></span> option + associated with it. If backup versions are kept, the files are + rolled as + described above and a new one begun. If there is no + <span class="command"><strong>versions</strong></span> option, no more data will + be written to the log + until some out-of-band mechanism removes or truncates the log to + less than the + maximum size. The default behavior is not to limit the size of + the + file. + </p> + + <p> + Example usage of the <span class="command"><strong>size</strong></span> and + <span class="command"><strong>versions</strong></span> options: + </p> + +<pre class="programlisting">channel an_example_channel { + file "example.log" versions 3 size 20m; + print-time yes; + print-category yes; +}; +</pre> + + <p> + The <span class="command"><strong>syslog</strong></span> destination clause + directs the + channel to the system log. Its argument is a + syslog facility as described in the <span class="command"><strong>syslog</strong></span> man + page. Known facilities are <span class="command"><strong>kern</strong></span>, <span class="command"><strong>user</strong></span>, + <span class="command"><strong>mail</strong></span>, <span class="command"><strong>daemon</strong></span>, <span class="command"><strong>auth</strong></span>, + <span class="command"><strong>syslog</strong></span>, <span class="command"><strong>lpr</strong></span>, <span class="command"><strong>news</strong></span>, + <span class="command"><strong>uucp</strong></span>, <span class="command"><strong>cron</strong></span>, <span class="command"><strong>authpriv</strong></span>, + <span class="command"><strong>ftp</strong></span>, <span class="command"><strong>local0</strong></span>, <span class="command"><strong>local1</strong></span>, + <span class="command"><strong>local2</strong></span>, <span class="command"><strong>local3</strong></span>, <span class="command"><strong>local4</strong></span>, + <span class="command"><strong>local5</strong></span>, <span class="command"><strong>local6</strong></span> and + <span class="command"><strong>local7</strong></span>, however not all facilities + are supported on + all operating systems. + How <span class="command"><strong>syslog</strong></span> will handle messages + sent to + this facility is described in the <span class="command"><strong>syslog.conf</strong></span> man + page. If you have a system which uses a very old version of <span class="command"><strong>syslog</strong></span> that + only uses two arguments to the <span class="command"><strong>openlog()</strong></span> function, + then this clause is silently ignored. + </p> + <p> + On Windows machines syslog messages are directed to the EventViewer. + </p> + <p> + The <span class="command"><strong>severity</strong></span> clause works like <span class="command"><strong>syslog</strong></span>'s + "priorities", except that they can also be used if you are writing + straight to a file rather than using <span class="command"><strong>syslog</strong></span>. + Messages which are not at least of the severity level given will + not be selected for the channel; messages of higher severity + levels + will be accepted. + </p> + <p> + If you are using <span class="command"><strong>syslog</strong></span>, then the <span class="command"><strong>syslog.conf</strong></span> priorities + will also determine what eventually passes through. For example, + defining a channel facility and severity as <span class="command"><strong>daemon</strong></span> and <span class="command"><strong>debug</strong></span> but + only logging <span class="command"><strong>daemon.warning</strong></span> via <span class="command"><strong>syslog.conf</strong></span> will + cause messages of severity <span class="command"><strong>info</strong></span> and + <span class="command"><strong>notice</strong></span> to + be dropped. If the situation were reversed, with <span class="command"><strong>named</strong></span> writing + messages of only <span class="command"><strong>warning</strong></span> or higher, + then <span class="command"><strong>syslogd</strong></span> would + print all messages it received from the channel. + </p> + + <p> + The <span class="command"><strong>stderr</strong></span> destination clause + directs the + channel to the server's standard error stream. This is intended + for + use when the server is running as a foreground process, for + example + when debugging a configuration. + </p> + + <p> + The server can supply extensive debugging information when + it is in debugging mode. If the server's global debug level is + greater + than zero, then debugging mode will be active. The global debug + level is set either by starting the <span class="command"><strong>named</strong></span> server + with the <code class="option">-d</code> flag followed by a positive integer, + or by running <span class="command"><strong>rndc trace</strong></span>. + The global debug level + can be set to zero, and debugging mode turned off, by running <span class="command"><strong>rndc +notrace</strong></span>. All debugging messages in the server have a debug + level, and higher debug levels give more detailed output. Channels + that specify a specific debug severity, for example: + </p> + +<pre class="programlisting">channel specific_debug_level { + file "foo"; + severity debug 3; +}; +</pre> + + <p> + will get debugging output of level 3 or less any time the + server is in debugging mode, regardless of the global debugging + level. Channels with <span class="command"><strong>dynamic</strong></span> + severity use the + server's global debug level to determine what messages to print. + </p> + <p> + If <span class="command"><strong>print-time</strong></span> has been turned on, + then + the date and time will be logged. <span class="command"><strong>print-time</strong></span> may + be specified for a <span class="command"><strong>syslog</strong></span> channel, + but is usually + pointless since <span class="command"><strong>syslog</strong></span> also logs + the date and + time. If <span class="command"><strong>print-category</strong></span> is + requested, then the + category of the message will be logged as well. Finally, if <span class="command"><strong>print-severity</strong></span> is + on, then the severity level of the message will be logged. The <span class="command"><strong>print-</strong></span> options may + be used in any combination, and will always be printed in the + following + order: time, category, severity. Here is an example where all + three <span class="command"><strong>print-</strong></span> options + are on: + </p> + + <p> + <code class="computeroutput">28-Feb-2000 15:05:32.863 general: notice: running</code> + </p> + + <p> + If <span class="command"><strong>buffered</strong></span> has been turned on the output + to files will not be flushed after each log entry. By default + all log messages are flushed. + </p> + + <p> + There are four predefined channels that are used for + <span class="command"><strong>named</strong></span>'s default logging as follows. + If <span class="command"><strong>named</strong></span> is started with the + <code class="option">-L</code> then a + fifth channel <span class="command"><strong>default_logfile</strong></span> is added. + How they are + used is described in <a class="xref" href="Bv9ARM.ch06.html#the_category_phrase" title="The category Phrase">the section called “The <span class="command"><strong>category</strong></span> Phrase”</a>. + </p> + +<pre class="programlisting">channel default_syslog { + // send to syslog's daemon facility + syslog daemon; + // only send priority info and higher + severity info; +}; + +channel default_debug { + // write to named.run in the working directory + // Note: stderr is used instead of "named.run" if + // the server is started with the '-g' option. + file "named.run"; + // log at the server's current debug level + severity dynamic; +}; + +channel default_stderr { + // writes to stderr + stderr; + // only send priority info and higher + severity info; +}; + +channel null { + // toss anything sent to this channel + null; +}; + +channel default_logfile { + // this channel is only present if named is + // started with the -L option, whose argument + // provides the file name + file "..."; + // log at the server's current debug level + severity dynamic; +}; +</pre> + + <p> + The <span class="command"><strong>default_debug</strong></span> channel has the + special + property that it only produces output when the server's debug + level is + nonzero. It normally writes to a file called <code class="filename">named.run</code> + in the server's working directory. + </p> + + <p> + For security reasons, when the <code class="option">-u</code> + command line option is used, the <code class="filename">named.run</code> file + is created only after <span class="command"><strong>named</strong></span> has + changed to the + new UID, and any debug output generated while <span class="command"><strong>named</strong></span> is + starting up and still running as root is discarded. If you need + to capture this output, you must run the server with the <code class="option">-L</code> + option to specify a default logfile, or the <code class="option">-g</code> + option to log to standard error which you can redirect to a file. + </p> + + <p> + Once a channel is defined, it cannot be redefined. Thus you + cannot alter the built-in channels directly, but you can modify + the default logging by pointing categories at channels you have + defined. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="the_category_phrase"></a>The <span class="command"><strong>category</strong></span> Phrase</h4></div></div></div> + + <p> + There are many categories, so you can send the logs you want + to see wherever you want, without seeing logs you don't want. If + you don't specify a list of channels for a category, then log + messages + in that category will be sent to the <span class="command"><strong>default</strong></span> category + instead. If you don't specify a default category, the following + "default default" is used: + </p> + +<pre class="programlisting">category default { default_syslog; default_debug; }; +</pre> + + <p> + If you start <span class="command"><strong>named</strong></span> with the + <code class="option">-L</code> option then the default category is: + </p> + +<pre class="programlisting">category default { default_logfile; default_debug; }; +</pre> + + <p> + As an example, let's say you want to log security events to + a file, but you also want keep the default logging behavior. You'd + specify the following: + </p> + +<pre class="programlisting">channel my_security_channel { + file "my_security_file"; + severity info; +}; +category security { + my_security_channel; + default_syslog; + default_debug; +};</pre> + + <p> + To discard all messages in a category, specify the <span class="command"><strong>null</strong></span> channel: + </p> + +<pre class="programlisting">category xfer-out { null; }; +category notify { null; }; +</pre> + + <p> + Following are the available categories and brief descriptions + of the types of log information they contain. More + categories may be added in future <acronym class="acronym">BIND</acronym> releases. + </p> + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.150in" class="1"> +<col width="3.350in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p><span class="command"><strong>client</strong></span></p> + </td> +<td> + <p> + Processing of client requests. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>cname</strong></span></p> + </td> +<td> + <p> + Logs nameservers that are skipped due to them being + a CNAME rather than A / AAAA records. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>config</strong></span></p> + </td> +<td> + <p> + Configuration file parsing and processing. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>database</strong></span></p> + </td> +<td> + <p> + Messages relating to the databases used + internally by the name server to store zone and cache + data. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>default</strong></span></p> + </td> +<td> + <p> + The default category defines the logging + options for those categories where no specific + configuration has been + defined. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>delegation-only</strong></span></p> + </td> +<td> + <p> + Delegation only. Logs queries that have been + forced to NXDOMAIN as the result of a + delegation-only zone or a + <span class="command"><strong>delegation-only</strong></span> in a + forward, hint or stub zone declaration. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>dispatch</strong></span></p> + </td> +<td> + <p> + Dispatching of incoming packets to the + server modules where they are to be processed. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>dnssec</strong></span></p> + </td> +<td> + <p> + DNSSEC and TSIG protocol processing. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>dnstap</strong></span></p> + </td> +<td> + <p> + The "dnstap" DNS traffic capture system. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>edns-disabled</strong></span></p> + </td> +<td> + <p> + Log queries that have been forced to use plain + DNS due to timeouts. This is often due to + the remote servers not being RFC 1034 compliant + (not always returning FORMERR or similar to + EDNS queries and other extensions to the DNS + when they are not understood). In other words, this is + targeted at servers that fail to respond to + DNS queries that they don't understand. + </p> + <p> + Note: the log message can also be due to + packet loss. Before reporting servers for + non-RFC 1034 compliance they should be re-tested + to determine the nature of the non-compliance. + This testing should prevent or reduce the + number of false-positive reports. + </p> + <p> + Note: eventually <span class="command"><strong>named</strong></span> will have to stop + treating such timeouts as due to RFC 1034 non + compliance and start treating it as plain + packet loss. Falsely classifying packet + loss as due to RFC 1034 non compliance impacts + on DNSSEC validation which requires EDNS for + the DNSSEC records to be returned. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>general</strong></span></p> + </td> +<td> + <p> + The catch-all. Many things still aren't + classified into categories, and they all end up here. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>lame-servers</strong></span></p> + </td> +<td> + <p> + Lame servers. These are misconfigurations + in remote servers, discovered by BIND 9 when trying to + query those servers during resolution. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>network</strong></span></p> + </td> +<td> + <p> + Network operations. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>notify</strong></span></p> + </td> +<td> + <p> + The NOTIFY protocol. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>queries</strong></span></p> + </td> +<td> + <p> + Specify where queries should be logged to. + </p> + <p> + At startup, specifying the category <span class="command"><strong>queries</strong></span> will also + enable query logging unless <span class="command"><strong>querylog</strong></span> option has been + specified. + </p> + + <p> + The query log entry first reports a client object + identifier in @0x<hexadecimal-number> + format. Next, it reports the client's IP + address and port number, and the query name, + class and type. Next, it reports whether the + Recursion Desired flag was set (+ if set, - + if not set), if the query was signed (S), + EDNS was in used along with the EDNS version + number (E(#)), if TCP was used (T), if DO + (DNSSEC Ok) was set (D), if CD (Checking + Disabled) was set (C), if a valid DNS Server + COOKIE was received (V), or if a DNS COOKIE + option without a valid Server COOKIE was + present (K). After this the destination + address the query was sent to is reported. + </p> + + <p> + <code class="computeroutput">client 127.0.0.1#62536 (www.example.com): query: www.example.com IN AAAA +SE</code> + </p> + <p> + <code class="computeroutput">client ::1#62537 (www.example.net): query: www.example.net IN AAAA -SE</code> + </p> + <p> + (The first part of this log message, showing the + client address/port number and query name, is + repeated in all subsequent log messages related + to the same query.) + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>query-errors</strong></span></p> + </td> +<td> + <p> + Information about queries that resulted in some + failure. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>rate-limit</strong></span></p> + </td> +<td> + <p> + The start, periodic, and final notices of the + rate limiting of a stream of responses are logged at + <span class="command"><strong>info</strong></span> severity in this category. + These messages include a hash value of the domain name + of the response and the name itself, + except when there is insufficient memory to record + the name for the final notice + The final notice is normally delayed until about one + minute after rate limit stops. + A lack of memory can hurry the final notice, + in which case it starts with an asterisk (*). + Various internal events are logged at debug 1 level + and higher. + </p> + <p> + Rate limiting of individual requests + is logged in the <span class="command"><strong>query-errors</strong></span> category. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>resolver</strong></span></p> + </td> +<td> + <p> + DNS resolution, such as the recursive + lookups performed on behalf of clients by a caching name + server. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>rpz</strong></span></p> + </td> +<td> + <p> + Information about errors in response policy zone files, + rewritten responses, and at the highest + <span class="command"><strong>debug</strong></span> levels, mere rewriting + attempts. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>security</strong></span></p> + </td> +<td> + <p> + Approval and denial of requests. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>spill</strong></span></p> + </td> +<td> + <p> + Logs queries that have been terminated, either by dropping + or responding with SERVFAIL, as a result of a fetchlimit + quota being exceeded. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>trust-anchor-telemetry</strong></span></p> + </td> +<td> + <p> + Logs trust-anchor-telemetry requests received by named. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>unmatched</strong></span></p> + </td> +<td> + <p> + Messages that <span class="command"><strong>named</strong></span> was unable to determine the + class of or for which there was no matching <span class="command"><strong>view</strong></span>. + A one line summary is also logged to the <span class="command"><strong>client</strong></span> category. + This category is best sent to a file or stderr, by + default it is sent to + the <span class="command"><strong>null</strong></span> channel. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>update</strong></span></p> + </td> +<td> + <p> + Dynamic updates. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>update-security</strong></span></p> + </td> +<td> + <p> + Approval and denial of update requests. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>xfer-in</strong></span></p> + </td> +<td> + <p> + Zone transfers the server is receiving. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>xfer-out</strong></span></p> + </td> +<td> + <p> + Zone transfers the server is sending. + </p> + </td> +</tr> +</tbody> +</table> +</div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="query_errors"></a>The <span class="command"><strong>query-errors</strong></span> Category</h4></div></div></div> + <p> + The <span class="command"><strong>query-errors</strong></span> category is + specifically intended for debugging purposes: To identify + why and how specific queries result in responses which + indicate an error. + Messages of this category are therefore only logged + with <span class="command"><strong>debug</strong></span> levels. + </p> + + <p> + At the debug levels of 1 or higher, each response with the + rcode of SERVFAIL is logged as follows: + </p> + <p> + <code class="computeroutput">client 127.0.0.1#61502: query failed (SERVFAIL) for www.example.com/IN/AAAA at query.c:3880</code> + </p> + <p> + This means an error resulting in SERVFAIL was + detected at line 3880 of source file + <code class="filename">query.c</code>. + Log messages of this level will particularly + help identify the cause of SERVFAIL for an + authoritative server. + </p> + <p> + At the debug levels of 2 or higher, detailed context + information of recursive resolutions that resulted in + SERVFAIL is logged. + The log message will look like as follows: + </p> + <p> + + </p> +<pre class="programlisting"> +fetch completed at resolver.c:2970 for www.example.com/A +in 30.000183: timed out/success [domain:example.com, +referral:2,restart:7,qrysent:8,timeout:5,lame:0,neterr:0, +badresp:1,adberr:0,findfail:0,valfail:0] + </pre> +<p> + </p> + <p> + The first part before the colon shows that a recursive + resolution for AAAA records of www.example.com completed + in 30.000183 seconds and the final result that led to the + SERVFAIL was determined at line 2970 of source file + <code class="filename">resolver.c</code>. + </p> + <p> + The following part shows the detected final result and the + latest result of DNSSEC validation. + The latter is always success when no validation attempt + is made. + In this example, this query resulted in SERVFAIL probably + because all name servers are down or unreachable, leading + to a timeout in 30 seconds. + DNSSEC validation was probably not attempted. + </p> + <p> + The last part enclosed in square brackets shows statistics + information collected for this particular resolution + attempt. + The <code class="varname">domain</code> field shows the deepest zone + that the resolver reached; + it is the zone where the error was finally detected. + The meaning of the other fields is summarized in the + following table. + </p> + + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.150in" class="1"> +<col width="3.350in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p><code class="varname">referral</code></p> + </td> +<td> + <p> + The number of referrals the resolver received + throughout the resolution process. + In the above example this is 2, which are most + likely com and example.com. + </p> + </td> +</tr> +<tr> +<td> + <p><code class="varname">restart</code></p> + </td> +<td> + <p> + The number of cycles that the resolver tried + remote servers at the <code class="varname">domain</code> + zone. + In each cycle the resolver sends one query + (possibly resending it, depending on the response) + to each known name server of + the <code class="varname">domain</code> zone. + </p> + </td> +</tr> +<tr> +<td> + <p><code class="varname">qrysent</code></p> + </td> +<td> + <p> + The number of queries the resolver sent at the + <code class="varname">domain</code> zone. + </p> + </td> +</tr> +<tr> +<td> + <p><code class="varname">timeout</code></p> + </td> +<td> + <p> + The number of timeouts since the resolver + received the last response. + </p> + </td> +</tr> +<tr> +<td> + <p><code class="varname">lame</code></p> + </td> +<td> + <p> + The number of lame servers the resolver detected + at the <code class="varname">domain</code> zone. + A server is detected to be lame either by an + invalid response or as a result of lookup in + BIND9's address database (ADB), where lame + servers are cached. + </p> + </td> +</tr> +<tr> +<td> + <p><code class="varname">neterr</code></p> + </td> +<td> + <p> + The number of erroneous results that the + resolver encountered in sending queries + at the <code class="varname">domain</code> zone. + One common case is the remote server is + unreachable and the resolver receives an ICMP + unreachable error message. + </p> + </td> +</tr> +<tr> +<td> + <p><code class="varname">badresp</code></p> + </td> +<td> + <p> + The number of unexpected responses (other than + <code class="varname">lame</code>) to queries sent by the + resolver at the <code class="varname">domain</code> zone. + </p> + </td> +</tr> +<tr> +<td> + <p><code class="varname">adberr</code></p> + </td> +<td> + <p> + Failures in finding remote server addresses + of the <code class="varname">domain</code> zone in the ADB. + One common case of this is that the remote + server's name does not have any address records. + </p> + </td> +</tr> +<tr> +<td> + <p><code class="varname">findfail</code></p> + </td> +<td> + <p> + Failures of resolving remote server addresses. + This is a total number of failures throughout + the resolution process. + </p> + </td> +</tr> +<tr> +<td> + <p><code class="varname">valfail</code></p> + </td> +<td> + <p> + Failures of DNSSEC validation. + Validation failures are counted throughout + the resolution process (not limited to + the <code class="varname">domain</code> zone), but should + only happen in <code class="varname">domain</code>. + </p> + </td> +</tr> +</tbody> +</table> + </div> + <p> + At the debug levels of 3 or higher, the same messages + as those at the debug 1 level are logged for other errors + than SERVFAIL. + Note that negative responses such as NXDOMAIN are not + regarded as errors here. + </p> + <p> + At the debug levels of 4 or higher, the same messages + as those at the debug 2 level are logged for other errors + than SERVFAIL. + Unlike the above case of level 3, messages are logged for + negative responses. + This is because any unexpected results can be difficult to + debug in the recursion case. + </p> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="lwres_grammar"></a><span class="command"><strong>lwres</strong></span> Statement Grammar</h3></div></div></div> + + <p> + This is the grammar of the <span class="command"><strong>lwres</strong></span> + statement in the <code class="filename">named.conf</code> file: + </p> + +<pre class="programlisting"><span class="command"><strong>lwres {</strong></span> + [ <span class="command"><strong>listen-on {</strong></span> + ( <em class="replaceable"><code>ip_addr</code></em> [ <span class="command"><strong>port</strong></span> <em class="replaceable"><code>ip_port</code></em> ] [ <span class="command"><strong>dscp</strong></span> <em class="replaceable"><code>ip_dscp</code></em> ] <span class="command"><strong>;</strong></span> ) + ... + <span class="command"><strong>};</strong></span> ] + [ <span class="command"><strong>view</strong></span> <em class="replaceable"><code>view_name</code></em><span class="command"><strong>;</strong></span> ] + [ <span class="command"><strong>search {</strong></span> <em class="replaceable"><code>domain_name</code></em> <span class="command"><strong>;</strong></span> ... <span class="command"><strong>};</strong></span> ] + [ <span class="command"><strong>ndots</strong></span> <em class="replaceable"><code>number</code></em><span class="command"><strong>;</strong></span> ] + [ <span class="command"><strong>lwres-tasks</strong></span> <em class="replaceable"><code>number</code></em><span class="command"><strong>;</strong></span> ] + [ <span class="command"><strong>lwres-clients</strong></span> <em class="replaceable"><code>number</code></em><span class="command"><strong>;</strong></span> ] +<span class="command"><strong>};</strong></span> +</pre> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="lwres_statement"></a><span class="command"><strong>lwres</strong></span> Statement Definition and Usage</h3></div></div></div> + + <p> + The <span class="command"><strong>lwres</strong></span> statement configures the + name + server to also act as a lightweight resolver server. (See + <a class="xref" href="Bv9ARM.ch05.html#lwresd" title="Running a Resolver Daemon">the section called “Running a Resolver Daemon”</a>.) There may be multiple + <span class="command"><strong>lwres</strong></span> statements configuring + lightweight resolver servers with different properties. + </p> + + <p> + The <span class="command"><strong>listen-on</strong></span> statement specifies a + list of + IPv4 addresses (and ports) that this instance of a lightweight + resolver daemon + should accept requests on. If no port is specified, port 921 is + used. + If this statement is omitted, requests will be accepted on + 127.0.0.1, + port 921. + </p> + + <p> + The <span class="command"><strong>view</strong></span> statement binds this + instance of a + lightweight resolver daemon to a view in the DNS namespace, so that + the + response will be constructed in the same manner as a normal DNS + query + matching this view. If this statement is omitted, the default view + is + used, and if there is no default view, an error is triggered. + </p> + + <p> + The <span class="command"><strong>search</strong></span> statement is equivalent to + the + <span class="command"><strong>search</strong></span> statement in + <code class="filename">/etc/resolv.conf</code>. It provides a + list of domains + which are appended to relative names in queries. + </p> + + <p> + The <span class="command"><strong>ndots</strong></span> statement is equivalent to + the + <span class="command"><strong>ndots</strong></span> statement in + <code class="filename">/etc/resolv.conf</code>. It indicates the + minimum + number of dots in a relative domain name that should result in an + exact match lookup before search path elements are appended. + </p> + <p> + The <code class="option">lwres-tasks</code> statement specifies the number + of worker threads the lightweight resolver will dedicate to serving + clients. By default the number is the same as the number of CPUs on + the system; this can be overridden using the <code class="option">-n</code> + command line option when starting the server. + </p> + <p> + The <code class="option">lwres-clients</code> specifies + the number of client objects per thread the lightweight + resolver should create to serve client queries. + By default, if the lightweight resolver runs as a part + of <span class="command"><strong>named</strong></span>, 256 client objects are + created for each task; if it runs as <span class="command"><strong>lwresd</strong></span>, + 1024 client objects are created for each thread. The maximum + value is 32768; higher values will be silently ignored and + the maximum will be used instead. + Note that setting too high a value may overconsume + system resources. + </p> + <p> + The maximum number of client queries that the lightweight + resolver can handle at any one time equals + <code class="option">lwres-tasks</code> times <code class="option">lwres-clients</code>. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="masters_grammar"></a><span class="command"><strong>masters</strong></span> Statement Grammar</h3></div></div></div> + <pre class="programlisting"> +<span class="command"><strong>masters</strong></span> <em class="replaceable"><code>string</code></em> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp + <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>masters</code></em> | <em class="replaceable"><code>ipv4_address</code></em> [ + <span class="command"><strong>port</strong></span> <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port + <em class="replaceable"><code>integer</code></em> ] ) [ key <em class="replaceable"><code>string</code></em> ]; ... }; +</pre> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="masters_statement"></a><span class="command"><strong>masters</strong></span> Statement Definition and + Usage</h3></div></div></div> + + <p><span class="command"><strong>masters</strong></span> + lists allow for a common set of masters to be easily used by + multiple stub and slave zones in their <span class="command"><strong>masters</strong></span> + or <span class="command"><strong>also-notify</strong></span> lists. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="options_grammar"></a><span class="command"><strong>options</strong></span> Statement Grammar</h3></div></div></div> + + <p> + This is the grammar of the <span class="command"><strong>options</strong></span> + statement in the <code class="filename">named.conf</code> file: + </p> + <pre class="programlisting"> +<span class="command"><strong>options</strong></span> { + <span class="command"><strong>acache-cleaning-interval</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>acache-enable</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>additional-from-auth</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>additional-from-cache</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>allow-new-zones</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>allow-notify</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-query</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-query-cache</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-query-cache-on</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-query-on</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-recursion</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-recursion-on</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-transfer</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-update</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-update-forwarding</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>also-notify</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>masters</code></em> | + <em class="replaceable"><code>ipv4_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port + <em class="replaceable"><code>integer</code></em> ] ) [ key <em class="replaceable"><code>string</code></em> ]; ... }; + <span class="command"><strong>alt-transfer-source</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) + ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>alt-transfer-source-v6</strong></span> ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | + * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>answer-cookie</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>attach-cache</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>auth-nxdomain</strong></span> <em class="replaceable"><code>boolean</code></em>; // default changed + <span class="command"><strong>auto-dnssec</strong></span> ( allow | maintain | off ); + <span class="command"><strong>automatic-interface-scan</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>avoid-v4-udp-ports</strong></span> { <em class="replaceable"><code>portrange</code></em>; ... }; + <span class="command"><strong>avoid-v6-udp-ports</strong></span> { <em class="replaceable"><code>portrange</code></em>; ... }; + <span class="command"><strong>bindkeys-file</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>blackhole</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>cache-file</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>catalog-zones</strong></span> { zone <em class="replaceable"><code>quoted_string</code></em> [ default-masters [ port + <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>masters</code></em> | <em class="replaceable"><code>ipv4_address</code></em> [ + <span class="command"><strong>port</strong></span> <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] ) [ key + <em class="replaceable"><code>string</code></em> ]; ... } ] [ zone-directory <em class="replaceable"><code>quoted_string</code></em> ] [ + <span class="command"><strong>in-memory</strong></span> <em class="replaceable"><code>boolean</code></em> ] [ min-update-interval <em class="replaceable"><code>integer</code></em> ]; ... }; + <span class="command"><strong>check-dup-records</strong></span> ( fail | warn | ignore ); + <span class="command"><strong>check-integrity</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>check-mx</strong></span> ( fail | warn | ignore ); + <span class="command"><strong>check-mx-cname</strong></span> ( fail | warn | ignore ); + <span class="command"><strong>check-names</strong></span> ( master | slave | response + ) ( fail | warn | ignore ); + <span class="command"><strong>check-sibling</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>check-spf</strong></span> ( warn | ignore ); + <span class="command"><strong>check-srv-cname</strong></span> ( fail | warn | ignore ); + <span class="command"><strong>check-wildcard</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>cleaning-interval</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>clients-per-query</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>cookie-algorithm</strong></span> ( aes | sha1 | sha256 ); + <span class="command"><strong>cookie-secret</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>coresize</strong></span> ( default | unlimited | <em class="replaceable"><code>sizeval</code></em> ); + <span class="command"><strong>datasize</strong></span> ( default | unlimited | <em class="replaceable"><code>sizeval</code></em> ); + <span class="command"><strong>deny-answer-addresses</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... } [ + <span class="command"><strong>except-from</strong></span> { <em class="replaceable"><code>quoted_string</code></em>; ... } ]; + <span class="command"><strong>deny-answer-aliases</strong></span> { <em class="replaceable"><code>quoted_string</code></em>; ... } [ except-from { + <em class="replaceable"><code>quoted_string</code></em>; ... } ]; + <span class="command"><strong>dialup</strong></span> ( notify | notify-passive | passive | refresh | <em class="replaceable"><code>boolean</code></em> ); + <span class="command"><strong>directory</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>disable-algorithms</strong></span> <em class="replaceable"><code>string</code></em> { <em class="replaceable"><code>string</code></em>; + ... }; + <span class="command"><strong>disable-ds-digests</strong></span> <em class="replaceable"><code>string</code></em> { <em class="replaceable"><code>string</code></em>; + ... }; + <span class="command"><strong>disable-empty-zone</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>dns64</strong></span> <em class="replaceable"><code>netprefix</code></em> { + <span class="command"><strong>break-dnssec</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>clients</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>exclude</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>mapped</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>recursive-only</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>suffix</strong></span> <em class="replaceable"><code>ipv6_address</code></em>; + }; + <span class="command"><strong>dns64-contact</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>dns64-server</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>dnssec-accept-expired</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>dnssec-dnskey-kskonly</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>dnssec-enable</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>dnssec-loadkeys-interval</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>dnssec-lookaside</strong></span> ( <em class="replaceable"><code>string</code></em> trust-anchor + <em class="replaceable"><code>string</code></em> | auto | no ); + <span class="command"><strong>dnssec-must-be-secure</strong></span> <em class="replaceable"><code>string</code></em> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>dnssec-secure-to-insecure</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>dnssec-update-mode</strong></span> ( maintain | no-resign ); + <span class="command"><strong>dnssec-validation</strong></span> ( yes | no | auto ); + <span class="command"><strong>dnstap</strong></span> { ( all | auth | client | forwarder | + <span class="command"><strong>resolver</strong></span> ) [ ( query | response ) ]; ... }; + <span class="command"><strong>dnstap-identity</strong></span> ( <em class="replaceable"><code>quoted_string</code></em> | none | + <span class="command"><strong>hostname</strong></span> ); + <span class="command"><strong>dnstap-output</strong></span> ( file | unix ) <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>dnstap-version</strong></span> ( <em class="replaceable"><code>quoted_string</code></em> | none ); + <span class="command"><strong>dscp</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>dual-stack-servers</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>quoted_string</code></em> [ port + <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv4_address</code></em> [ port + <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port + <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] ); ... }; + <span class="command"><strong>dump-file</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>edns-udp-size</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>empty-contact</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>empty-server</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>empty-zones-enable</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>fetch-quota-params</strong></span> <em class="replaceable"><code>integer</code></em> <em class="replaceable"><code>fixedpoint</code></em> <em class="replaceable"><code>fixedpoint</code></em> <em class="replaceable"><code>fixedpoint</code></em>; + <span class="command"><strong>fetches-per-server</strong></span> <em class="replaceable"><code>integer</code></em> [ ( drop | fail ) ]; + <span class="command"><strong>fetches-per-zone</strong></span> <em class="replaceable"><code>integer</code></em> [ ( drop | fail ) ]; + <span class="command"><strong>files</strong></span> ( default | unlimited | <em class="replaceable"><code>sizeval</code></em> ); + <span class="command"><strong>filter-aaaa</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>filter-aaaa-on-v4</strong></span> ( break-dnssec | <em class="replaceable"><code>boolean</code></em> ); + <span class="command"><strong>filter-aaaa-on-v6</strong></span> ( break-dnssec | <em class="replaceable"><code>boolean</code></em> ); + <span class="command"><strong>flush-zones-on-shutdown</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>forward</strong></span> ( first | only ); + <span class="command"><strong>forwarders</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>ipv4_address</code></em> + | <em class="replaceable"><code>ipv6_address</code></em> ) [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ]; ... }; + <span class="command"><strong>fstrm-set-buffer-hint</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>fstrm-set-flush-timeout</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>fstrm-set-input-queue-size</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>fstrm-set-output-notify-threshold</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>fstrm-set-output-queue-model</strong></span> ( mpsc | spsc ); + <span class="command"><strong>fstrm-set-output-queue-size</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>fstrm-set-reopen-interval</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>geoip-directory</strong></span> ( <em class="replaceable"><code>quoted_string</code></em> | none ); + <span class="command"><strong>geoip-use-ecs</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>heartbeat-interval</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>hostname</strong></span> ( <em class="replaceable"><code>quoted_string</code></em> | none ); + <span class="command"><strong>inline-signing</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>interface-interval</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>ixfr-from-differences</strong></span> ( master | slave | <em class="replaceable"><code>boolean</code></em> ); + <span class="command"><strong>keep-response-order</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>key-directory</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>lame-ttl</strong></span> <em class="replaceable"><code>ttlval</code></em>; + <span class="command"><strong>listen-on</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp + <em class="replaceable"><code>integer</code></em> ] { + <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>listen-on-v6</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp + <em class="replaceable"><code>integer</code></em> ] { + <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>lmdb-mapsize</strong></span> <em class="replaceable"><code>sizeval</code></em>; + <span class="command"><strong>lock-file</strong></span> ( <em class="replaceable"><code>quoted_string</code></em> | none ); + <span class="command"><strong>managed-keys-directory</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>masterfile-format</strong></span> ( map | raw | text ); + <span class="command"><strong>masterfile-style</strong></span> ( full | relative ); + <span class="command"><strong>match-mapped-addresses</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>max-acache-size</strong></span> ( unlimited | <em class="replaceable"><code>sizeval</code></em> ); + <span class="command"><strong>max-cache-size</strong></span> ( default | unlimited | <em class="replaceable"><code>sizeval</code></em> | <em class="replaceable"><code>percentage</code></em> ); + <span class="command"><strong>max-cache-ttl</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-clients-per-query</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-journal-size</strong></span> ( unlimited | <em class="replaceable"><code>sizeval</code></em> ); + <span class="command"><strong>max-ncache-ttl</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-records</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-recursion-depth</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-recursion-queries</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-refresh-time</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-retry-time</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-rsa-exponent-size</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-transfer-idle-in</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-transfer-idle-out</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-transfer-time-in</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-transfer-time-out</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-udp-size</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-zone-ttl</strong></span> ( unlimited | <em class="replaceable"><code>ttlval</code></em> ); + <span class="command"><strong>memstatistics</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>memstatistics-file</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>message-compression</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>min-refresh-time</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>min-retry-time</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>minimal-any</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>minimal-responses</strong></span> ( no-auth | no-auth-recursive | <em class="replaceable"><code>boolean</code></em> ); + <span class="command"><strong>multi-master</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>no-case-compress</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>nocookie-udp-size</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>notify</strong></span> ( explicit | master-only | <em class="replaceable"><code>boolean</code></em> ); + <span class="command"><strong>notify-delay</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>notify-rate</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>notify-source</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ + <span class="command"><strong>dscp</strong></span> <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>notify-source-v6</strong></span> ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] + [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>notify-to-soa</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>nta-lifetime</strong></span> <em class="replaceable"><code>ttlval</code></em>; + <span class="command"><strong>nta-recheck</strong></span> <em class="replaceable"><code>ttlval</code></em>; + <span class="command"><strong>nxdomain-redirect</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>pid-file</strong></span> ( <em class="replaceable"><code>quoted_string</code></em> | none ); + <span class="command"><strong>port</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>preferred-glue</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>prefetch</strong></span> <em class="replaceable"><code>integer</code></em> [ <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>provide-ixfr</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>query-source</strong></span> ( ( [ address ] ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( + <em class="replaceable"><code>integer</code></em> | * ) ] ) | ( [ [ address ] ( <em class="replaceable"><code>ipv4_address</code></em> | * ) ] + <span class="command"><strong>port</strong></span> ( <em class="replaceable"><code>integer</code></em> | * ) ) ) [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>query-source-v6</strong></span> ( ( [ address ] ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( + <em class="replaceable"><code>integer</code></em> | * ) ] ) | ( [ [ address ] ( <em class="replaceable"><code>ipv6_address</code></em> | * ) ] + <span class="command"><strong>port</strong></span> ( <em class="replaceable"><code>integer</code></em> | * ) ) ) [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>querylog</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>random-device</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>rate-limit</strong></span> { + <span class="command"><strong>all-per-second</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>errors-per-second</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>exempt-clients</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>ipv4-prefix-length</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>ipv6-prefix-length</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>log-only</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>max-table-size</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>min-table-size</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>nodata-per-second</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>nxdomains-per-second</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>qps-scale</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>referrals-per-second</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>responses-per-second</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>slip</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>window</strong></span> <em class="replaceable"><code>integer</code></em>; + }; + <span class="command"><strong>recursing-file</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>recursion</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>recursive-clients</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>request-expire</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>request-ixfr</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>request-nsid</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>require-server-cookie</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>reserved-sockets</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>resolver-query-timeout</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>response-policy</strong></span> { zone <em class="replaceable"><code>quoted_string</code></em> [ log <em class="replaceable"><code>boolean</code></em> ] [ + <span class="command"><strong>max-policy-ttl</strong></span> <em class="replaceable"><code>integer</code></em> ] [ policy ( cname | disabled | drop | + <span class="command"><strong>given</strong></span> | no-op | nodata | nxdomain | passthru | tcp-only + <em class="replaceable"><code>quoted_string</code></em> ) ] [ recursive-only <em class="replaceable"><code>boolean</code></em> ]; ... } [ + <span class="command"><strong>break-dnssec</strong></span> <em class="replaceable"><code>boolean</code></em> ] [ max-policy-ttl <em class="replaceable"><code>integer</code></em> ] [ + <span class="command"><strong>min-ns-dots</strong></span> <em class="replaceable"><code>integer</code></em> ] [ nsip-wait-recurse <em class="replaceable"><code>boolean</code></em> ] [ + <span class="command"><strong>qname-wait-recurse</strong></span> <em class="replaceable"><code>boolean</code></em> ] [ recursive-only <em class="replaceable"><code>boolean</code></em> ]; + <span class="command"><strong>root-delegation-only</strong></span> [ exclude { <em class="replaceable"><code>quoted_string</code></em>; ... } ]; + <span class="command"><strong>root-key-sentinel</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>rrset-order</strong></span> { [ class <em class="replaceable"><code>string</code></em> ] [ type <em class="replaceable"><code>string</code></em> ] [ name + <em class="replaceable"><code>quoted_string</code></em> ] <em class="replaceable"><code>string</code></em> <em class="replaceable"><code>string</code></em>; ... }; + <span class="command"><strong>secroots-file</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>send-cookie</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>serial-query-rate</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>serial-update-method</strong></span> ( date | increment | unixtime ); + <span class="command"><strong>server-id</strong></span> ( <em class="replaceable"><code>quoted_string</code></em> | none | hostname ); + <span class="command"><strong>servfail-ttl</strong></span> <em class="replaceable"><code>ttlval</code></em>; + <span class="command"><strong>session-keyalg</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>session-keyfile</strong></span> ( <em class="replaceable"><code>quoted_string</code></em> | none ); + <span class="command"><strong>session-keyname</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>sig-signing-nodes</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>sig-signing-signatures</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>sig-signing-type</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>sig-validity-interval</strong></span> <em class="replaceable"><code>integer</code></em> [ <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>sortlist</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>stacksize</strong></span> ( default | unlimited | <em class="replaceable"><code>sizeval</code></em> ); + <span class="command"><strong>startup-notify-rate</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>statistics-file</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>tcp-clients</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>tcp-listen-queue</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>tkey-dhkey</strong></span> <em class="replaceable"><code>quoted_string</code></em> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>tkey-domain</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>tkey-gssapi-credential</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>tkey-gssapi-keytab</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>transfer-format</strong></span> ( many-answers | one-answer ); + <span class="command"><strong>transfer-message-size</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>transfer-source</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ + <span class="command"><strong>dscp</strong></span> <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>transfer-source-v6</strong></span> ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) + ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>transfers-in</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>transfers-out</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>transfers-per-ns</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>trust-anchor-telemetry</strong></span> <em class="replaceable"><code>boolean</code></em>; // experimental + <span class="command"><strong>try-tcp-refresh</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>update-check-ksk</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>use-alt-transfer-source</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>use-v4-udp-ports</strong></span> { <em class="replaceable"><code>portrange</code></em>; ... }; + <span class="command"><strong>use-v6-udp-ports</strong></span> { <em class="replaceable"><code>portrange</code></em>; ... }; + <span class="command"><strong>v6-bias</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>version</strong></span> ( <em class="replaceable"><code>quoted_string</code></em> | none ); + <span class="command"><strong>zero-no-soa-ttl</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>zero-no-soa-ttl-cache</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>zone-statistics</strong></span> ( full | terse | none | <em class="replaceable"><code>boolean</code></em> ); +}; +</pre> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="options"></a><span class="command"><strong>options</strong></span> Statement Definition and + Usage</h3></div></div></div> + + <p> + The <span class="command"><strong>options</strong></span> statement sets up global + options + to be used by <acronym class="acronym">BIND</acronym>. This statement + may appear only + once in a configuration file. If there is no <span class="command"><strong>options</strong></span> + statement, an options block with each option set to its default will + be used. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>attach-cache</strong></span></span></dt> +<dd> + <p> + Allows multiple views to share a single cache + database. + Each view has its own cache database by default, but + if multiple views have the same operational policy + for name resolution and caching, those views can + share a single cache to save memory and possibly + improve resolution efficiency by using this option. + </p> + + <p> + The <span class="command"><strong>attach-cache</strong></span> option + may also be specified in <span class="command"><strong>view</strong></span> + statements, in which case it overrides the + global <span class="command"><strong>attach-cache</strong></span> option. + </p> + + <p> + The <em class="replaceable"><code>cache_name</code></em> specifies + the cache to be shared. + When the <span class="command"><strong>named</strong></span> server configures + views which are supposed to share a cache, it + creates a cache with the specified name for the + first view of these sharing views. + The rest of the views will simply refer to the + already created cache. + </p> + + <p> + One common configuration to share a cache would be to + allow all views to share a single cache. + This can be done by specifying + the <span class="command"><strong>attach-cache</strong></span> as a global + option with an arbitrary name. + </p> + + <p> + Another possible operation is to allow a subset of + all views to share a cache while the others to + retain their own caches. + For example, if there are three views A, B, and C, + and only A and B should share a cache, specify the + <span class="command"><strong>attach-cache</strong></span> option as a view A (or + B)'s option, referring to the other view name: + </p> + +<pre class="programlisting"> + view "A" { + // this view has its own cache + ... + }; + view "B" { + // this view refers to A's cache + attach-cache "A"; + }; + view "C" { + // this view has its own cache + ... + }; +</pre> + + <p> + Views that share a cache must have the same policy + on configurable parameters that may affect caching. + The current implementation requires the following + configurable options be consistent among these + views: + <span class="command"><strong>check-names</strong></span>, + <span class="command"><strong>cleaning-interval</strong></span>, + <span class="command"><strong>dnssec-accept-expired</strong></span>, + <span class="command"><strong>dnssec-validation</strong></span>, + <span class="command"><strong>max-cache-ttl</strong></span>, + <span class="command"><strong>max-ncache-ttl</strong></span>, + <span class="command"><strong>max-cache-size</strong></span>, and + <span class="command"><strong>zero-no-soa-ttl</strong></span>. + </p> + + <p> + Note that there may be other parameters that may + cause confusion if they are inconsistent for + different views that share a single cache. + For example, if these views define different sets of + forwarders that can return different answers for the + same question, sharing the answer does not make + sense or could even be harmful. + It is administrator's responsibility to ensure + configuration differences in different views do + not cause disruption with a shared cache. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>directory</strong></span></span></dt> +<dd> + <p> + The working directory of the server. + Any non-absolute pathnames in the configuration file will + be taken as relative to this directory. The default + location for most server output files + (e.g. <code class="filename">named.run</code>) is this directory. + If a directory is not specified, the working directory + defaults to `<code class="filename">.</code>', the directory from + which the server was started. The directory specified + should be an absolute path. It is + <span class="emphasis"><em>strongly recommended</em></span> + that the directory be writable by the effective user + ID of the <span class="command"><strong>named</strong></span> process. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnstap</strong></span></span></dt> +<dd> + <p> + <span class="command"><strong>dnstap</strong></span> is a fast, flexible method + for capturing and logging DNS traffic. Developed by + Robert Edmonds at Farsight Security, Inc., and supported + by multiple DNS implementations, <span class="command"><strong>dnstap</strong></span> + uses + <span class="command"><strong>libfstrm</strong></span> (a lightweight high-speed + framing library, see + <a class="link" href="https://github.com/farsightsec/fstrm" target="_top">https://github.com/farsightsec/fstrm</a>) to send + event payloads which are encoded using Protocol Buffers + (<span class="command"><strong>libprotobuf-c</strong></span>, a mechanism for + serializing structured data developed + by Google, Inc.; see + <a class="link" href="https://developers.google.com/protocol-buffers/" target="_top">https://developers.google.com/protocol-buffers</a>). + </p> + <p> + To enable <span class="command"><strong>dnstap</strong></span> at compile time, + the <span class="command"><strong>fstrm</strong></span> and <span class="command"><strong>protobuf-c</strong></span> + libraries must be available, and BIND must be configured with + <code class="option">--enable-dnstap</code>. + </p> + <p> + The <span class="command"><strong>dnstap</strong></span> option is a bracketed list + of message types to be logged. These may be set differently + for each view. Supported types are <code class="literal">client</code>, + <code class="literal">auth</code>, <code class="literal">resolver</code>, and + <code class="literal">forwarder</code>. Specifying type + <code class="literal">all</code> will cause all <span class="command"><strong>dnstap</strong></span> + messages to be logged, regardless of type. + </p> + <p> + Each type may take an additional argument to indicate whether + to log <code class="literal">query</code> messages or + <code class="literal">response</code> messages; if not specified, + both queries and responses are logged. + </p> + <p> + Example: To log all authoritative queries and responses, + recursive client responses, and upstream queries sent by + the resolver, use: +</p> +<pre class="programlisting">dnstap { + auth; + client response; + resolver query; +}; +</pre> +<p> + </p> + <p> + Logged <span class="command"><strong>dnstap</strong></span> messages can be parsed + using the <span class="command"><strong>dnstap-read</strong></span> utility (see + <a class="xref" href="man.dnstap-read.html" title="dnstap-read"><span class="refentrytitle"><span class="application">dnstap-read</span></span>(1)</a> for details). + </p> + <p> + For more information on <span class="command"><strong>dnstap</strong></span>, see + <a class="link" href="http://dnstap.info" target="_top">http://dnstap.info</a>. + </p> + <p> + The fstrm library has a number of tunables that are exposed + in <code class="filename">named.conf</code>, and can be modified + if necessary to improve performance or prevent loss of data. + These are: + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + + <span class="command"><strong>fstrm-set-buffer-hint</strong></span>: The + threshold number of bytes to accumulate in the output + buffer before forcing a buffer flush. The minimum is + 1024, the maximum is 65536, and the default is 8192. + + </li> +<li class="listitem"> + + <span class="command"><strong>fstrm-set-flush-timeout</strong></span>: The number + of seconds to allow unflushed data to remain in the + output buffer. The minimum is 1 second, the maximum is + 600 seconds (10 minutes), and the default is 1 second. + + </li> +<li class="listitem"> + + <span class="command"><strong>fstrm-set-output-notify-threshold</strong></span>: + The number of outstanding queue entries to allow on + an input queue before waking the I/O thread. + The minimum is 1 and the default is 32. + + </li> +<li class="listitem"> + + <span class="command"><strong>fstrm-set-output-queue-model</strong></span>: + Controls the queuing semantics to use for queue + objects. The default is <code class="literal">mpsc</code> + (multiple producer, single consumer); the other + option is <code class="literal">spsc</code> (single producer, + single consumer). + + </li> +<li class="listitem"> + + <span class="command"><strong>fstrm-set-input-queue-size</strong></span>: The + number of queue entries to allocate for each + input queue. This value must be a power of 2. + The minimum is 2, the maximum is 16384, and + the default is 512. + + </li> +<li class="listitem"> + + <span class="command"><strong>fstrm-set-output-queue-size</strong></span>: + The number of queue entries to allocate for each + output queue. The minimum is 2, the maximum is + system-dependent and based on <code class="option">IOV_MAX</code>, + and the default is 64. + + </li> +<li class="listitem"> + + <span class="command"><strong>fstrm-set-reopen-interval</strong></span>: + The number of seconds to wait between attempts to + reopen a closed output stream. The minimum is 1 second, + the maximum is 600 seconds (10 minutes), and the default + is 5 seconds. + + </li> +</ul></div> + <p> + Note that all of the above minimum, maximum, and default + values are set by the <span class="command"><strong>libfstrm</strong></span> library, + and may be subject to change in future versions of the + library. See the <span class="command"><strong>libfstrm</strong></span> documentation + for more information. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnstap-output</strong></span></span></dt> +<dd> + <p> + Configures the path to which the <span class="command"><strong>dnstap</strong></span> + frame stream will be sent if <span class="command"><strong>dnstap</strong></span> + is enabled at compile time and active. + </p> + <p> + The first argument is either <code class="literal">file</code> or + <code class="literal">unix</code>, indicating whether the destination + is a file or a UNIX domain socket. The second argument + is the path of the file or socket. (Note: when using a + socket, <span class="command"><strong>dnstap</strong></span> messages will + only be sent if another process such as + <span class="command"><strong>fstrm_capture</strong></span> + (provided with <span class="command"><strong>libfstrm</strong></span>) is listening on + the socket.) + </p> + <p> + <span class="command"><strong>dnstap-output</strong></span> can only be set globally + in <span class="command"><strong>options</strong></span>. Currently, it can only be + set once while <span class="command"><strong>named</strong></span> is running; + once set, it cannot be changed by + <span class="command"><strong>rndc reload</strong></span> or + <span class="command"><strong>rndc reconfig</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnstap-identity</strong></span></span></dt> +<dd> + <p> + Specifies an <span class="command"><strong>identity</strong></span> string to send in + <span class="command"><strong>dnstap</strong></span> messages. If set to + <code class="literal">hostname</code>, which is the default, the + server's hostname will be sent. If set to + <code class="literal">none</code>, no identity string will be sent. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnstap-version</strong></span></span></dt> +<dd> + <p> + Specifies a <span class="command"><strong>version</strong></span> string to send in + <span class="command"><strong>dnstap</strong></span> messages. The default is the + version number of the BIND release. If set to + <code class="literal">none</code>, no version string will be sent. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>geoip-directory</strong></span></span></dt> +<dd> + <p> + Specifies the directory containing GeoIP + <code class="filename">.dat</code> database files for GeoIP + initialization. By default, this option is unset + and the GeoIP support will use libGeoIP's + built-in directory. + (For details, see <a class="xref" href="Bv9ARM.ch06.html#acl" title="acl Statement Definition and Usage">the section called “<span class="command"><strong>acl</strong></span> Statement Definition and + Usage”</a> about the + <span class="command"><strong>geoip</strong></span> ACL.) + </p> + </dd> +<dt><span class="term"><span class="command"><strong>key-directory</strong></span></span></dt> +<dd> + <p> + When performing dynamic update of secure zones, the + directory where the public and private DNSSEC key files + should be found, if different than the current working + directory. (Note that this option has no effect on the + paths for files containing non-DNSSEC keys such as + <code class="filename">bind.keys</code>, + <code class="filename">rndc.key</code> or + <code class="filename">session.key</code>.) + </p> + </dd> +<dt><span class="term"><span class="command"><strong>lmdb-mapsize</strong></span></span></dt> +<dd> + <p> + When <span class="command"><strong>named</strong></span> is built with liblmdb, + this option sets a maximum size for the memory map of + the new-zone database (NZD) in LMDB database format. + This database is used to store configuration information + for zones added using <span class="command"><strong>rndc addzone</strong></span>. + Note that this is not the NZD database file size, but + the largest size that the database may grow to. + </p> + <p> + Because the database file is memory mapped, its size is + limited by the address space of the named process. The + default of 32 megabytes was chosen to be usable with + 32-bit <span class="command"><strong>named</strong></span> builds. The largest + permitted value is 1 terabyte. Given typical zone + configurations without elaborate ACLs, a 32 MB NZD file + ought to be able to hold configurations of about 100,000 + zones. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>managed-keys-directory</strong></span></span></dt> +<dd> + <p> + Specifies the directory in which to store the files that + track managed DNSSEC keys. By default, this is the working + directory. The directory <span class="emphasis"><em>must</em></span> + be writable by the effective user ID of the + <span class="command"><strong>named</strong></span> process. + </p> + <p> + If <span class="command"><strong>named</strong></span> is not configured to use views, + then managed keys for the server will be tracked in a single + file called <code class="filename">managed-keys.bind</code>. + Otherwise, managed keys will be tracked in separate files, + one file per view; each file name will be the view name + (or, if it contains characters that are incompatible with + use as a file name, the SHA256 hash of the view name), + followed by the extension + <code class="filename">.mkeys</code>. + </p> + <p> + (Note: in previous releases, file names for views + always used the SHA256 hash of the view name. To ensure + compatibility after upgrade, if a file using the old + name format is found to exist, it will be used instead + of the new format.) + </p> + </dd> +<dt><span class="term"><span class="command"><strong>named-xfer</strong></span></span></dt> +<dd> + <p> + <span class="emphasis"><em>This option is obsolete.</em></span> It + was used in <acronym class="acronym">BIND</acronym> 8 to specify + the pathname to the <span class="command"><strong>named-xfer</strong></span> + program. In <acronym class="acronym">BIND</acronym> 9, no separate + <span class="command"><strong>named-xfer</strong></span> program is needed; + its functionality is built into the name server. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>tkey-gssapi-keytab</strong></span></span></dt> +<dd> + <p> + The KRB5 keytab file to use for GSS-TSIG updates. If + this option is set and tkey-gssapi-credential is not + set, then updates will be allowed with any key + matching a principal in the specified keytab. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>tkey-gssapi-credential</strong></span></span></dt> +<dd> + <p> + The security credential with which the server should + authenticate keys requested by the GSS-TSIG protocol. + Currently only Kerberos 5 authentication is available + and the credential is a Kerberos principal which the + server can acquire through the default system key + file, normally <code class="filename">/etc/krb5.keytab</code>. + The location keytab file can be overridden using the + tkey-gssapi-keytab option. Normally this principal is + of the form "<strong class="userinput"><code>DNS/</code></strong><code class="varname">server.domain</code>". + To use GSS-TSIG, <span class="command"><strong>tkey-domain</strong></span> must + also be set if a specific keytab is not set with + tkey-gssapi-keytab. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>tkey-domain</strong></span></span></dt> +<dd> + <p> + The domain appended to the names of all shared keys + generated with <span class="command"><strong>TKEY</strong></span>. When a + client requests a <span class="command"><strong>TKEY</strong></span> exchange, + it may or may not specify the desired name for the + key. If present, the name of the shared key will + be <code class="varname">client specified part</code> + + <code class="varname">tkey-domain</code>. Otherwise, the + name of the shared key will be <code class="varname">random hex + digits</code> + <code class="varname">tkey-domain</code>. + In most cases, the <span class="command"><strong>domainname</strong></span> + should be the server's domain name, or an otherwise + non-existent subdomain like + "_tkey.<code class="varname">domainname</code>". If you are + using GSS-TSIG, this variable must be defined, unless + you specify a specific keytab using tkey-gssapi-keytab. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>tkey-dhkey</strong></span></span></dt> +<dd> + <p> + The Diffie-Hellman key used by the server + to generate shared keys with clients using the Diffie-Hellman + mode + of <span class="command"><strong>TKEY</strong></span>. The server must be + able to load the + public and private keys from files in the working directory. + In + most cases, the <code class="varname">key_name</code> should be the server's host name. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>cache-file</strong></span></span></dt> +<dd> + <p> + This is for testing only. Do not use. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dump-file</strong></span></span></dt> +<dd> + <p> + The pathname of the file the server dumps + the database to when instructed to do so with + <span class="command"><strong>rndc dumpdb</strong></span>. + If not specified, the default is <code class="filename">named_dump.db</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>memstatistics-file</strong></span></span></dt> +<dd> + <p> + The pathname of the file the server writes memory + usage statistics to on exit. If not specified, + the default is <code class="filename">named.memstats</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>lock-file</strong></span></span></dt> +<dd> + <p> + The pathname of a file on which <span class="command"><strong>named</strong></span> will + attempt to acquire a file lock when starting up for + the first time; if unsuccessful, the server will + will terminate, under the assumption that another + server is already running. If not specified, the default is + <code class="filename">/var/run/named/named.lock</code>. + </p> + <p> + Specifying <span class="command"><strong>lock-file none</strong></span> disables the + use of a lock file. <span class="command"><strong>lock-file</strong></span> is + ignored if <span class="command"><strong>named</strong></span> was run using the <code class="option">-X</code> + option, which overrides it. Changes to + <span class="command"><strong>lock-file</strong></span> are ignored if + <span class="command"><strong>named</strong></span> is being reloaded or + reconfigured; it is only effective when the server is + first started up. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>pid-file</strong></span></span></dt> +<dd> + <p> + The pathname of the file the server writes its process ID + in. If not specified, the default is + <code class="filename">/var/run/named/named.pid</code>. + The PID file is used by programs that want to send signals to + the running + name server. Specifying <span class="command"><strong>pid-file none</strong></span> disables the + use of a PID file — no file will be written and any + existing one will be removed. Note that <span class="command"><strong>none</strong></span> + is a keyword, not a filename, and therefore is not enclosed + in + double quotes. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>recursing-file</strong></span></span></dt> +<dd> + <p> + The pathname of the file the server dumps + the queries that are currently recursing when instructed + to do so with <span class="command"><strong>rndc recursing</strong></span>. + If not specified, the default is <code class="filename">named.recursing</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>statistics-file</strong></span></span></dt> +<dd> + <p> + The pathname of the file the server appends statistics + to when instructed to do so using <span class="command"><strong>rndc stats</strong></span>. + If not specified, the default is <code class="filename">named.stats</code> in the + server's current directory. The format of the file is + described + in <a class="xref" href="Bv9ARM.ch06.html#statsfile" title="The Statistics File">the section called “The Statistics File”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>bindkeys-file</strong></span></span></dt> +<dd> + <p> + The pathname of a file to override the built-in trusted + keys provided by <span class="command"><strong>named</strong></span>. + See the discussion of <span class="command"><strong>dnssec-validation</strong></span> + for details. If not specified, the default is + <code class="filename">/etc/bind.keys</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>secroots-file</strong></span></span></dt> +<dd> + <p> + The pathname of the file the server dumps + security roots to when instructed to do so with + <span class="command"><strong>rndc secroots</strong></span>. + If not specified, the default is + <code class="filename">named.secroots</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>session-keyfile</strong></span></span></dt> +<dd> + <p> + The pathname of the file into which to write a TSIG + session key generated by <span class="command"><strong>named</strong></span> for use by + <span class="command"><strong>nsupdate -l</strong></span>. If not specified, the + default is <code class="filename">/var/run/named/session.key</code>. + (See <a class="xref" href="Bv9ARM.ch06.html#dynamic_update_policies" title="Dynamic Update Policies">the section called “Dynamic Update Policies”</a>, and in + particular the discussion of the + <span class="command"><strong>update-policy</strong></span> statement's + <strong class="userinput"><code>local</code></strong> option for more + information about this feature.) + </p> + </dd> +<dt><span class="term"><span class="command"><strong>session-keyname</strong></span></span></dt> +<dd> + <p> + The key name to use for the TSIG session key. + If not specified, the default is "local-ddns". + </p> + </dd> +<dt><span class="term"><span class="command"><strong>session-keyalg</strong></span></span></dt> +<dd> + <p> + The algorithm to use for the TSIG session key. + Valid values are hmac-sha1, hmac-sha224, hmac-sha256, + hmac-sha384, hmac-sha512 and hmac-md5. If not + specified, the default is hmac-sha256. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>port</strong></span></span></dt> +<dd> + <p> + The UDP/TCP port number the server uses for + receiving and sending DNS protocol traffic. + The default is 53. This option is mainly intended for server + testing; + a server using a port other than 53 will not be able to + communicate with + the global DNS. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dscp</strong></span></span></dt> +<dd> + <p> + The global Differentiated Services Code Point (DSCP) + value to classify outgoing DNS traffic on operating + systems that support DSCP. Valid values are 0 through 63. + It is not configured by default. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>random-device</strong></span></span></dt> +<dd> + <p> + The source of entropy to be used by the server. Entropy is + primarily needed + for DNSSEC operations, such as TKEY transactions and dynamic + update of signed + zones. This options specifies the device (or file) from which + to read + entropy. If this is a file, operations requiring entropy will + fail when the + file has been exhausted. If not specified, the default value + is + <code class="filename">/dev/random</code> + (or equivalent) when present, and none otherwise. The + <span class="command"><strong>random-device</strong></span> option takes + effect during + the initial configuration load at server startup time and + is ignored on subsequent reloads. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>preferred-glue</strong></span></span></dt> +<dd> + <p> + If specified, the listed type (A or AAAA) will be emitted + before other glue + in the additional section of a query response. + The default is to prefer A records when responding + to queries that arrived via IPv4 and AAAA when + responding to queries that arrived via IPv6. + </p> + </dd> +<dt> +<a name="root_delegation_only"></a><span class="term"><span class="command"><strong>root-delegation-only</strong></span></span> +</dt> +<dd> + <p> + Turn on enforcement of delegation-only in TLDs + (top level domains) and root zones with an optional + exclude list. + </p> + <p> + DS queries are expected to be made to and be answered by + delegation only zones. Such queries and responses are + treated as an exception to delegation-only processing + and are not converted to NXDOMAIN responses provided + a CNAME is not discovered at the query name. + </p> + <p> + If a delegation only zone server also serves a child + zone it is not always possible to determine whether + an answer comes from the delegation only zone or the + child zone. SOA NS and DNSKEY records are apex + only records and a matching response that contains + these records or DS is treated as coming from a + child zone. RRSIG records are also examined to see + if they are signed by a child zone or not. The + authority section is also examined to see if there + is evidence that the answer is from the child zone. + Answers that are determined to be from a child zone + are not converted to NXDOMAIN responses. Despite + all these checks there is still a possibility of + false negatives when a child zone is being served. + </p> + <p> + Similarly false positives can arise from empty nodes + (no records at the name) in the delegation only zone + when the query type is not ANY. + </p> + <p> + Note some TLDs are not delegation only (e.g. "DE", "LV", + "US" and "MUSEUM"). This list is not exhaustive. + </p> + +<pre class="programlisting"> +options { + root-delegation-only exclude { "de"; "lv"; "us"; "museum"; }; +}; +</pre> + + </dd> +<dt><span class="term"><span class="command"><strong>disable-algorithms</strong></span></span></dt> +<dd> + <p> + Disable the specified DNSSEC algorithms at and below the + specified name. + Multiple <span class="command"><strong>disable-algorithms</strong></span> + statements are allowed. + Only the best match <span class="command"><strong>disable-algorithms</strong></span> + clause will be used to determine which algorithms are used. + </p> + <p> + If all supported algorithms are disabled, the zones covered + by the <span class="command"><strong>disable-algorithms</strong></span> will be treated + as insecure. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>disable-ds-digests</strong></span></span></dt> +<dd> + <p> + Disable the specified DS/DLV digest types at and below the + specified name. + Multiple <span class="command"><strong>disable-ds-digests</strong></span> + statements are allowed. + Only the best match <span class="command"><strong>disable-ds-digests</strong></span> + clause will be used to determine which digest types are used. + </p> + <p> + If all supported digest types are disabled, the zones covered + by the <span class="command"><strong>disable-ds-digests</strong></span> will be treated + as insecure. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-lookaside</strong></span></span></dt> +<dd> + <p> + When set, <span class="command"><strong>dnssec-lookaside</strong></span> provides the + validator with an alternate method to validate DNSKEY + records at the top of a zone. When a DNSKEY is at or + below a domain specified by the deepest + <span class="command"><strong>dnssec-lookaside</strong></span>, and the normal DNSSEC + validation has left the key untrusted, the trust-anchor + will be appended to the key name and a DLV record will be + looked up to see if it can validate the key. If the DLV + record validates a DNSKEY (similarly to the way a DS + record does) the DNSKEY RRset is deemed to be trusted. + </p> + <p> + If <span class="command"><strong>dnssec-lookaside</strong></span> is set to + <strong class="userinput"><code>no</code></strong>, then dnssec-lookaside + is not used. + </p> + <p> + NOTE: The ISC-provided DLV service at + <code class="literal">dlv.isc.org</code>, has been shut down. + The <span class="command"><strong>dnssec-lookaside auto;</strong></span> + configuration option, which set <span class="command"><strong>named</strong></span> + up to use ISC DLV with minimal configuration, has + accordingly been removed. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-must-be-secure</strong></span></span></dt> +<dd> + <p> + Specify hierarchies which must be or may not be secure + (signed and validated). If <strong class="userinput"><code>yes</code></strong>, + then <span class="command"><strong>named</strong></span> will only accept answers if + they are secure. If <strong class="userinput"><code>no</code></strong>, then normal + DNSSEC validation applies allowing for insecure answers to + be accepted. The specified domain must be under a + <span class="command"><strong>trusted-keys</strong></span> or + <span class="command"><strong>managed-keys</strong></span> statement, or + <span class="command"><strong>dnssec-validation auto</strong></span> must be active. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dns64</strong></span></span></dt> +<dd> + <p> + This directive instructs <span class="command"><strong>named</strong></span> to + return mapped IPv4 addresses to AAAA queries when + there are no AAAA records. It is intended to be + used in conjunction with a NAT64. Each + <span class="command"><strong>dns64</strong></span> defines one DNS64 prefix. + Multiple DNS64 prefixes can be defined. + </p> + <p> + Compatible IPv6 prefixes have lengths of 32, 40, 48, 56, + 64 and 96 as per RFC 6052. + </p> + <p> + Additionally a reverse IP6.ARPA zone will be created for + the prefix to provide a mapping from the IP6.ARPA names + to the corresponding IN-ADDR.ARPA names using synthesized + CNAMEs. <span class="command"><strong>dns64-server</strong></span> and + <span class="command"><strong>dns64-contact</strong></span> can be used to specify + the name of the server and contact for the zones. These + are settable at the view / options level. These are + not settable on a per-prefix basis. + </p> + <p> + Each <span class="command"><strong>dns64</strong></span> supports an optional + <span class="command"><strong>clients</strong></span> ACL that determines which + clients are affected by this directive. If not defined, + it defaults to <strong class="userinput"><code>any;</code></strong>. + </p> + <p> + Each <span class="command"><strong>dns64</strong></span> supports an optional + <span class="command"><strong>mapped</strong></span> ACL that selects which + IPv4 addresses are to be mapped in the corresponding + A RRset. If not defined it defaults to + <strong class="userinput"><code>any;</code></strong>. + </p> + <p> + Normally, DNS64 won't apply to a domain name that + owns one or more AAAA records; these records will + simply be returned. The optional + <span class="command"><strong>exclude</strong></span> ACL allows specification + of a list of IPv6 addresses that will be ignored + if they appear in a domain name's AAAA records, and + DNS64 will be applied to any A records the domain + name owns. If not defined, <span class="command"><strong>exclude</strong></span> + defaults to ::ffff:0.0.0.0/96. + </p> + <p> + A optional <span class="command"><strong>suffix</strong></span> can also + be defined to set the bits trailing the mapped + IPv4 address bits. By default these bits are + set to <strong class="userinput"><code>::</code></strong>. The bits + matching the prefix and mapped IPv4 address + must be zero. + </p> + <p> + If <span class="command"><strong>recursive-only</strong></span> is set to + <span class="command"><strong>yes</strong></span> the DNS64 synthesis will + only happen for recursive queries. The default + is <span class="command"><strong>no</strong></span>. + </p> + <p> + If <span class="command"><strong>break-dnssec</strong></span> is set to + <span class="command"><strong>yes</strong></span> the DNS64 synthesis will + happen even if the result, if validated, would + cause a DNSSEC validation failure. If this option + is set to <span class="command"><strong>no</strong></span> (the default), the DO + is set on the incoming query, and there are RRSIGs on + the applicable records, then synthesis will not happen. + </p> +<pre class="programlisting"> + acl rfc1918 { 10/8; 192.168/16; 172.16/12; }; + + dns64 64:FF9B::/96 { + clients { any; }; + mapped { !rfc1918; any; }; + exclude { 64:FF9B::/96; ::ffff:0000:0000/96; }; + suffix ::; + }; +</pre> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-loadkeys-interval</strong></span></span></dt> +<dd> + <p> + When a zone is configured with <span class="command"><strong>auto-dnssec + maintain;</strong></span> its key repository must be checked + periodically to see if any new keys have been added + or any existing keys' timing metadata has been updated + (see <a class="xref" href="man.dnssec-keygen.html" title="dnssec-keygen"><span class="refentrytitle"><span class="application">dnssec-keygen</span></span>(8)</a> and + <a class="xref" href="man.dnssec-settime.html" title="dnssec-settime"><span class="refentrytitle"><span class="application">dnssec-settime</span></span>(8)</a>). The + <span class="command"><strong>dnssec-loadkeys-interval</strong></span> option + sets the frequency of automatic repository checks, in + minutes. The default is <code class="literal">60</code> (1 hour), + the minimum is <code class="literal">1</code> (1 minute), and the + maximum is <code class="literal">1440</code> (24 hours); any higher + value is silently reduced. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-update-mode</strong></span></span></dt> +<dd> + <p> + If this option is set to its default value of + <code class="literal">maintain</code> in a zone of type + <code class="literal">master</code> which is DNSSEC-signed + and configured to allow dynamic updates (see + <a class="xref" href="Bv9ARM.ch06.html#dynamic_update_policies" title="Dynamic Update Policies">the section called “Dynamic Update Policies”</a>), and + if <span class="command"><strong>named</strong></span> has access to the + private signing key(s) for the zone, then + <span class="command"><strong>named</strong></span> will automatically sign all new + or changed records and maintain signatures for the zone + by regenerating RRSIG records whenever they approach + their expiration date. + </p> + <p> + If the option is changed to <code class="literal">no-resign</code>, + then <span class="command"><strong>named</strong></span> will sign all new or + changed records, but scheduled maintenance of + signatures is disabled. + </p> + <p> + With either of these settings, <span class="command"><strong>named</strong></span> + will reject updates to a DNSSEC-signed zone when the + signing keys are inactive or unavailable to + <span class="command"><strong>named</strong></span>. (A planned third option, + <code class="literal">external</code>, will disable all automatic + signing and allow DNSSEC data to be submitted into a zone + via dynamic update; this is not yet implemented.) + </p> + </dd> +<dt><span class="term"><span class="command"><strong>nta-lifetime</strong></span></span></dt> +<dd> + <p> + Species the default lifetime, in seconds, + that will be used for negative trust anchors added + via <span class="command"><strong>rndc nta</strong></span>. + </p> + <p> + A negative trust anchor selectively disables + DNSSEC validation for zones that are known to be + failing because of misconfiguration rather than + an attack. When data to be validated is + at or below an active NTA (and above any other + configured trust anchors), <span class="command"><strong>named</strong></span> will + abort the DNSSEC validation process and treat the data as + insecure rather than bogus. This continues until the + NTA's lifetime is elapsed. NTAs persist + across <span class="command"><strong>named</strong></span> restarts. + </p> + <p> + For convenience, TTL-style time unit suffixes can be + used to specify the NTA lifetime in seconds, minutes + or hours. <code class="option">nta-lifetime</code> defaults to + one hour. It cannot exceed one week. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>nta-recheck</strong></span></span></dt> +<dd> + <p> + Species how often to check whether negative + trust anchors added via <span class="command"><strong>rndc nta</strong></span> + are still necessary. + </p> + <p> + A negative trust anchor is normally used when a + domain has stopped validating due to operator error; + it temporarily disables DNSSEC validation for that + domain. In the interest of ensuring that DNSSEC + validation is turned back on as soon as possible, + <span class="command"><strong>named</strong></span> will periodically send a + query to the domain, ignoring negative trust anchors, + to find out whether it can now be validated. If so, + the negative trust anchor is allowed to expire early. + </p> + <p> + Validity checks can be disabled for an individual + NTA by using <span class="command"><strong>rndc nta -f</strong></span>, or + for all NTAs by setting <code class="option">nta-recheck</code> + to zero. + </p> + <p> + For convenience, TTL-style time unit suffixes can be + used to specify the NTA recheck interval in seconds, + minutes or hours. The default is five minutes. It + cannot be longer than <code class="option">nta-lifetime</code> + (which cannot be longer than a week). + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-zone-ttl</strong></span></span></dt> +<dd> + <p> + Specifies a maximum permissible TTL value in seconds. + For convenience, TTL-style time unit suffixes may be + used to specify the maximum value. + When loading a zone file using a + <code class="option">masterfile-format</code> of + <code class="constant">text</code> or <code class="constant">raw</code>, + any record encountered with a TTL higher than + <code class="option">max-zone-ttl</code> will cause the zone to + be rejected. + </p> + <p> + This is useful in DNSSEC-signed zones because when + rolling to a new DNSKEY, the old key needs to remain + available until RRSIG records have expired from + caches. The <code class="option">max-zone-ttl</code> option guarantees + that the largest TTL in the zone will be no higher + than the set value. + </p> + <p> + (NOTE: Because <code class="constant">map</code>-format files + load directly into memory, this option cannot be + used with them.) + </p> + <p> + The default value is <code class="constant">unlimited</code>. + A <code class="option">max-zone-ttl</code> of zero is treated as + <code class="constant">unlimited</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>serial-update-method</strong></span></span></dt> +<dd> + <p> + Zones configured for dynamic DNS may use this + option to set the update method that will be used for + the zone serial number in the SOA record. + </p> + <p> + With the default setting of + <span class="command"><strong>serial-update-method increment;</strong></span>, the + SOA serial number will be incremented by one each time + the zone is updated. + </p> + <p> + When set to + <span class="command"><strong>serial-update-method unixtime;</strong></span>, the + SOA serial number will be set to the number of seconds + since the UNIX epoch, unless the serial number is + already greater than or equal to that value, in which + case it is simply incremented by one. + </p> + <p> + When set to + <span class="command"><strong>serial-update-method date;</strong></span>, the + new SOA serial number will be the current date + in the form "YYYYMMDD", followed by two zeroes, + unless the existing serial number is already greater + than or equal to that value, in which case it is + incremented by one. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>zone-statistics</strong></span></span></dt> +<dd> + <p> + If <strong class="userinput"><code>full</code></strong>, the server will collect + statistical data on all zones (unless specifically + turned off on a per-zone basis by specifying + <span class="command"><strong>zone-statistics terse</strong></span> or + <span class="command"><strong>zone-statistics none</strong></span> + in the <span class="command"><strong>zone</strong></span> statement). + The default is <strong class="userinput"><code>terse</code></strong>, providing + minimal statistics on zones (including name and + current serial number, but not query type + counters). + </p> + <p> + These statistics may be accessed via the + <span class="command"><strong>statistics-channel</strong></span> or + using <span class="command"><strong>rndc stats</strong></span>, which + will dump them to the file listed + in the <span class="command"><strong>statistics-file</strong></span>. See + also <a class="xref" href="Bv9ARM.ch06.html#statsfile" title="The Statistics File">the section called “The Statistics File”</a>. + </p> + <p> + For backward compatibility with earlier versions + of BIND 9, the <span class="command"><strong>zone-statistics</strong></span> + option can also accept <strong class="userinput"><code>yes</code></strong> + or <strong class="userinput"><code>no</code></strong>; <strong class="userinput"><code>yes</code></strong> + has the same meaning as <strong class="userinput"><code>full</code></strong>. + As of <acronym class="acronym">BIND</acronym> 9.10, + <strong class="userinput"><code>no</code></strong> has the same meaning + as <strong class="userinput"><code>none</code></strong>; previously, it + was the same as <strong class="userinput"><code>terse</code></strong>. + </p> + </dd> +</dl></div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boolean_options"></a>Boolean Options</h4></div></div></div> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>automatic-interface-scan</strong></span></span></dt> +<dd> + <p> + If <strong class="userinput"><code>yes</code></strong> and supported by the OS, + automatically rescan network interfaces when the interface + addresses are added or removed. The default is + <strong class="userinput"><code>yes</code></strong>. + </p> + <p> + Currently the OS needs to support routing sockets for + <span class="command"><strong>automatic-interface-scan</strong></span> to be + supported. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-new-zones</strong></span></span></dt> +<dd> + <p> + If <strong class="userinput"><code>yes</code></strong>, then zones can be + added at runtime via <span class="command"><strong>rndc addzone</strong></span>. + The default is <strong class="userinput"><code>no</code></strong>. + </p> + <p> + Newly added zones' configuration parameters + are stored so that they can persist after the + server is restarted. The configuration information + is saved in a file called + <code class="filename"><em class="replaceable"><code>viewname</code></em>.nzf</code> + (or, if <span class="command"><strong>named</strong></span> is compiled with + liblmdb, in an LMDB database file called + <code class="filename"><em class="replaceable"><code>viewname</code></em>.nzd</code>). + <em class="replaceable"><code>viewname</code></em> is the name of the + view, unless the view name contains characters that are + incompatible with use as a file name, in which case a + cryptographic hash of the view name is used instead. + </p> + <p> + Zones added at runtime will have their configuration + stored either in a new-zone file (NZF) or a new-zone + database (NZD) depending on whether + <span class="command"><strong>named</strong></span> was linked with + liblmdb at compile time. + See <a class="xref" href="man.rndc.html" title="rndc"><span class="refentrytitle"><span class="application">rndc</span></span>(8)</a> for further details + about <span class="command"><strong>rndc addzone</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>auth-nxdomain</strong></span></span></dt> +<dd> + <p> + If <strong class="userinput"><code>yes</code></strong>, then the <span class="command"><strong>AA</strong></span> bit + is always set on NXDOMAIN responses, even if the server is + not actually + authoritative. The default is <strong class="userinput"><code>no</code></strong>; + this is + a change from <acronym class="acronym">BIND</acronym> 8. If you + are using very old DNS software, you + may need to set it to <strong class="userinput"><code>yes</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>deallocate-on-exit</strong></span></span></dt> +<dd> + <p> + This option was used in <acronym class="acronym">BIND</acronym> + 8 to enable checking + for memory leaks on exit. <acronym class="acronym">BIND</acronym> 9 ignores the option and always performs + the checks. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>memstatistics</strong></span></span></dt> +<dd> + <p> + Write memory statistics to the file specified by + <span class="command"><strong>memstatistics-file</strong></span> at exit. + The default is <strong class="userinput"><code>no</code></strong> unless + '-m record' is specified on the command line in + which case it is <strong class="userinput"><code>yes</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dialup</strong></span></span></dt> +<dd> + <p> + If <strong class="userinput"><code>yes</code></strong>, then the + server treats all zones as if they are doing zone transfers + across + a dial-on-demand dialup link, which can be brought up by + traffic + originating from this server. This has different effects + according + to zone type and concentrates the zone maintenance so that + it all + happens in a short interval, once every <span class="command"><strong>heartbeat-interval</strong></span> and + hopefully during the one call. It also suppresses some of + the normal + zone maintenance traffic. The default is <strong class="userinput"><code>no</code></strong>. + </p> + <p> + The <span class="command"><strong>dialup</strong></span> option + may also be specified in the <span class="command"><strong>view</strong></span> and + <span class="command"><strong>zone</strong></span> statements, + in which case it overrides the global <span class="command"><strong>dialup</strong></span> + option. + </p> + <p> + If the zone is a master zone, then the server will send out a + NOTIFY + request to all the slaves (default). This should trigger the + zone serial + number check in the slave (providing it supports NOTIFY) + allowing the slave + to verify the zone while the connection is active. + The set of servers to which NOTIFY is sent can be controlled + by + <span class="command"><strong>notify</strong></span> and <span class="command"><strong>also-notify</strong></span>. + </p> + <p> + If the + zone is a slave or stub zone, then the server will suppress + the regular + "zone up to date" (refresh) queries and only perform them + when the + <span class="command"><strong>heartbeat-interval</strong></span> expires in + addition to sending + NOTIFY requests. + </p> + <p> + Finer control can be achieved by using + <strong class="userinput"><code>notify</code></strong> which only sends NOTIFY + messages, + <strong class="userinput"><code>notify-passive</code></strong> which sends NOTIFY + messages and + suppresses the normal refresh queries, <strong class="userinput"><code>refresh</code></strong> + which suppresses normal refresh processing and sends refresh + queries + when the <span class="command"><strong>heartbeat-interval</strong></span> + expires, and + <strong class="userinput"><code>passive</code></strong> which just disables normal + refresh + processing. + </p> + + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.150in" class="1"> +<col width="1.150in" class="2"> +<col width="1.150in" class="3"> +<col width="1.150in" class="4"> +</colgroup> +<tbody> +<tr> +<td> + <p> + dialup mode + </p> + </td> +<td> + <p> + normal refresh + </p> + </td> +<td> + <p> + heart-beat refresh + </p> + </td> +<td> + <p> + heart-beat notify + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>no</strong></span> (default)</p> + </td> +<td> + <p> + yes + </p> + </td> +<td> + <p> + no + </p> + </td> +<td> + <p> + no + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>yes</strong></span></p> + </td> +<td> + <p> + no + </p> + </td> +<td> + <p> + yes + </p> + </td> +<td> + <p> + yes + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>notify</strong></span></p> + </td> +<td> + <p> + yes + </p> + </td> +<td> + <p> + no + </p> + </td> +<td> + <p> + yes + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>refresh</strong></span></p> + </td> +<td> + <p> + no + </p> + </td> +<td> + <p> + yes + </p> + </td> +<td> + <p> + no + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>passive</strong></span></p> + </td> +<td> + <p> + no + </p> + </td> +<td> + <p> + no + </p> + </td> +<td> + <p> + no + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>notify-passive</strong></span></p> + </td> +<td> + <p> + no + </p> + </td> +<td> + <p> + no + </p> + </td> +<td> + <p> + yes + </p> + </td> +</tr> +</tbody> +</table> + </div> + + <p> + Note that normal NOTIFY processing is not affected by + <span class="command"><strong>dialup</strong></span>. + </p> + + </dd> +<dt><span class="term"><span class="command"><strong>fake-iquery</strong></span></span></dt> +<dd> + <p> + In <acronym class="acronym">BIND</acronym> 8, this option + enabled simulating the obsolete DNS query type + IQUERY. <acronym class="acronym">BIND</acronym> 9 never does + IQUERY simulation. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>fetch-glue</strong></span></span></dt> +<dd> + <p> + This option is obsolete. + In BIND 8, <strong class="userinput"><code>fetch-glue yes</code></strong> + caused the server to attempt to fetch glue resource records + it + didn't have when constructing the additional + data section of a response. This is now considered a bad + idea + and BIND 9 never does it. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>flush-zones-on-shutdown</strong></span></span></dt> +<dd> + <p> + When the nameserver exits due receiving SIGTERM, + flush or do not flush any pending zone writes. The default + is + <span class="command"><strong>flush-zones-on-shutdown</strong></span> <strong class="userinput"><code>no</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>geoip-use-ecs</strong></span></span></dt> +<dd> + <p> + When BIND is compiled with GeoIP support and configured + with "geoip" ACL elements, this option indicates whether + the EDNS Client Subnet option, if present in a request, + should be used for matching against the GeoIP database. + The default is + <span class="command"><strong>geoip-use-ecs</strong></span> <strong class="userinput"><code>yes</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>has-old-clients</strong></span></span></dt> +<dd> + <p> + This option was incorrectly implemented + in <acronym class="acronym">BIND</acronym> 8, and is ignored by <acronym class="acronym">BIND</acronym> 9. + To achieve the intended effect + of + <span class="command"><strong>has-old-clients</strong></span> <strong class="userinput"><code>yes</code></strong>, specify + the two separate options <span class="command"><strong>auth-nxdomain</strong></span> <strong class="userinput"><code>yes</code></strong> + and <span class="command"><strong>rfc2308-type1</strong></span> <strong class="userinput"><code>no</code></strong> instead. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>host-statistics</strong></span></span></dt> +<dd> + <p> + In BIND 8, this enabled keeping of + statistics for every host that the name server interacts + with. + Not implemented in BIND 9. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>root-key-sentinel</strong></span></span></dt> +<dd> + <p> + Respond to root key sentinel probes as described in + draft-ietf-dnsop-kskroll-sentinel-08. The default is + <strong class="userinput"><code>yes</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>maintain-ixfr-base</strong></span></span></dt> +<dd> + <p> + <span class="emphasis"><em>This option is obsolete</em></span>. + It was used in <acronym class="acronym">BIND</acronym> 8 to + determine whether a transaction log was + kept for Incremental Zone Transfer. <acronym class="acronym">BIND</acronym> 9 maintains a transaction + log whenever possible. If you need to disable outgoing + incremental zone + transfers, use <span class="command"><strong>provide-ixfr</strong></span> <strong class="userinput"><code>no</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>message-compression</strong></span></span></dt> +<dd> + <p> + If <strong class="userinput"><code>yes</code></strong>, DNS name compression is + used in responses to regular queries (not including + AXFR or IXFR, which always uses compression). Setting + this option to <strong class="userinput"><code>no</code></strong> reduces CPU + usage on servers and may improve throughput. However, + it increases response size, which may cause more queries + to be processed using TCP; a server with compression + disabled is out of compliance with RFC 1123 Section + 6.1.3.2. The default is <strong class="userinput"><code>yes</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>minimal-responses</strong></span></span></dt> +<dd> + <p> + If set to <strong class="userinput"><code>yes</code></strong>, then when generating + responses the server will only add records to the authority + and additional data sections when they are required (e.g. + delegations, negative responses). This may improve the + performance of the server. + </p> + <p> + When set to <strong class="userinput"><code>no-auth</code></strong>, the + server will omit records from the authority section + unless they are required, but it may still add + records to the additional section. When set to + <strong class="userinput"><code>no-auth-recursive</code></strong>, this + is only done if the query is recursive. These + settings are useful when answering stub clients, + which usually ignore the authority section. + <strong class="userinput"><code>no-auth-recursive</code></strong> is + designed for mixed-mode servers which handle + both authoritative and recursive queries. + </p> + <p> + The default is <strong class="userinput"><code>no</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>minimal-any</strong></span></span></dt> +<dd> + <p> + If set to <strong class="userinput"><code>yes</code></strong>, then when + generating a positive response to a query of type + ANY over UDP, the server will reply with only one + of the RRsets for the query name, and its covering + RRSIGs if any, instead of replying with all known + RRsets for the name. Similarly, a query for type + RRSIG will be answered with the RRSIG records covering + only one type. This can reduce the impact of some kinds + of attack traffic, without harming legitimate + clients. (Note, however, that the RRset returned is the + first one found in the database; it is not necessarily + the smallest available RRset.) + Additionally, <code class="option">minimal-responses</code> is + turned on for these queries, so no unnecessary records + will be added to the authority or additional sections. + The default is <strong class="userinput"><code>no</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>multiple-cnames</strong></span></span></dt> +<dd> + <p> + This option was used in <acronym class="acronym">BIND</acronym> 8 to allow + a domain name to have multiple CNAME records in violation of + the DNS standards. <acronym class="acronym">BIND</acronym> 9.2 onwards + always strictly enforces the CNAME rules both in master + files and dynamic updates. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>notify</strong></span></span></dt> +<dd> + <p> + If <strong class="userinput"><code>yes</code></strong> (the default), + DNS NOTIFY messages are sent when a zone the server is + authoritative for + changes, see <a class="xref" href="Bv9ARM.ch04.html#notify" title="Notify">the section called “Notify”</a>. The messages are + sent to the + servers listed in the zone's NS records (except the master + server identified + in the SOA MNAME field), and to any servers listed in the + <span class="command"><strong>also-notify</strong></span> option. + </p> + <p> + If <strong class="userinput"><code>master-only</code></strong>, notifies are only + sent + for master zones. + If <strong class="userinput"><code>explicit</code></strong>, notifies are sent only + to + servers explicitly listed using <span class="command"><strong>also-notify</strong></span>. + If <strong class="userinput"><code>no</code></strong>, no notifies are sent. + </p> + <p> + The <span class="command"><strong>notify</strong></span> option may also be + specified in the <span class="command"><strong>zone</strong></span> + statement, + in which case it overrides the <span class="command"><strong>options notify</strong></span> statement. + It would only be necessary to turn off this option if it + caused slaves + to crash. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>notify-to-soa</strong></span></span></dt> +<dd> + <p> + If <strong class="userinput"><code>yes</code></strong> do not check the nameservers + in the NS RRset against the SOA MNAME. Normally a NOTIFY + message is not sent to the SOA MNAME (SOA ORIGIN) as it is + supposed to contain the name of the ultimate master. + Sometimes, however, a slave is listed as the SOA MNAME in + hidden master configurations and in that case you would + want the ultimate master to still send NOTIFY messages to + all the nameservers listed in the NS RRset. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>recursion</strong></span></span></dt> +<dd> + <p> + If <strong class="userinput"><code>yes</code></strong>, and a + DNS query requests recursion, then the server will attempt + to do + all the work required to answer the query. If recursion is + off + and the server does not already know the answer, it will + return a + referral response. The default is + <strong class="userinput"><code>yes</code></strong>. + Note that setting <span class="command"><strong>recursion no</strong></span> does not prevent + clients from getting data from the server's cache; it only + prevents new data from being cached as an effect of client + queries. + Caching may still occur as an effect the server's internal + operation, such as NOTIFY address lookups. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>request-nsid</strong></span></span></dt> +<dd> + <p> + If <strong class="userinput"><code>yes</code></strong>, then an empty EDNS(0) + NSID (Name Server Identifier) option is sent with all + queries to authoritative name servers during iterative + resolution. If the authoritative server returns an NSID + option in its response, then its contents are logged in + the <span class="command"><strong>resolver</strong></span> category at level + <span class="command"><strong>info</strong></span>. + The default is <strong class="userinput"><code>no</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>request-sit</strong></span></span></dt> +<dd> + <p> + This experimental option is obsolete. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>require-server-cookie</strong></span></span></dt> +<dd> + <p> + Require a valid server cookie before sending a full + response to a UDP request from a cookie aware client. + BADCOOKIE is sent if there is a bad or no existent + server cookie. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>answer-cookie</strong></span></span></dt> +<dd> + <p> + When set to the default value of <strong class="userinput"><code>yes</code></strong>, + COOKIE EDNS options will be sent when applicable in + replies to client queries. If set to + <strong class="userinput"><code>no</code></strong>, COOKIE EDNS options will not + be sent in replies. This can only be set at the global + options level, not per-view. + </p> + <p> + <span class="command"><strong>answer-cookie no</strong></span> is only intended as a + temporary measure, for use when <span class="command"><strong>named</strong></span> + shares an IP address with other servers that do not yet + support DNS COOKIE. A mismatch between servers on the + same address is not expected to cause operational + problems, but the option to disable COOKIE responses so + that all servers have the same behavior is provided out + of an abundance of caution. DNS COOKIE is an important + security mechanism, and should not be disabled unless + absolutely necessary. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>send-cookie</strong></span></span></dt> +<dd> + <p> + If <strong class="userinput"><code>yes</code></strong>, then a COOKIE EDNS + option is sent along with the query. If the + resolver has previously talked to the server, the + COOKIE returned in the previous transaction is sent. + This is used by the server to determine whether + the resolver has talked to it before. A resolver + sending the correct COOKIE is assumed not to be an + off-path attacker sending a spoofed-source query; + the query is therefore unlikely to be part of a + reflection/amplification attack, so resolvers + sending a correct COOKIE option are not subject to + response rate limiting (RRL). Resolvers which + do not send a correct COOKIE option may be limited + to receiving smaller responses via the + <span class="command"><strong>nocookie-udp-size</strong></span> option. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>nocookie-udp-size</strong></span></span></dt> +<dd> + <p> + Sets the maximum size of UDP responses that will be + sent to queries without a valid server COOKIE. A value + below 128 will be silently raised to 128. The default + value is 4096, but the <span class="command"><strong>max-udp-size</strong></span> + option may further limit the response size. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>sit-secret</strong></span></span></dt> +<dd> + <p> + This experimental option is obsolete. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>cookie-algorithm</strong></span></span></dt> +<dd> + <p> + Set the algorithm to be used when generating the + server cookie. One of "aes", "sha1" or "sha256". + The default is "aes" if supported by the cryptographic + library or otherwise "sha256". + </p> + </dd> +<dt><span class="term"><span class="command"><strong>cookie-secret</strong></span></span></dt> +<dd> + <p> + If set, this is a shared secret used for generating + and verifying EDNS COOKIE options + within an anycast cluster. If not set, the system + will generate a random secret at startup. The + shared secret is encoded as a hex string and needs + to be 128 bits for AES128, 160 bits for SHA1 and + 256 bits for SHA256. + </p> + <p> + If there are multiple secrets specified, the first + one listed in <code class="filename">named.conf</code> is + used to generate new server cookies. The others + will only be used to verify returned cookies. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>rfc2308-type1</strong></span></span></dt> +<dd> + <p> + Setting this to <strong class="userinput"><code>yes</code></strong> will + cause the server to send NS records along with the SOA + record for negative + answers. The default is <strong class="userinput"><code>no</code></strong>. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + Not yet implemented in <acronym class="acronym">BIND</acronym> + 9. + </p> + </div> + </dd> +<dt><span class="term"><span class="command"><strong>trust-anchor-telemetry</strong></span></span></dt> +<dd> + <p> + Causes <span class="command"><strong>named</strong></span> to send specially-formed + queries once per day to domains for which trust anchors + have been configured via <span class="command"><strong>trusted-keys</strong></span>, + <span class="command"><strong>managed-keys</strong></span>, or + <span class="command"><strong>dnssec-validation auto</strong></span>. + </p> + <p> + The query name used for these queries has the + form "_ta-xxxx(-xxxx)(...)".<domain>, where + each "xxxx" is a group of four hexadecimal digits + representing the key ID of a trusted DNSSEC key. + The key IDs for each domain are sorted smallest + to largest prior to encoding. The query type is NULL. + </p> + <p> + By monitoring these queries, zone operators will + be able to see which resolvers have been updated to + trust a new key; this may help them decide when it + is safe to remove an old one. + </p> + <p> + The default is <strong class="userinput"><code>yes</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>use-id-pool</strong></span></span></dt> +<dd> + <p> + <span class="emphasis"><em>This option is obsolete</em></span>. + <acronym class="acronym">BIND</acronym> 9 always allocates query + IDs from a pool. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>use-ixfr</strong></span></span></dt> +<dd> + <p> + <span class="emphasis"><em>This option is obsolete</em></span>. + If you need to disable IXFR to a particular server or + servers, see + the information on the <span class="command"><strong>provide-ixfr</strong></span> option + in <a class="xref" href="Bv9ARM.ch06.html#server_statement_definition_and_usage" title="server Statement Definition and Usage">the section called “<span class="command"><strong>server</strong></span> Statement Definition and + Usage”</a>. + See also + <a class="xref" href="Bv9ARM.ch04.html#incremental_zone_transfers" title="Incremental Zone Transfers (IXFR)">the section called “Incremental Zone Transfers (IXFR)”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>provide-ixfr</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>provide-ixfr</strong></span> in + <a class="xref" href="Bv9ARM.ch06.html#server_statement_definition_and_usage" title="server Statement Definition and Usage">the section called “<span class="command"><strong>server</strong></span> Statement Definition and + Usage”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>request-ixfr</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>request-ixfr</strong></span> in + <a class="xref" href="Bv9ARM.ch06.html#server_statement_definition_and_usage" title="server Statement Definition and Usage">the section called “<span class="command"><strong>server</strong></span> Statement Definition and + Usage”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>request-expire</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>request-expire</strong></span> in + <a class="xref" href="Bv9ARM.ch06.html#server_statement_definition_and_usage" title="server Statement Definition and Usage">the section called “<span class="command"><strong>server</strong></span> Statement Definition and + Usage”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>treat-cr-as-space</strong></span></span></dt> +<dd> + <p> + This option was used in <acronym class="acronym">BIND</acronym> + 8 to make + the server treat carriage return ("<span class="command"><strong>\r</strong></span>") characters the same way + as a space or tab character, + to facilitate loading of zone files on a UNIX system that + were generated + on an NT or DOS machine. In <acronym class="acronym">BIND</acronym> 9, both UNIX "<span class="command"><strong>\n</strong></span>" + and NT/DOS "<span class="command"><strong>\r\n</strong></span>" newlines + are always accepted, + and the option is ignored. + </p> + </dd> +<dt> +<span class="term"><span class="command"><strong>additional-from-auth</strong></span>, </span><span class="term"><span class="command"><strong>additional-from-cache</strong></span></span> +</dt> +<dd> + + <p> + These options control the behavior of an authoritative + server when + answering queries which have additional data, or when + following CNAME + and DNAME chains. + </p> + + <p> + When both of these options are set to <strong class="userinput"><code>yes</code></strong> + (the default) and a + query is being answered from authoritative data (a zone + configured into the server), the additional data section of + the + reply will be filled in using data from other authoritative + zones + and from the cache. In some situations this is undesirable, + such + as when there is concern over the correctness of the cache, + or + in servers where slave zones may be added and modified by + untrusted third parties. Also, avoiding + the search for this additional data will speed up server + operations + at the possible expense of additional queries to resolve + what would + otherwise be provided in the additional section. + </p> + + <p> + For example, if a query asks for an MX record for host <code class="literal">foo.example.com</code>, + and the record found is "<code class="literal">MX 10 mail.example.net</code>", normally the address + records (A and AAAA) for <code class="literal">mail.example.net</code> will be provided as well, + if known, even though they are not in the example.com zone. + Setting these options to <span class="command"><strong>no</strong></span> + disables this behavior and makes + the server only search for additional data in the zone it + answers from. + </p> + + <p> + These options are intended for use in authoritative-only + servers, or in authoritative-only views. Attempts to set + them to <span class="command"><strong>no</strong></span> without also + specifying + <span class="command"><strong>recursion no</strong></span> will cause the + server to + ignore the options and log a warning message. + </p> + + <p> + Specifying <span class="command"><strong>additional-from-cache no</strong></span> actually + disables the use of the cache not only for additional data + lookups + but also when looking up the answer. This is usually the + desired + behavior in an authoritative-only server where the + correctness of + the cached data is an issue. + </p> + + <p> + When a name server is non-recursively queried for a name + that is not + below the apex of any served zone, it normally answers with + an + "upwards referral" to the root servers or the servers of + some other + known parent of the query name. Since the data in an + upwards referral + comes from the cache, the server will not be able to provide + upwards + referrals when <span class="command"><strong>additional-from-cache no</strong></span> + has been specified. Instead, it will respond to such + queries + with REFUSED. This should not cause any problems since + upwards referrals are not required for the resolution + process. + </p> + + </dd> +<dt><span class="term"><span class="command"><strong>match-mapped-addresses</strong></span></span></dt> +<dd> + <p> + If <strong class="userinput"><code>yes</code></strong>, then an + IPv4-mapped IPv6 address will match any address match + list entries that match the corresponding IPv4 address. + </p> + <p> + This option was introduced to work around a kernel quirk + in some operating systems that causes IPv4 TCP + connections, such as zone transfers, to be accepted on an + IPv6 socket using mapped addresses. This caused address + match lists designed for IPv4 to fail to match. However, + <span class="command"><strong>named</strong></span> now solves this problem + internally. The use of this option is discouraged. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>filter-aaaa-on-v4</strong></span></span></dt> +<dd> + <p> + This option is only available when + <acronym class="acronym">BIND</acronym> 9 is compiled with the + <strong class="userinput"><code>--enable-filter-aaaa</code></strong> option on the + "configure" command line. It is intended to help the + transition from IPv4 to IPv6 by not giving IPv6 addresses + to DNS clients unless they have connections to the IPv6 + Internet. This is not recommended unless absolutely + necessary. The default is <strong class="userinput"><code>no</code></strong>. + The <span class="command"><strong>filter-aaaa-on-v4</strong></span> option + may also be specified in <span class="command"><strong>view</strong></span> statements + to override the global <span class="command"><strong>filter-aaaa-on-v4</strong></span> + option. + </p> + <p> + If <strong class="userinput"><code>yes</code></strong>, + the DNS client is at an IPv4 address, in <span class="command"><strong>filter-aaaa</strong></span>, + and if the response does not include DNSSEC signatures, + then all AAAA records are deleted from the response. + This filtering applies to all responses and not only + authoritative responses. + </p> + <p> + If <strong class="userinput"><code>break-dnssec</code></strong>, + then AAAA records are deleted even when DNSSEC is enabled. + As suggested by the name, this makes the response not verify, + because the DNSSEC protocol is designed detect deletions. + </p> + <p> + This mechanism can erroneously cause other servers to + not give AAAA records to their clients. + A recursing server with both IPv6 and IPv4 network connections + that queries an authoritative server using this mechanism + via IPv4 will be denied AAAA records even if its client is + using IPv6. + </p> + <p> + This mechanism is applied to authoritative as well as + non-authoritative records. + A client using IPv4 that is not allowed recursion can + erroneously be given AAAA records because the server is not + allowed to check for A records. + </p> + <p> + Some AAAA records are given to IPv4 clients in glue records. + IPv4 clients that are servers can then erroneously + answer requests for AAAA records received via IPv4. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>filter-aaaa-on-v6</strong></span></span></dt> +<dd> + <p> + Identical to <span class="command"><strong>filter-aaaa-on-v4</strong></span>, + except it filters AAAA responses to queries from IPv6 + clients instead of IPv4 clients. To filter all + responses, set both options to <strong class="userinput"><code>yes</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>ixfr-from-differences</strong></span></span></dt> +<dd> + <p> + When <strong class="userinput"><code>yes</code></strong> and the server loads a new + version of a master zone from its zone file or receives a + new version of a slave file via zone transfer, it will + compare the new version to the previous one and calculate + a set of differences. The differences are then logged in + the zone's journal file such that the changes can be + transmitted to downstream slaves as an incremental zone + transfer. + </p> + <p> + By allowing incremental zone transfers to be used for + non-dynamic zones, this option saves bandwidth at the + expense of increased CPU and memory consumption at the + master. + In particular, if the new version of a zone is completely + different from the previous one, the set of differences + will be of a size comparable to the combined size of the + old and new zone version, and the server will need to + temporarily allocate memory to hold this complete + difference set. + </p> + <p><span class="command"><strong>ixfr-from-differences</strong></span> + also accepts <span class="command"><strong>master</strong></span> and + <span class="command"><strong>slave</strong></span> at the view and options + levels which causes + <span class="command"><strong>ixfr-from-differences</strong></span> to be enabled for + all <span class="command"><strong>master</strong></span> or + <span class="command"><strong>slave</strong></span> zones respectively. + It is off by default. + </p> + <p> + Note: if inline signing is enabled for a zone, the + user-provided <span class="command"><strong>ixfr-from-differences</strong></span> + setting is ignored for that zone. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>multi-master</strong></span></span></dt> +<dd> + <p> + This should be set when you have multiple masters for a zone + and the + addresses refer to different machines. If <strong class="userinput"><code>yes</code></strong>, <span class="command"><strong>named</strong></span> will + not log + when the serial number on the master is less than what <span class="command"><strong>named</strong></span> + currently + has. The default is <strong class="userinput"><code>no</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>auto-dnssec</strong></span></span></dt> +<dd> + <p> + Zones configured for dynamic DNS may use this + option to allow varying levels of automatic DNSSEC key + management. There are three possible settings: + </p> + <p> + <span class="command"><strong>auto-dnssec allow;</strong></span> permits + keys to be updated and the zone fully re-signed + whenever the user issues the command <span class="command"><strong>rndc sign + <em class="replaceable"><code>zonename</code></em></strong></span>. + </p> + <p> + <span class="command"><strong>auto-dnssec maintain;</strong></span> includes the + above, but also automatically adjusts the zone's DNSSEC + keys on schedule, according to the keys' timing metadata + (see <a class="xref" href="man.dnssec-keygen.html" title="dnssec-keygen"><span class="refentrytitle"><span class="application">dnssec-keygen</span></span>(8)</a> and + <a class="xref" href="man.dnssec-settime.html" title="dnssec-settime"><span class="refentrytitle"><span class="application">dnssec-settime</span></span>(8)</a>). The command + <span class="command"><strong>rndc sign + <em class="replaceable"><code>zonename</code></em></strong></span> causes + <span class="command"><strong>named</strong></span> to load keys from the key + repository and sign the zone with all keys that are + active. + <span class="command"><strong>rndc loadkeys + <em class="replaceable"><code>zonename</code></em></strong></span> causes + <span class="command"><strong>named</strong></span> to load keys from the key + repository and schedule key maintenance events to occur + in the future, but it does not sign the full zone + immediately. Note: once keys have been loaded for a + zone the first time, the repository will be searched + for changes periodically, regardless of whether + <span class="command"><strong>rndc loadkeys</strong></span> is used. The recheck + interval is defined by + <span class="command"><strong>dnssec-loadkeys-interval</strong></span>.) + </p> + <p> + The default setting is <span class="command"><strong>auto-dnssec off</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-enable</strong></span></span></dt> +<dd> + <p> + This indicates whether DNSSEC-related resource + records are to be returned by <span class="command"><strong>named</strong></span>. + If set to <strong class="userinput"><code>no</code></strong>, + <span class="command"><strong>named</strong></span> will not return DNSSEC-related + resource records unless specifically queried for. + The default is <strong class="userinput"><code>yes</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-validation</strong></span></span></dt> +<dd> + <p> + Enable DNSSEC validation in <span class="command"><strong>named</strong></span>. + Note <span class="command"><strong>dnssec-enable</strong></span> also needs to be + set to <strong class="userinput"><code>yes</code></strong> to be effective. + If set to <strong class="userinput"><code>no</code></strong>, DNSSEC validation + is disabled. + </p> + <p> + If set to <strong class="userinput"><code>auto</code></strong>, DNSSEC validation + is enabled, and a default trust anchor for the DNS root + zone is used. If set to <strong class="userinput"><code>yes</code></strong>, + DNSSEC validation is enabled, but a trust anchor must be + manually configured using a <span class="command"><strong>trusted-keys</strong></span> + or <span class="command"><strong>managed-keys</strong></span> statement. The default + is <strong class="userinput"><code>yes</code></strong>. + </p> + <p> + The default root trust anchor is stored in the file + <code class="filename">bind.keys</code>. + <span class="command"><strong>named</strong></span> will load that key at + startup if <span class="command"><strong>dnssec-validation</strong></span> is + set to <code class="constant">auto</code>. A copy of the file is + installed along with BIND 9, and is current as of the + release date. If the root key expires, a new copy of + <code class="filename">bind.keys</code> can be downloaded + from <a class="link" href="https://www.isc.org/bind-keys" target="_top">https://www.isc.org/bind-keys</a>. + </p> + <p> + To prevent problems if <code class="filename">bind.keys</code> is + not found, the current trust anchor is also compiled in + to <span class="command"><strong>named</strong></span>. Relying on this is not + recommended, however, as it requires <span class="command"><strong>named</strong></span> + to be recompiled with a new key when the root key expires.) + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + <span class="command"><strong>named</strong></span> <span class="emphasis"><em>only</em></span> + loads the root key from <code class="filename">bind.keys</code>. + The file cannot be used to store keys for other zones. + The root key in <code class="filename">bind.keys</code> is ignored + if <span class="command"><strong>dnssec-validation auto</strong></span> is not in + use. + </p> + <p> + Whenever the resolver sends out queries to an + EDNS-compliant server, it always sets the DO bit + indicating it can support DNSSEC responses even if + <span class="command"><strong>dnssec-validation</strong></span> is off. + </p> + </div> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-accept-expired</strong></span></span></dt> +<dd> + <p> + Accept expired signatures when verifying DNSSEC signatures. + The default is <strong class="userinput"><code>no</code></strong>. + Setting this option to <strong class="userinput"><code>yes</code></strong> + leaves <span class="command"><strong>named</strong></span> vulnerable to + replay attacks. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>querylog</strong></span></span></dt> +<dd> + <p> + Specify whether query logging should be started when <span class="command"><strong>named</strong></span> + starts. + If <span class="command"><strong>querylog</strong></span> is not specified, + then the query logging + is determined by the presence of the logging category <span class="command"><strong>queries</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-names</strong></span></span></dt> +<dd> + <p> + This option is used to restrict the character set and syntax + of + certain domain names in master files and/or DNS responses + received + from the network. The default varies according to usage + area. For + <span class="command"><strong>master</strong></span> zones the default is <span class="command"><strong>fail</strong></span>. + For <span class="command"><strong>slave</strong></span> zones the default + is <span class="command"><strong>warn</strong></span>. + For answers received from the network (<span class="command"><strong>response</strong></span>) + the default is <span class="command"><strong>ignore</strong></span>. + </p> + <p> + The rules for legal hostnames and mail domains are derived + from RFC 952 and RFC 821 as modified by RFC 1123. + </p> + <p><span class="command"><strong>check-names</strong></span> + applies to the owner names of A, AAAA and MX records. + It also applies to the domain names in the RDATA of NS, SOA, + MX, and SRV records. + It also applies to the RDATA of PTR records where the owner + name indicated that it is a reverse lookup of a hostname + (the owner name ends in IN-ADDR.ARPA, IP6.ARPA, or IP6.INT). + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-dup-records</strong></span></span></dt> +<dd> + <p> + Check master zones for records that are treated as different + by DNSSEC but are semantically equal in plain DNS. The + default is to <span class="command"><strong>warn</strong></span>. Other possible + values are <span class="command"><strong>fail</strong></span> and + <span class="command"><strong>ignore</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-mx</strong></span></span></dt> +<dd> + <p> + Check whether the MX record appears to refer to a IP address. + The default is to <span class="command"><strong>warn</strong></span>. Other possible + values are <span class="command"><strong>fail</strong></span> and + <span class="command"><strong>ignore</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-wildcard</strong></span></span></dt> +<dd> + <p> + This option is used to check for non-terminal wildcards. + The use of non-terminal wildcards is almost always as a + result of a failure + to understand the wildcard matching algorithm (RFC 1034). + This option + affects master zones. The default (<span class="command"><strong>yes</strong></span>) is to check + for non-terminal wildcards and issue a warning. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-integrity</strong></span></span></dt> +<dd> + <p> + Perform post load zone integrity checks on master + zones. This checks that MX and SRV records refer + to address (A or AAAA) records and that glue + address records exist for delegated zones. For + MX and SRV records only in-zone hostnames are + checked (for out-of-zone hostnames use + <span class="command"><strong>named-checkzone</strong></span>). + For NS records only names below top of zone are + checked (for out-of-zone names and glue consistency + checks use <span class="command"><strong>named-checkzone</strong></span>). + The default is <span class="command"><strong>yes</strong></span>. + </p> + <p> + The use of the SPF record for publishing Sender + Policy Framework is deprecated as the migration + from using TXT records to SPF records was abandoned. + Enabling this option also checks that a TXT Sender + Policy Framework record exists (starts with "v=spf1") + if there is an SPF record. Warnings are emitted if the + TXT record does not exist and can be suppressed with + <span class="command"><strong>check-spf</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-mx-cname</strong></span></span></dt> +<dd> + <p> + If <span class="command"><strong>check-integrity</strong></span> is set then + fail, warn or ignore MX records that refer + to CNAMES. The default is to <span class="command"><strong>warn</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-srv-cname</strong></span></span></dt> +<dd> + <p> + If <span class="command"><strong>check-integrity</strong></span> is set then + fail, warn or ignore SRV records that refer + to CNAMES. The default is to <span class="command"><strong>warn</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-sibling</strong></span></span></dt> +<dd> + <p> + When performing integrity checks, also check that + sibling glue exists. The default is <span class="command"><strong>yes</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-spf</strong></span></span></dt> +<dd> + <p> + If <span class="command"><strong>check-integrity</strong></span> is set then + check that there is a TXT Sender Policy Framework + record present (starts with "v=spf1") if there is an + SPF record present. The default is + <span class="command"><strong>warn</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>zero-no-soa-ttl</strong></span></span></dt> +<dd> + <p> + When returning authoritative negative responses to + SOA queries set the TTL of the SOA record returned in + the authority section to zero. + The default is <span class="command"><strong>yes</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>zero-no-soa-ttl-cache</strong></span></span></dt> +<dd> + <p> + When caching a negative response to a SOA query + set the TTL to zero. + The default is <span class="command"><strong>no</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>update-check-ksk</strong></span></span></dt> +<dd> + <p> + When set to the default value of <code class="literal">yes</code>, + check the KSK bit in each key to determine how the key + should be used when generating RRSIGs for a secure zone. + </p> + <p> + Ordinarily, zone-signing keys (that is, keys without the + KSK bit set) are used to sign the entire zone, while + key-signing keys (keys with the KSK bit set) are only + used to sign the DNSKEY RRset at the zone apex. + However, if this option is set to <code class="literal">no</code>, + then the KSK bit is ignored; KSKs are treated as if they + were ZSKs and are used to sign the entire zone. This is + similar to the <span class="command"><strong>dnssec-signzone -z</strong></span> + command line option. + </p> + <p> + When this option is set to <code class="literal">yes</code>, there + must be at least two active keys for every algorithm + represented in the DNSKEY RRset: at least one KSK and one + ZSK per algorithm. If there is any algorithm for which + this requirement is not met, this option will be ignored + for that algorithm. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-dnskey-kskonly</strong></span></span></dt> +<dd> + <p> + When this option and <span class="command"><strong>update-check-ksk</strong></span> + are both set to <code class="literal">yes</code>, only key-signing + keys (that is, keys with the KSK bit set) will be used + to sign the DNSKEY RRset at the zone apex. Zone-signing + keys (keys without the KSK bit set) will be used to sign + the remainder of the zone, but not the DNSKEY RRset. + This is similar to the + <span class="command"><strong>dnssec-signzone -x</strong></span> command line option. + </p> + <p> + The default is <span class="command"><strong>no</strong></span>. If + <span class="command"><strong>update-check-ksk</strong></span> is set to + <code class="literal">no</code>, this option is ignored. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>try-tcp-refresh</strong></span></span></dt> +<dd> + <p> + Try to refresh the zone using TCP if UDP queries fail. + For BIND 8 compatibility, the default is + <span class="command"><strong>yes</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-secure-to-insecure</strong></span></span></dt> +<dd> + <p> + Allow a dynamic zone to transition from secure to + insecure (i.e., signed to unsigned) by deleting all + of the DNSKEY records. The default is <span class="command"><strong>no</strong></span>. + If set to <span class="command"><strong>yes</strong></span>, and if the DNSKEY RRset + at the zone apex is deleted, all RRSIG and NSEC records + will be removed from the zone as well. + </p> + <p> + If the zone uses NSEC3, then it is also necessary to + delete the NSEC3PARAM RRset from the zone apex; this will + cause the removal of all corresponding NSEC3 records. + (It is expected that this requirement will be eliminated + in a future release.) + </p> + <p> + Note that if a zone has been configured with + <span class="command"><strong>auto-dnssec maintain</strong></span> and the + private keys remain accessible in the key repository, + then the zone will be automatically signed again the + next time <span class="command"><strong>named</strong></span> is started. + </p> + </dd> +</dl></div> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="forwarding"></a>Forwarding</h4></div></div></div> + + <p> + The forwarding facility can be used to create a large site-wide + cache on a few servers, reducing traffic over links to external + name servers. It can also be used to allow queries by servers that + do not have direct access to the Internet, but wish to look up + exterior + names anyway. Forwarding occurs only on those queries for which + the server is not authoritative and does not have the answer in + its cache. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>forward</strong></span></span></dt> +<dd> + <p> + This option is only meaningful if the + forwarders list is not empty. A value of <code class="varname">first</code>, + the default, causes the server to query the forwarders + first — and + if that doesn't answer the question, the server will then + look for + the answer itself. If <code class="varname">only</code> is + specified, the + server will only query the forwarders. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>forwarders</strong></span></span></dt> +<dd> + <p> + Specifies the IP addresses to be used + for forwarding. The default is the empty list (no + forwarding). + </p> + </dd> +</dl></div> + + <p> + Forwarding can also be configured on a per-domain basis, allowing + for the global forwarding options to be overridden in a variety + of ways. You can set particular domains to use different + forwarders, + or have a different <span class="command"><strong>forward only/first</strong></span> behavior, + or not forward at all, see <a class="xref" href="Bv9ARM.ch06.html#zone_statement_grammar" title="zone Statement Grammar">the section called “<span class="command"><strong>zone</strong></span> + Statement Grammar”</a>. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="dual_stack"></a>Dual-stack Servers</h4></div></div></div> + + <p> + Dual-stack servers are used as servers of last resort to work + around + problems in reachability due the lack of support for either IPv4 + or IPv6 + on the host machine. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>dual-stack-servers</strong></span></span></dt> +<dd> + <p> + Specifies host names or addresses of machines with access to + both IPv4 and IPv6 transports. If a hostname is used, the + server must be able + to resolve the name using only the transport it has. If the + machine is dual + stacked, then the <span class="command"><strong>dual-stack-servers</strong></span> have no effect unless + access to a transport has been disabled on the command line + (e.g. <span class="command"><strong>named -4</strong></span>). + </p> + </dd> +</dl></div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="access_control"></a>Access Control</h4></div></div></div> + + + <p> + Access to the server can be restricted based on the IP address + of the requesting system. See <a class="xref" href="Bv9ARM.ch06.html#address_match_lists" title="Address Match Lists">the section called “Address Match Lists”</a> for + details on how to specify IP address lists. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>allow-notify</strong></span></span></dt> +<dd> + <p> + Specifies which hosts are allowed to + notify this server, a slave, of zone changes in addition + to the zone masters. + <span class="command"><strong>allow-notify</strong></span> may also be + specified in the + <span class="command"><strong>zone</strong></span> statement, in which case + it overrides the + <span class="command"><strong>options allow-notify</strong></span> + statement. It is only meaningful + for a slave zone. If not specified, the default is to + process notify messages + only from a zone's master. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-query</strong></span></span></dt> +<dd> + <p> + Specifies which hosts are allowed to ask ordinary + DNS questions. <span class="command"><strong>allow-query</strong></span> may + also be specified in the <span class="command"><strong>zone</strong></span> + statement, in which case it overrides the + <span class="command"><strong>options allow-query</strong></span> statement. + If not specified, the default is to allow queries + from all hosts. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + <span class="command"><strong>allow-query-cache</strong></span> is now + used to specify access to the cache. + </p> + </div> + </dd> +<dt><span class="term"><span class="command"><strong>allow-query-on</strong></span></span></dt> +<dd> + <p> + Specifies which local addresses can accept ordinary + DNS questions. This makes it possible, for instance, + to allow queries on internal-facing interfaces but + disallow them on external-facing ones, without + necessarily knowing the internal network's addresses. + </p> + <p> + Note that <span class="command"><strong>allow-query-on</strong></span> is only + checked for queries that are permitted by + <span class="command"><strong>allow-query</strong></span>. A query must be + allowed by both ACLs, or it will be refused. + </p> + <p> + <span class="command"><strong>allow-query-on</strong></span> may + also be specified in the <span class="command"><strong>zone</strong></span> + statement, in which case it overrides the + <span class="command"><strong>options allow-query-on</strong></span> statement. + </p> + <p> + If not specified, the default is to allow queries + on all addresses. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + <span class="command"><strong>allow-query-cache</strong></span> is + used to specify access to the cache. + </p> + </div> + </dd> +<dt><span class="term"><span class="command"><strong>allow-query-cache</strong></span></span></dt> +<dd> + <p> + Specifies which hosts are allowed to get answers + from the cache. If <span class="command"><strong>allow-query-cache</strong></span> + is not set then <span class="command"><strong>allow-recursion</strong></span> + is used if set, otherwise <span class="command"><strong>allow-query</strong></span> + is used if set unless <span class="command"><strong>recursion no;</strong></span> is + set in which case <span class="command"><strong>none;</strong></span> is used, + otherwise the default (<span class="command"><strong>localnets;</strong></span> + <span class="command"><strong>localhost;</strong></span>) is used. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-query-cache-on</strong></span></span></dt> +<dd> + <p> + Specifies which local addresses can give answers + from the cache. If not specified, the default is + to allow cache queries on any address, + <span class="command"><strong>localnets</strong></span> and + <span class="command"><strong>localhost</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-recursion</strong></span></span></dt> +<dd> + <p> + Specifies which hosts are allowed to make recursive + queries through this server. If + <span class="command"><strong>allow-recursion</strong></span> is not set + then <span class="command"><strong>allow-query-cache</strong></span> is + used if set, otherwise <span class="command"><strong>allow-query</strong></span> + is used if set, otherwise the default + (<span class="command"><strong>localnets;</strong></span> + <span class="command"><strong>localhost;</strong></span>) is used. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-recursion-on</strong></span></span></dt> +<dd> + <p> + Specifies which local addresses can accept recursive + queries. If not specified, the default is to allow + recursive queries on all addresses. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-update</strong></span></span></dt> +<dd> + <p> + Specifies which hosts are allowed to + submit Dynamic DNS updates for master zones. The default is + to deny + updates from all hosts. Note that allowing updates based + on the requestor's IP address is insecure; see + <a class="xref" href="Bv9ARM.ch07.html#dynamic_update_security" title="Dynamic Update Security">the section called “Dynamic Update Security”</a> for details. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-update-forwarding</strong></span></span></dt> +<dd> + <p> + Specifies which hosts are allowed to + submit Dynamic DNS updates to slave zones to be forwarded to + the + master. The default is <strong class="userinput"><code>{ none; }</code></strong>, + which + means that no update forwarding will be performed. To + enable + update forwarding, specify + <strong class="userinput"><code>allow-update-forwarding { any; };</code></strong>. + Specifying values other than <strong class="userinput"><code>{ none; }</code></strong> or + <strong class="userinput"><code>{ any; }</code></strong> is usually + counterproductive, since + the responsibility for update access control should rest + with the + master server, not the slaves. + </p> + <p> + Note that enabling the update forwarding feature on a slave + server + may expose master servers relying on insecure IP address + based + access control to attacks; see <a class="xref" href="Bv9ARM.ch07.html#dynamic_update_security" title="Dynamic Update Security">the section called “Dynamic Update Security”</a> + for more details. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-v6-synthesis</strong></span></span></dt> +<dd> + <p> + This option was introduced for the smooth transition from + AAAA + to A6 and from "nibble labels" to binary labels. + However, since both A6 and binary labels were then + deprecated, + this option was also deprecated. + It is now ignored with some warning messages. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-transfer</strong></span></span></dt> +<dd> + <p> + Specifies which hosts are allowed to + receive zone transfers from the server. <span class="command"><strong>allow-transfer</strong></span> may + also be specified in the <span class="command"><strong>zone</strong></span> + statement, in which + case it overrides the <span class="command"><strong>options allow-transfer</strong></span> statement. + If not specified, the default is to allow transfers to all + hosts. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>blackhole</strong></span></span></dt> +<dd> + <p> + Specifies a list of addresses that the + server will not accept queries from or use to resolve a + query. Queries + from these addresses will not be responded to. The default + is <strong class="userinput"><code>none</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>filter-aaaa</strong></span></span></dt> +<dd> + <p> + Specifies a list of addresses to which + <span class="command"><strong>filter-aaaa-on-v4</strong></span> + and <span class="command"><strong>filter-aaaa-on-v6</strong></span> + apply. The default is <strong class="userinput"><code>any</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>keep-response-order</strong></span></span></dt> +<dd> + <p> + Specifies a list of addresses to which the server + will send responses to TCP queries in the same order + in which they were received. This disables the + processing of TCP queries in parallel. The default + is <strong class="userinput"><code>none</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>no-case-compress</strong></span></span></dt> +<dd> + <p> + Specifies a list of addresses which require responses + to use case-insensitive compression. This ACL can be + used when <span class="command"><strong>named</strong></span> needs to work with + clients that do not comply with the requirement in RFC + 1034 to use case-insensitive name comparisons when + checking for matching domain names. + </p> + <p> + If left undefined, the ACL defaults to + <span class="command"><strong>none</strong></span>: case-insensitive compression + will be used for all clients. If the ACL is defined and + matches a client, then case will be ignored when + compressing domain names in DNS responses sent to that + client. + </p> + <p> + This can result in slightly smaller responses: if + a response contains the names "example.com" and + "example.COM", case-insensitive compression would treat + the second one as a duplicate. It also ensures + that the case of the query name exactly matches the + case of the owner names of returned records, rather + than matching the case of the records entered in + the zone file. This allows responses to exactly + match the query, which is required by some clients + due to incorrect use of case-sensitive comparisons. + </p> + <p> + Case-insensitive compression is <span class="emphasis"><em>always</em></span> + used in AXFR and IXFR responses, regardless of whether + the client matches this ACL. + </p> + <p> + There are circumstances in which <span class="command"><strong>named</strong></span> + will not preserve the case of owner names of records: + if a zone file defines records of different types with + the same name, but the capitalization of the name is + different (e.g., "www.example.com/A" and + "WWW.EXAMPLE.COM/AAAA"), then all responses for that + name will use the <span class="emphasis"><em>first</em></span> version + of the name that was used in the zone file. This + limitation may be addressed in a future release. However, + domain names specified in the rdata of resource records + (i.e., records of type NS, MX, CNAME, etc) will always + have their case preserved unless the client matches this + ACL. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>resolver-query-timeout</strong></span></span></dt> +<dd> + <p> + The amount of time in seconds that the resolver + will spend attempting to resolve a recursive + query before failing. The default and minimum + is <code class="literal">10</code> and the maximum is + <code class="literal">30</code>. Setting it to + <code class="literal">0</code> will result in the default + being used. + </p> + </dd> +</dl></div> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="interfaces"></a>Interfaces</h4></div></div></div> + + <p> + The interfaces and ports that the server will answer queries + from may be specified using the <span class="command"><strong>listen-on</strong></span> option. <span class="command"><strong>listen-on</strong></span> takes + an optional port and an <code class="varname">address_match_list</code> + of IPv4 addresses. (IPv6 addresses are ignored, with a + logged warning.) + The server will listen on all interfaces allowed by the address + match list. If a port is not specified, port 53 will be used. + </p> + <p> + Multiple <span class="command"><strong>listen-on</strong></span> statements are + allowed. + For example, + </p> + +<pre class="programlisting">listen-on { 5.6.7.8; }; +listen-on port 1234 { !1.2.3.4; 1.2/16; }; +</pre> + + <p> + will enable the name server on port 53 for the IP address + 5.6.7.8, and on port 1234 of an address on the machine in net + 1.2 that is not 1.2.3.4. + </p> + + <p> + If no <span class="command"><strong>listen-on</strong></span> is specified, the + server will listen on port 53 on all IPv4 interfaces. + </p> + + <p> + The <span class="command"><strong>listen-on-v6</strong></span> option is used to + specify the interfaces and the ports on which the server will + listen for incoming queries sent using IPv6. If not specified, + the server will listen on port 53 on all IPv6 interfaces. + </p> + + <p> + When </p> +<pre class="programlisting">{ any; }</pre> +<p> is + specified + as the <code class="varname">address_match_list</code> for the + <span class="command"><strong>listen-on-v6</strong></span> option, + the server does not bind a separate socket to each IPv6 interface + address as it does for IPv4 if the operating system has enough API + support for IPv6 (specifically if it conforms to RFC 3493 and RFC + 3542). + Instead, it listens on the IPv6 wildcard address. + If the system only has incomplete API support for IPv6, however, + the behavior is the same as that for IPv4. + </p> + + <p> + A list of particular IPv6 addresses can also be specified, in + which case + the server listens on a separate socket for each specified + address, + regardless of whether the desired API is supported by the system. + IPv4 addresses specified in <span class="command"><strong>listen-on-v6</strong></span> + will be ignored, with a logged warning. + </p> + + <p> + Multiple <span class="command"><strong>listen-on-v6</strong></span> options can + be used. + For example, + </p> + +<pre class="programlisting">listen-on-v6 { any; }; +listen-on-v6 port 1234 { !2001:db8::/32; any; }; +</pre> + + <p> + will enable the name server on port 53 for any IPv6 addresses + (with a single wildcard socket), + and on port 1234 of IPv6 addresses that is not in the prefix + 2001:db8::/32 (with separate sockets for each matched address.) + </p> + + <p> + To make the server not listen on any IPv6 address, use + </p> + +<pre class="programlisting">listen-on-v6 { none; }; +</pre> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="query_address"></a>Query Address</h4></div></div></div> + + <p> + If the server doesn't know the answer to a question, it will + query other name servers. <span class="command"><strong>query-source</strong></span> specifies + the address and port used for such queries. For queries sent over + IPv6, there is a separate <span class="command"><strong>query-source-v6</strong></span> option. + If <span class="command"><strong>address</strong></span> is <span class="command"><strong>*</strong></span> (asterisk) or is omitted, + a wildcard IP address (<span class="command"><strong>INADDR_ANY</strong></span>) + will be used. + </p> + + <p> + If <span class="command"><strong>port</strong></span> is <span class="command"><strong>*</strong></span> or is omitted, + a random port number from a pre-configured + range is picked up and will be used for each query. + The port range(s) is that specified in + the <span class="command"><strong>use-v4-udp-ports</strong></span> (for IPv4) + and <span class="command"><strong>use-v6-udp-ports</strong></span> (for IPv6) + options, excluding the ranges specified in + the <span class="command"><strong>avoid-v4-udp-ports</strong></span> + and <span class="command"><strong>avoid-v6-udp-ports</strong></span> options, respectively. + </p> + + <p> + The defaults of the <span class="command"><strong>query-source</strong></span> and + <span class="command"><strong>query-source-v6</strong></span> options + are: + </p> + +<pre class="programlisting">query-source address * port *; +query-source-v6 address * port *; +</pre> + + <p> + If <span class="command"><strong>use-v4-udp-ports</strong></span> or + <span class="command"><strong>use-v6-udp-ports</strong></span> is unspecified, + <span class="command"><strong>named</strong></span> will check if the operating + system provides a programming interface to retrieve the + system's default range for ephemeral ports. + If such an interface is available, + <span class="command"><strong>named</strong></span> will use the corresponding system + default range; otherwise, it will use its own defaults: + </p> + +<pre class="programlisting">use-v4-udp-ports { range 1024 65535; }; +use-v6-udp-ports { range 1024 65535; }; +</pre> + + <p> + Note: make sure the ranges be sufficiently large for + security. A desirable size depends on various parameters, + but we generally recommend it contain at least 16384 ports + (14 bits of entropy). + Note also that the system's default range when used may be + too small for this purpose, and that the range may even be + changed while <span class="command"><strong>named</strong></span> is running; the new + range will automatically be applied when <span class="command"><strong>named</strong></span> + is reloaded. + It is encouraged to + configure <span class="command"><strong>use-v4-udp-ports</strong></span> and + <span class="command"><strong>use-v6-udp-ports</strong></span> explicitly so that the + ranges are sufficiently large and are reasonably + independent from the ranges used by other applications. + </p> + + <p> + Note: the operational configuration + where <span class="command"><strong>named</strong></span> runs may prohibit the use + of some ports. For example, UNIX systems will not allow + <span class="command"><strong>named</strong></span> running without a root privilege + to use ports less than 1024. + If such ports are included in the specified (or detected) + set of query ports, the corresponding query attempts will + fail, resulting in resolution failures or delay. + It is therefore important to configure the set of ports + that can be safely used in the expected operational environment. + </p> + + <p> + The defaults of the <span class="command"><strong>avoid-v4-udp-ports</strong></span> and + <span class="command"><strong>avoid-v6-udp-ports</strong></span> options + are: + </p> + +<pre class="programlisting">avoid-v4-udp-ports {}; +avoid-v6-udp-ports {}; +</pre> + + <p> + Note: BIND 9.5.0 introduced + the <span class="command"><strong>use-queryport-pool</strong></span> + option to support a pool of such random ports, but this + option is now obsolete because reusing the same ports in + the pool may not be sufficiently secure. + For the same reason, it is generally strongly discouraged to + specify a particular port for the + <span class="command"><strong>query-source</strong></span> or + <span class="command"><strong>query-source-v6</strong></span> options; + it implicitly disables the use of randomized port numbers. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>use-queryport-pool</strong></span></span></dt> +<dd> + <p> + This option is obsolete. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>queryport-pool-ports</strong></span></span></dt> +<dd> + <p> + This option is obsolete. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>queryport-pool-updateinterval</strong></span></span></dt> +<dd> + <p> + This option is obsolete. + </p> + </dd> +</dl></div> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + The address specified in the <span class="command"><strong>query-source</strong></span> option + is used for both UDP and TCP queries, but the port applies only + to UDP queries. TCP queries always use a random + unprivileged port. + </p> + </div> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + Solaris 2.5.1 and earlier does not support setting the source + address for TCP sockets. + </p> + </div> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + See also <span class="command"><strong>transfer-source</strong></span> and + <span class="command"><strong>notify-source</strong></span>. + </p> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="zone_transfers"></a>Zone Transfers</h4></div></div></div> + + <p> + <acronym class="acronym">BIND</acronym> has mechanisms in place to + facilitate zone transfers + and set limits on the amount of load that transfers place on the + system. The following options apply to zone transfers. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>also-notify</strong></span></span></dt> +<dd> + <p> + Defines a global list of IP addresses of name servers + that are also sent NOTIFY messages whenever a fresh copy of + the + zone is loaded, in addition to the servers listed in the + zone's NS records. + This helps to ensure that copies of the zones will + quickly converge on stealth servers. + Optionally, a port may be specified with each + <span class="command"><strong>also-notify</strong></span> address to send + the notify messages to a port other than the + default of 53. + An optional TSIG key can also be specified with each + address to cause the notify messages to be signed; this + can be useful when sending notifies to multiple views. + In place of explicit addresses, one or more named + <span class="command"><strong>masters</strong></span> lists can be used. + </p> + <p> + If an <span class="command"><strong>also-notify</strong></span> list + is given in a <span class="command"><strong>zone</strong></span> statement, + it will override + the <span class="command"><strong>options also-notify</strong></span> + statement. When a <span class="command"><strong>zone notify</strong></span> + statement + is set to <span class="command"><strong>no</strong></span>, the IP + addresses in the global <span class="command"><strong>also-notify</strong></span> list will + not be sent NOTIFY messages for that zone. The default is + the empty + list (no global notification list). + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-transfer-time-in</strong></span></span></dt> +<dd> + <p> + Inbound zone transfers running longer than + this many minutes will be terminated. The default is 120 + minutes + (2 hours). The maximum value is 28 days (40320 minutes). + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-transfer-idle-in</strong></span></span></dt> +<dd> + <p> + Inbound zone transfers making no progress + in this many minutes will be terminated. The default is 60 + minutes + (1 hour). The maximum value is 28 days (40320 minutes). + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-transfer-time-out</strong></span></span></dt> +<dd> + <p> + Outbound zone transfers running longer than + this many minutes will be terminated. The default is 120 + minutes + (2 hours). The maximum value is 28 days (40320 minutes). + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-transfer-idle-out</strong></span></span></dt> +<dd> + <p> + Outbound zone transfers making no progress + in this many minutes will be terminated. The default is 60 + minutes (1 + hour). The maximum value is 28 days (40320 minutes). + </p> + </dd> +<dt><span class="term"><span class="command"><strong>notify-rate</strong></span></span></dt> +<dd> + <p> + The rate at which NOTIFY requests will be sent + during normal zone maintenance operations. (NOTIFY + requests due to initial zone loading are subject + to a separate rate limit; see below.) The default is + 20 per second. + The lowest possible rate is one per second; when set + to zero, it will be silently raised to one. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>startup-notify-rate</strong></span></span></dt> +<dd> + <p> + The rate at which NOTIFY requests will be sent + when the name server is first starting up, or when + zones have been newly added to the nameserver. + The default is 20 per second. + The lowest possible rate is one per second; when set + to zero, it will be silently raised to one. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>serial-query-rate</strong></span></span></dt> +<dd> + <p> + Slave servers will periodically query master + servers to find out if zone serial numbers have + changed. Each such query uses a minute amount of + the slave server's network bandwidth. To limit + the amount of bandwidth used, BIND 9 limits the + rate at which queries are sent. The value of the + <span class="command"><strong>serial-query-rate</strong></span> option, an + integer, is the maximum number of queries sent + per second. The default is 20 per second. + The lowest possible rate is one per second; when set + to zero, it will be silently raised to one. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>serial-queries</strong></span></span></dt> +<dd> + <p> + In BIND 8, the <span class="command"><strong>serial-queries</strong></span> + option + set the maximum number of concurrent serial number queries + allowed to be outstanding at any given time. + BIND 9 does not limit the number of outstanding + serial queries and ignores the <span class="command"><strong>serial-queries</strong></span> option. + Instead, it limits the rate at which the queries are sent + as defined using the <span class="command"><strong>serial-query-rate</strong></span> option. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>transfer-format</strong></span></span></dt> +<dd> + + <p> + Zone transfers can be sent using two different formats, + <span class="command"><strong>one-answer</strong></span> and + <span class="command"><strong>many-answers</strong></span>. + The <span class="command"><strong>transfer-format</strong></span> option is used + on the master server to determine which format it sends. + <span class="command"><strong>one-answer</strong></span> uses one DNS message per + resource record transferred. + <span class="command"><strong>many-answers</strong></span> packs as many resource + records as possible into a message. + <span class="command"><strong>many-answers</strong></span> is more efficient, but is + only supported by relatively new slave servers, + such as <acronym class="acronym">BIND</acronym> 9, <acronym class="acronym">BIND</acronym> + 8.x and <acronym class="acronym">BIND</acronym> 4.9.5 onwards. + The <span class="command"><strong>many-answers</strong></span> format is also supported by + recent Microsoft Windows nameservers. + The default is <span class="command"><strong>many-answers</strong></span>. + <span class="command"><strong>transfer-format</strong></span> may be overridden on a + per-server basis by using the <span class="command"><strong>server</strong></span> + statement. + </p> + + </dd> +<dt><span class="term"><span class="command"><strong>transfer-message-size</strong></span></span></dt> +<dd> + <p> + This is an upper bound on the uncompressed size of DNS + messages used in zone transfers over TCP. If a message + grows larger than this size, additional messages will be + used to complete the zone transfer. (Note, however, + that this is a hint, not a hard limit; if a message + contains a single resource record whose RDATA does not + fit within the size limit, a larger message will be + permitted so the record can be transferred.) + </p> + <p> + Valid values are between 512 and 65535 octets, and any + values outside that range will be adjusted to the nearest + value within it. The default is <code class="literal">20480</code>, + which was selected to improve message compression: + most DNS messages of this size will compress to less + than 16536 bytes. Larger messages cannot be compressed + as effectively, because 16536 is the largest permissible + compression offset pointer in a DNS message. + </p> + <p> + This option is mainly intended for server testing; + there is rarely any benefit in setting a value other + than the default. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>transfers-in</strong></span></span></dt> +<dd> + <p> + The maximum number of inbound zone transfers + that can be running concurrently. The default value is <code class="literal">10</code>. + Increasing <span class="command"><strong>transfers-in</strong></span> may + speed up the convergence + of slave zones, but it also may increase the load on the + local system. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>transfers-out</strong></span></span></dt> +<dd> + <p> + The maximum number of outbound zone transfers + that can be running concurrently. Zone transfer requests in + excess + of the limit will be refused. The default value is <code class="literal">10</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>transfers-per-ns</strong></span></span></dt> +<dd> + <p> + The maximum number of inbound zone transfers + that can be concurrently transferring from a given remote + name server. + The default value is <code class="literal">2</code>. + Increasing <span class="command"><strong>transfers-per-ns</strong></span> + may + speed up the convergence of slave zones, but it also may + increase + the load on the remote name server. <span class="command"><strong>transfers-per-ns</strong></span> may + be overridden on a per-server basis by using the <span class="command"><strong>transfers</strong></span> phrase + of the <span class="command"><strong>server</strong></span> statement. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>transfer-source</strong></span></span></dt> +<dd> + <p><span class="command"><strong>transfer-source</strong></span> + determines which local address will be bound to IPv4 + TCP connections used to fetch zones transferred + inbound by the server. It also determines the + source IPv4 address, and optionally the UDP port, + used for the refresh queries and forwarded dynamic + updates. If not set, it defaults to a system + controlled value which will usually be the address + of the interface "closest to" the remote end. This + address must appear in the remote end's + <span class="command"><strong>allow-transfer</strong></span> option for the + zone being transferred, if one is specified. This + statement sets the + <span class="command"><strong>transfer-source</strong></span> for all zones, + but can be overridden on a per-view or per-zone + basis by including a + <span class="command"><strong>transfer-source</strong></span> statement within + the <span class="command"><strong>view</strong></span> or + <span class="command"><strong>zone</strong></span> block in the configuration + file. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + Solaris 2.5.1 and earlier does not support setting the + source address for TCP sockets. + </p> + </div> + </dd> +<dt><span class="term"><span class="command"><strong>transfer-source-v6</strong></span></span></dt> +<dd> + <p> + The same as <span class="command"><strong>transfer-source</strong></span>, + except zone transfers are performed using IPv6. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>alt-transfer-source</strong></span></span></dt> +<dd> + <p> + An alternate transfer source if the one listed in + <span class="command"><strong>transfer-source</strong></span> fails and + <span class="command"><strong>use-alt-transfer-source</strong></span> is + set. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> +<p> + If you do not wish the alternate transfer source + to be used, you should set + <span class="command"><strong>use-alt-transfer-source</strong></span> + appropriately and you should not depend upon + getting an answer back to the first refresh + query. + </p> +</div> + </dd> +<dt><span class="term"><span class="command"><strong>alt-transfer-source-v6</strong></span></span></dt> +<dd> + <p> + An alternate transfer source if the one listed in + <span class="command"><strong>transfer-source-v6</strong></span> fails and + <span class="command"><strong>use-alt-transfer-source</strong></span> is + set. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>use-alt-transfer-source</strong></span></span></dt> +<dd> + <p> + Use the alternate transfer sources or not. If views are + specified this defaults to <span class="command"><strong>no</strong></span> + otherwise it defaults to + <span class="command"><strong>yes</strong></span> (for BIND 8 + compatibility). + </p> + </dd> +<dt><span class="term"><span class="command"><strong>notify-source</strong></span></span></dt> +<dd> + <p><span class="command"><strong>notify-source</strong></span> + determines which local source address, and + optionally UDP port, will be used to send NOTIFY + messages. This address must appear in the slave + server's <span class="command"><strong>masters</strong></span> zone clause or + in an <span class="command"><strong>allow-notify</strong></span> clause. This + statement sets the <span class="command"><strong>notify-source</strong></span> + for all zones, but can be overridden on a per-zone or + per-view basis by including a + <span class="command"><strong>notify-source</strong></span> statement within + the <span class="command"><strong>zone</strong></span> or + <span class="command"><strong>view</strong></span> block in the configuration + file. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + Solaris 2.5.1 and earlier does not support setting the + source address for TCP sockets. + </p> + </div> + </dd> +<dt><span class="term"><span class="command"><strong>notify-source-v6</strong></span></span></dt> +<dd> + <p> + Like <span class="command"><strong>notify-source</strong></span>, + but applies to notify messages sent to IPv6 addresses. + </p> + </dd> +</dl></div> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="port_lists"></a>UDP Port Lists</h4></div></div></div> + + <p> + <span class="command"><strong>use-v4-udp-ports</strong></span>, + <span class="command"><strong>avoid-v4-udp-ports</strong></span>, + <span class="command"><strong>use-v6-udp-ports</strong></span>, and + <span class="command"><strong>avoid-v6-udp-ports</strong></span> + specify a list of IPv4 and IPv6 UDP ports that will be + used or not used as source ports for UDP messages. + See <a class="xref" href="Bv9ARM.ch06.html#query_address" title="Query Address">the section called “Query Address”</a> about how the + available ports are determined. + For example, with the following configuration + </p> + +<pre class="programlisting"> +use-v6-udp-ports { range 32768 65535; }; +avoid-v6-udp-ports { 40000; range 50000 60000; }; +</pre> + + <p> + UDP ports of IPv6 messages sent + from <span class="command"><strong>named</strong></span> will be in one + of the following ranges: 32768 to 39999, 40001 to 49999, + and 60001 to 65535. + </p> + + <p> + <span class="command"><strong>avoid-v4-udp-ports</strong></span> and + <span class="command"><strong>avoid-v6-udp-ports</strong></span> can be used + to prevent <span class="command"><strong>named</strong></span> from choosing as its random source port a + port that is blocked by your firewall or a port that is + used by other applications; + if a query went out with a source port blocked by a + firewall, the + answer would not get by the firewall and the name server would + have to query again. + Note: the desired range can also be represented only with + <span class="command"><strong>use-v4-udp-ports</strong></span> and + <span class="command"><strong>use-v6-udp-ports</strong></span>, and the + <span class="command"><strong>avoid-</strong></span> options are redundant in that + sense; they are provided for backward compatibility and + to possibly simplify the port specification. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="resource_limits"></a>Operating System Resource Limits</h4></div></div></div> + + <p> + The server's usage of many system resources can be limited. + Scaled values are allowed when specifying resource limits. For + example, <span class="command"><strong>1G</strong></span> can be used instead of + <span class="command"><strong>1073741824</strong></span> to specify a limit of + one + gigabyte. <span class="command"><strong>unlimited</strong></span> requests + unlimited use, or the + maximum available amount. <span class="command"><strong>default</strong></span> + uses the limit + that was in force when the server was started. See the description + of <span class="command"><strong>size_spec</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#configuration_file_elements" title="Configuration File Elements">the section called “Configuration File Elements”</a>. + </p> + + <p> + The following options set operating system resource limits for + the name server process. Some operating systems don't support + some or + any of the limits. On such systems, a warning will be issued if + the + unsupported limit is used. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>coresize</strong></span></span></dt> +<dd> + <p> + The maximum size of a core dump. The default + is <code class="literal">default</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>datasize</strong></span></span></dt> +<dd> + <p> + The maximum amount of data memory the server + may use. The default is <code class="literal">default</code>. + This is a hard limit on server memory usage. + If the server attempts to allocate memory in excess of this + limit, the allocation will fail, which may in turn leave + the server unable to perform DNS service. Therefore, + this option is rarely useful as a way of limiting the + amount of memory used by the server, but it can be used + to raise an operating system data size limit that is + too small by default. If you wish to limit the amount + of memory used by the server, use the + <span class="command"><strong>max-cache-size</strong></span> and + <span class="command"><strong>recursive-clients</strong></span> + options instead. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>files</strong></span></span></dt> +<dd> + <p> + The maximum number of files the server + may have open concurrently. The default is <code class="literal">unlimited</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>stacksize</strong></span></span></dt> +<dd> + <p> + The maximum amount of stack memory the server + may use. The default is <code class="literal">default</code>. + </p> + </dd> +</dl></div> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="server_resource_limits"></a>Server Resource Limits</h4></div></div></div> + + <p> + The following options set limits on the server's + resource consumption that are enforced internally by the + server rather than the operating system. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>max-ixfr-log-size</strong></span></span></dt> +<dd> + <p> + This option is obsolete; it is accepted + and ignored for BIND 8 compatibility. The option + <span class="command"><strong>max-journal-size</strong></span> performs a + similar function in BIND 9. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-journal-size</strong></span></span></dt> +<dd> + <p> + Sets a maximum size for each journal file + (see <a class="xref" href="Bv9ARM.ch04.html#journal" title="The journal file">the section called “The journal file”</a>). When the journal file + approaches + the specified size, some of the oldest transactions in the + journal + will be automatically removed. The largest permitted + value is 2 gigabytes. The default is + <code class="literal">unlimited</code>, which also + means 2 gigabytes. + This may also be set on a per-zone basis. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-records</strong></span></span></dt> +<dd> + <p> + The maximum number of records permitted in a zone. + The default is zero which means unlimited. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>host-statistics-max</strong></span></span></dt> +<dd> + <p> + In BIND 8, specifies the maximum number of host statistics + entries to be kept. + Not implemented in BIND 9. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>recursive-clients</strong></span></span></dt> +<dd> + <p> + The maximum number ("hard quota") of simultaneous + recursive lookups the server will perform on behalf + of clients. The default is + <code class="literal">1000</code>. Because each recursing + client uses a fair + bit of memory (on the order of 20 kilobytes), the + value of the + <span class="command"><strong>recursive-clients</strong></span> option may + have to be decreased on hosts with limited memory. + </p> + <p> + <code class="option">recursive-clients</code> defines a "hard + quota" limit for pending recursive clients: when more + clients than this are pending, new incoming requests + will not be accepted, and for each incoming request + a previous pending request will also be dropped. + </p> + <p> + A "soft quota" is also set. When this lower + quota is exceeded, incoming requests are accepted, but + for each one, a pending request will be dropped. + If <code class="option">recursive-clients</code> is greater than + 1000, the soft quota is set to + <code class="option">recursive-clients</code> minus 100; + otherwise it is set to 90% of + <code class="option">recursive-clients</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>tcp-clients</strong></span></span></dt> +<dd> + <p> + The maximum number of simultaneous client TCP + connections that the server will accept. + The default is <code class="literal">150</code>. + </p> + </dd> +<dt> +<a name="clients-per-query"></a><span class="term"><a name="cpq_term"></a><span class="command"><strong>clients-per-query</strong></span>, </span><span class="term"><span class="command"><strong>max-clients-per-query</strong></span></span> +</dt> +<dd> + <p>These set the + initial value (minimum) and maximum number of recursive + simultaneous clients for any given query + (<qname,qtype,qclass>) that the server will accept + before dropping additional clients. <span class="command"><strong>named</strong></span> will attempt to + self tune this value and changes will be logged. The + default values are 10 and 100. + </p> + <p> + This value should reflect how many queries come in for + a given name in the time it takes to resolve that name. + If the number of queries exceed this value, <span class="command"><strong>named</strong></span> will + assume that it is dealing with a non-responsive zone + and will drop additional queries. If it gets a response + after dropping queries, it will raise the estimate. The + estimate will then be lowered in 20 minutes if it has + remained unchanged. + </p> + <p> + If <span class="command"><strong>clients-per-query</strong></span> is set to zero, + then there is no limit on the number of clients per query + and no queries will be dropped. + </p> + <p> + If <span class="command"><strong>max-clients-per-query</strong></span> is set to zero, + then there is no upper bound other than imposed by + <span class="command"><strong>recursive-clients</strong></span>. + </p> + </dd> +<dt> +<a name="fetches-per-zone"></a><span class="term"><span class="command"><strong>fetches-per-zone</strong></span></span> +</dt> +<dd> + <p> + The maximum number of simultaneous iterative + queries to any one domain that the server will + permit before blocking new queries for data + in or beneath that zone. + This value should reflect how many fetches would + normally be sent to any one zone in the time it + would take to resolve them. It should be smaller + than <code class="option">recursive-clients</code>. + </p> + <p> + When many clients simultaneously query for the + same name and type, the clients will all be attached + to the same fetch, up to the + <code class="option">max-clients-per-query</code> limit, + and only one iterative query will be sent. + However, when clients are simultaneously + querying for <span class="emphasis"><em>different</em></span> names + or types, multiple queries will be sent and + <code class="option">max-clients-per-query</code> is not + effective as a limit. + </p> + <p> + Optionally, this value may be followed by the keyword + <code class="literal">drop</code> or <code class="literal">fail</code>, + indicating whether queries which exceed the fetch + quota for a zone will be dropped with no response, + or answered with SERVFAIL. The default is + <code class="literal">drop</code>. + </p> + <p> + If <span class="command"><strong>fetches-per-zone</strong></span> is set to zero, + then there is no limit on the number of fetches per query + and no queries will be dropped. The default is zero. + </p> + <p> + The current list of active fetches can be dumped by + running <span class="command"><strong>rndc recursing</strong></span>. The list + includes the number of active fetches for each + domain and the number of queries that have been + passed or dropped as a result of the + <code class="option">fetches-per-zone</code> limit. (Note: + these counters are not cumulative over time; whenever + the number of active fetches for a domain drops to + zero, the counter for that domain is deleted, and the + next time a fetch is sent to that domain, it is + recreated with the counters set to zero.) + </p> + </dd> +<dt> +<a name="fetches-per-server"></a><span class="term"><span class="command"><strong>fetches-per-server</strong></span></span> +</dt> +<dd> + <p> + The maximum number of simultaneous iterative + queries that the server will allow to be sent to + a single upstream name server before blocking + additional queries. + This value should reflect how many fetches would + normally be sent to any one server in the time it + would take to resolve them. It should be smaller + than <code class="option">recursive-clients</code>. + </p> + <p> + Optionally, this value may be followed by the keyword + <code class="literal">drop</code> or <code class="literal">fail</code>, + indicating whether queries will be dropped with no + response, or answered with SERVFAIL, when all of the + servers authoritative for a zone are found to have + exceeded the per-server quota. The default is + <code class="literal">fail</code>. + </p> + <p> + If <span class="command"><strong>fetches-per-server</strong></span> is set to zero, + then there is no limit on the number of fetches per query + and no queries will be dropped. The default is zero. + </p> + <p> + The <span class="command"><strong>fetches-per-server</strong></span> quota is + dynamically adjusted in response to detected + congestion. As queries are sent to a server + and are either answered or time out, an + exponentially weighted moving average is calculated + of the ratio of timeouts to responses. If the + current average timeout ratio rises above a "high" + threshold, then <span class="command"><strong>fetches-per-server</strong></span> + is reduced for that server. If the timeout ratio + drops below a "low" threshold, then + <span class="command"><strong>fetches-per-server</strong></span> is increased. + The <span class="command"><strong>fetch-quota-params</strong></span> options + can be used to adjust the parameters for this + calculation. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>fetch-quota-params</strong></span></span></dt> +<dd> + <p> + Sets the parameters to use for dynamic resizing of + the <code class="option">fetches-per-server</code> quota in + response to detected congestion. + </p> + <p> + The first argument is an integer value indicating + how frequently to recalculate the moving average + of the ratio of timeouts to responses for each + server. The default is 100, meaning we recalculate + the average ratio after every 100 queries have either + been answered or timed out. + </p> + <p> + The remaining three arguments represent the "low" + threshold (defaulting to a timeout ratio of 0.1), + the "high" threshold (defaulting to a timeout + ratio of 0.3), and the discount rate for + the moving average (defaulting to 0.7). + A higher discount rate causes recent events to + weigh more heavily when calculating the moving + average; a lower discount rate causes past + events to weigh more heavily, smoothing out + short-term blips in the timeout ratio. + These arguments are all fixed-point numbers with + precision of 1/100: at most two places after + the decimal point are significant. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>reserved-sockets</strong></span></span></dt> +<dd> + <p> + The number of file descriptors reserved for TCP, stdio, + etc. This needs to be big enough to cover the number of + interfaces <span class="command"><strong>named</strong></span> listens on, <span class="command"><strong>tcp-clients</strong></span> as well as + to provide room for outgoing TCP queries and incoming zone + transfers. The default is <code class="literal">512</code>. + The minimum value is <code class="literal">128</code> and the + maximum value is <code class="literal">128</code> less than + maxsockets (-S). This option may be removed in the future. + </p> + <p> + This option has little effect on Windows. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-cache-size</strong></span></span></dt> +<dd> + <p> + The maximum amount of memory to use for the + server's cache, in bytes or % of total physical memory. + When the amount of data in the cache + reaches this limit, the server will cause records to + expire prematurely based on an LRU based strategy so + that the limit is not exceeded. + The keyword <strong class="userinput"><code>unlimited</code></strong>, + or the value 0, will place no limit on cache size; + records will be purged from the cache only when their + TTLs expire. + Any positive values less than 2MB will be ignored + and reset to 2MB. + In a server with multiple views, the limit applies + separately to the cache of each view. + The default is <strong class="userinput"><code>90%</code></strong>. + On systems where detection of amount of physical + memory is not supported values represented as % + fall back to unlimited. + Note that the detection of physical memory is done only + once at startup, so <span class="command"><strong>named</strong></span> will not + adjust the cache size if the amount of physical memory + is changed during runtime. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>tcp-listen-queue</strong></span></span></dt> +<dd> + <p> + The listen queue depth. The default and minimum is 10. + If the kernel supports the accept filter "dataready" this + also controls how + many TCP connections that will be queued in kernel space + waiting for + some data before being passed to accept. Nonzero values + less than 10 will be silently raised. A value of 0 may also + be used; on most platforms this sets the listen queue + length to a system-defined default value. + </p> + </dd> +</dl></div> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="intervals"></a>Periodic Task Intervals</h4></div></div></div> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>cleaning-interval</strong></span></span></dt> +<dd> + <p> + This interval is effectively obsolete. Previously, + the server would remove expired resource records + from the cache every <span class="command"><strong>cleaning-interval</strong></span> minutes. + <acronym class="acronym">BIND</acronym> 9 now manages cache + memory in a more sophisticated manner and does not + rely on the periodic cleaning any more. + Specifying this option therefore has no effect on + the server's behavior. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>heartbeat-interval</strong></span></span></dt> +<dd> + <p> + The server will perform zone maintenance tasks + for all zones marked as <span class="command"><strong>dialup</strong></span> whenever this + interval expires. The default is 60 minutes. Reasonable + values are up + to 1 day (1440 minutes). The maximum value is 28 days + (40320 minutes). + If set to 0, no zone maintenance for these zones will occur. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>interface-interval</strong></span></span></dt> +<dd> + <p> + The server will scan the network interface list + every <span class="command"><strong>interface-interval</strong></span> + minutes. The default + is 60 minutes. The maximum value is 28 days (40320 minutes). + If set to 0, interface scanning will only occur when + the configuration file is loaded. After the scan, the + server will + begin listening for queries on any newly discovered + interfaces (provided they are allowed by the + <span class="command"><strong>listen-on</strong></span> configuration), and + will + stop listening on interfaces that have gone away. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>statistics-interval</strong></span></span></dt> +<dd> + <p> + Name server statistics will be logged + every <span class="command"><strong>statistics-interval</strong></span> + minutes. The default is + 60. The maximum value is 28 days (40320 minutes). + If set to 0, no statistics will be logged. + </p> +<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + Not yet implemented in + <acronym class="acronym">BIND</acronym> 9. + </p> + </div> + </dd> +<dt><span class="term"><span class="command"><strong>topology</strong></span></span></dt> +<dd> + <p> + In BIND 8, this option indicated network topology + so that preferential treatment could be given to + the topologicaly closest name servers when sending + queries. It is not implemented in BIND 9. + </p> + </dd> +</dl></div> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="the_sortlist_statement"></a>The <span class="command"><strong>sortlist</strong></span> Statement</h4></div></div></div> + + <p> + The response to a DNS query may consist of multiple resource + records (RRs) forming a resource record set (RRset). The name + server will normally return the RRs within the RRset in an + indeterminate order (but see the <span class="command"><strong>rrset-order</strong></span> + statement in <a class="xref" href="Bv9ARM.ch06.html#rrset_ordering" title="RRset Ordering">the section called “RRset Ordering”</a>). The client + resolver code should rearrange the RRs as appropriate, that is, + using any addresses on the local net in preference to other + addresses. However, not all resolvers can do this or are + correctly configured. When a client is using a local server, + the sorting can be performed in the server, based on the + client's address. This only requires configuring the name + servers, not all the clients. + </p> + + <p> + The <span class="command"><strong>sortlist</strong></span> statement (see below) takes an + <span class="command"><strong>address_match_list</strong></span> and interprets it in a + special way. Each top level statement in the + <span class="command"><strong>sortlist</strong></span> must itself be an explicit + <span class="command"><strong>address_match_list</strong></span> with one or two elements. + The first element (which may be an IP address, an IP prefix, an + ACL name or a nested <span class="command"><strong>address_match_list</strong></span>) of + each top level list is checked against the source address of + the query until a match is found. + </p> + <p> + Once the source address of the query has been matched, if the + top level statement contains only one element, the actual + primitive element that matched the source address is used to + select the address in the response to move to the beginning of + the response. If the statement is a list of two elements, then + the second element is interpreted as a topology preference + list. Each top level element is assigned a distance and the + address in the response with the minimum distance is moved to + the beginning of the response. + </p> + <p> + In the following example, any queries received from any of the + addresses of the host itself will get responses preferring + addresses on any of the locally connected networks. Next most + preferred are addresses on the 192.168.1/24 network, and after + that either the 192.168.2/24 or 192.168.3/24 network with no + preference shown between these two networks. Queries received + from a host on the 192.168.1/24 network will prefer other + addresses on that network to the 192.168.2/24 and 192.168.3/24 + networks. Queries received from a host on the 192.168.4/24 or + the 192.168.5/24 network will only prefer other addresses on + their directly connected networks. + </p> + +<pre class="programlisting">sortlist { + // IF the local host + // THEN first fit on the following nets + { localhost; + { localnets; + 192.168.1/24; + { 192.168.2/24; 192.168.3/24; }; }; }; + // IF on class C 192.168.1 THEN use .1, or .2 or .3 + { 192.168.1/24; + { 192.168.1/24; + { 192.168.2/24; 192.168.3/24; }; }; }; + // IF on class C 192.168.2 THEN use .2, or .1 or .3 + { 192.168.2/24; + { 192.168.2/24; + { 192.168.1/24; 192.168.3/24; }; }; }; + // IF on class C 192.168.3 THEN use .3, or .1 or .2 + { 192.168.3/24; + { 192.168.3/24; + { 192.168.1/24; 192.168.2/24; }; }; }; + // IF .4 or .5 THEN prefer that net + { { 192.168.4/24; 192.168.5/24; }; + }; +};</pre> + + <p> + The following example will give reasonable behavior for the + local host and hosts on directly connected networks. It is + similar to the behavior of the address sort in + <acronym class="acronym">BIND</acronym> 4.9.x. Responses sent to queries from + the local host will favor any of the directly connected + networks. Responses sent to queries from any other hosts on a + directly connected network will prefer addresses on that same + network. Responses to other queries will not be sorted. + </p> + +<pre class="programlisting">sortlist { + { localhost; localnets; }; + { localnets; }; +}; +</pre> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="rrset_ordering"></a>RRset Ordering</h4></div></div></div> + + <p> + When multiple records are returned in an answer it may be + useful to configure the order of the records placed into the + response. + The <span class="command"><strong>rrset-order</strong></span> statement permits + configuration + of the ordering of the records in a multiple record response. + See also the <span class="command"><strong>sortlist</strong></span> statement, + <a class="xref" href="Bv9ARM.ch06.html#the_sortlist_statement" title="The sortlist Statement">the section called “The <span class="command"><strong>sortlist</strong></span> Statement”</a>. + </p> + + <p> + An <span class="command"><strong>order_spec</strong></span> is defined as + follows: + </p> + <p> + [<span class="optional">class <em class="replaceable"><code>class_name</code></em></span>] + [<span class="optional">type <em class="replaceable"><code>type_name</code></em></span>] + [<span class="optional">name <em class="replaceable"><code>"domain_name"</code></em></span>] + order <em class="replaceable"><code>ordering</code></em> + </p> + <p> + If no class is specified, the default is <span class="command"><strong>ANY</strong></span>. + If no type is specified, the default is <span class="command"><strong>ANY</strong></span>. + If no name is specified, the default is "<span class="command"><strong>*</strong></span>" (asterisk). + </p> + <p> + The legal values for <span class="command"><strong>ordering</strong></span> are: + </p> + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="0.750in" class="1"> +<col width="3.750in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p><span class="command"><strong>fixed</strong></span></p> + </td> +<td> + <p> + Records are returned in the order they + are defined in the zone file. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>random</strong></span></p> + </td> +<td> + <p> + Records are returned in some random order. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>cyclic</strong></span></p> + </td> +<td> + <p> + Records are returned in a cyclic round-robin order. + </p> + <p> + If <acronym class="acronym">BIND</acronym> is configured with the + "--enable-fixed-rrset" option at compile time, then + the initial ordering of the RRset will match the + one specified in the zone file. + </p> + </td> +</tr> +</tbody> +</table> + </div> + <p> + For example: + </p> + +<pre class="programlisting">rrset-order { + class IN type A name "host.example.com" order random; + order cyclic; +}; +</pre> + + <p> + will cause any responses for type A records in class IN that + have "<code class="literal">host.example.com</code>" as a + suffix, to always be returned + in random order. All other records are returned in cyclic order. + </p> + <p> + If multiple <span class="command"><strong>rrset-order</strong></span> statements + appear, they are not combined — the last one applies. + </p> + <p> + By default, all records are returned in random order. + </p> + + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + In this release of <acronym class="acronym">BIND</acronym> 9, the + <span class="command"><strong>rrset-order</strong></span> statement does not support + "fixed" ordering by default. Fixed ordering can be enabled + at compile time by specifying "--enable-fixed-rrset" on + the "configure" command line. + </p> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="tuning"></a>Tuning</h4></div></div></div> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>lame-ttl</strong></span></span></dt> +<dd> + <p> + Sets the number of seconds to cache a + lame server indication. 0 disables caching. (This is + <span class="bold"><strong>NOT</strong></span> recommended.) + The default is <code class="literal">600</code> (10 minutes) and the + maximum value is + <code class="literal">1800</code> (30 minutes). + </p> + + </dd> +<dt><span class="term"><span class="command"><strong>servfail-ttl</strong></span></span></dt> +<dd> + <p> + Sets the number of seconds to cache a + SERVFAIL response due to DNSSEC validation failure or + other general server failure. If set to + <code class="literal">0</code>, SERVFAIL caching is disabled. + The SERVFAIL cache is not consulted if a query has + the CD (Checking Disabled) bit set; this allows a + query that failed due to DNSSEC validation to be retried + without waiting for the SERVFAIL TTL to expire. + </p> + <p> + The maximum value is <code class="literal">30</code> + seconds; any higher value will be silently + reduced. The default is <code class="literal">1</code> + second. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-ncache-ttl</strong></span></span></dt> +<dd> + <p> + To reduce network traffic and increase performance, + the server stores negative answers. <span class="command"><strong>max-ncache-ttl</strong></span> is + used to set a maximum retention time for these answers in + the server + in seconds. The default + <span class="command"><strong>max-ncache-ttl</strong></span> is <code class="literal">10800</code> seconds (3 hours). + <span class="command"><strong>max-ncache-ttl</strong></span> cannot exceed + 7 days and will + be silently truncated to 7 days if set to a greater value. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-cache-ttl</strong></span></span></dt> +<dd> + <p> + Sets the maximum time for which the server will + cache ordinary (positive) answers in seconds. + The default is 604800 (one week). + A value of zero may cause all queries to return + SERVFAIL, because of lost caches of intermediate + RRsets (such as NS and glue AAAA/A records) in the + resolution process. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>min-roots</strong></span></span></dt> +<dd> + <p> + The minimum number of root servers that + is required for a request for the root servers to be + accepted. The default + is <strong class="userinput"><code>2</code></strong>. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + Not implemented in <acronym class="acronym">BIND</acronym> 9. + </p> + </div> + </dd> +<dt><span class="term"><span class="command"><strong>sig-validity-interval</strong></span></span></dt> +<dd> + <p> + Specifies the number of days into the future when + DNSSEC signatures automatically generated as a + result of dynamic updates (<a class="xref" href="Bv9ARM.ch04.html#dynamic_update" title="Dynamic Update">the section called “Dynamic Update”</a>) will expire. There + is an optional second field which specifies how + long before expiry that the signatures will be + regenerated. If not specified, the signatures will + be regenerated at 1/4 of base interval. The second + field is specified in days if the base interval is + greater than 7 days otherwise it is specified in hours. + The default base interval is <code class="literal">30</code> days + giving a re-signing interval of 7 1/2 days. The maximum + values are 10 years (3660 days). + </p> + <p> + The signature inception time is unconditionally + set to one hour before the current time to allow + for a limited amount of clock skew. + </p> + <p> + The <span class="command"><strong>sig-validity-interval</strong></span> + should be, at least, several multiples of the SOA + expire interval to allow for reasonable interaction + between the various timer and expiry dates. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>sig-signing-nodes</strong></span></span></dt> +<dd> + <p> + Specify the maximum number of nodes to be + examined in each quantum when signing a zone with + a new DNSKEY. The default is + <code class="literal">100</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>sig-signing-signatures</strong></span></span></dt> +<dd> + <p> + Specify a threshold number of signatures that + will terminate processing a quantum when signing + a zone with a new DNSKEY. The default is + <code class="literal">10</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>sig-signing-type</strong></span></span></dt> +<dd> + <p> + Specify a private RDATA type to be used when generating + signing state records. The default is + <code class="literal">65534</code>. + </p> + <p> + It is expected that this parameter may be removed + in a future version once there is a standard type. + </p> + <p> + Signing state records are used to internally by + <span class="command"><strong>named</strong></span> to track the current state of + a zone-signing process, i.e., whether it is still active + or has been completed. The records can be inspected + using the command + <span class="command"><strong>rndc signing -list <em class="replaceable"><code>zone</code></em></strong></span>. + Once <span class="command"><strong>named</strong></span> has finished signing + a zone with a particular key, the signing state + record associated with that key can be removed from + the zone by running + <span class="command"><strong>rndc signing -clear <em class="replaceable"><code>keyid/algorithm</code></em> <em class="replaceable"><code>zone</code></em></strong></span>. + To clear all of the completed signing state + records for a zone, use + <span class="command"><strong>rndc signing -clear all <em class="replaceable"><code>zone</code></em></strong></span>. + </p> + </dd> +<dt> +<span class="term"><span class="command"><strong>min-refresh-time</strong></span>, </span><span class="term"><span class="command"><strong>max-refresh-time</strong></span>, </span><span class="term"><span class="command"><strong>min-retry-time</strong></span>, </span><span class="term"><span class="command"><strong>max-retry-time</strong></span></span> +</dt> +<dd> + <p> + These options control the server's behavior on refreshing a + zone (querying for SOA changes) or retrying failed + transfers. Usually the SOA values for the zone are used, + up to a hard-coded maximum expiry of 24 weeks. However, + these values are set by the master, giving slave server + administrators little control over their contents. + </p> + <p> + These options allow the administrator to set a minimum and + maximum refresh and retry time in seconds per-zone, + per-view, or globally. These options are valid for + slave and stub zones, and clamp the SOA refresh and + retry times to the specified values. + </p> + <p> + The following defaults apply. + <span class="command"><strong>min-refresh-time</strong></span> 300 seconds, + <span class="command"><strong>max-refresh-time</strong></span> 2419200 seconds + (4 weeks), <span class="command"><strong>min-retry-time</strong></span> 500 seconds, + and <span class="command"><strong>max-retry-time</strong></span> 1209600 seconds + (2 weeks). + </p> + </dd> +<dt><span class="term"><span class="command"><strong>edns-udp-size</strong></span></span></dt> +<dd> + <p> + Sets the maximum advertised EDNS UDP buffer size in + bytes, to control the size of packets received from + authoritative servers in response to recursive queries. + Valid values are 512 to 4096 (values outside this range + will be silently adjusted to the nearest value within + it). The default value is 4096. + </p> + <p> + The usual reason for setting + <span class="command"><strong>edns-udp-size</strong></span> to a non-default value + is to get UDP answers to pass through broken firewalls + that block fragmented packets and/or block UDP DNS + packets that are greater than 512 bytes. + </p> + <p> + When <span class="command"><strong>named</strong></span> first queries a remote + server, it will advertise a UDP buffer size of 512, as + this has the greatest chance of success on the first try. + </p> + <p> + If the initial response times out, <span class="command"><strong>named</strong></span> + will try again with plain DNS, and if that is successful, + it will be taken as evidence that the server does not + support EDNS. After enough failures using EDNS and + successes using plain DNS, <span class="command"><strong>named</strong></span> + will default to plain DNS for future communications + with that server. (Periodically, <span class="command"><strong>named</strong></span> + will send an EDNS query to see if the situation has + improved.) + </p> + <p> + However, if the initial query is successful with + EDNS advertising a buffer size of 512, then + <span class="command"><strong>named</strong></span> will advertise progressively + larger buffer sizes on successive queries, until + responses begin timing out or + <span class="command"><strong>edns-udp-size</strong></span> is reached. + </p> + <p> + The default buffer sizes used by <span class="command"><strong>named</strong></span> + are 512, 1232, 1432, and 4096, but never exceeding + <span class="command"><strong>edns-udp-size</strong></span>. (The values 1232 and + 1432 are chosen to allow for an IPv4/IPv6 encapsulated + UDP message to be sent without fragmentation at the + minimum MTU sizes for Ethernet and IPv6 networks.) + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-udp-size</strong></span></span></dt> +<dd> + <p> + Sets the maximum EDNS UDP message size + <span class="command"><strong>named</strong></span> will send in bytes. + Valid values are 512 to 4096 (values outside this + range will be silently adjusted to the nearest + value within it). The default value is 4096. + </p> + <p> + This value applies to responses sent by a server; to + set the advertised buffer size in queries, see + <span class="command"><strong>edns-udp-size</strong></span>. + </p> + <p> + The usual reason for setting + <span class="command"><strong>max-udp-size</strong></span> to a non-default + value is to get UDP answers to pass through broken + firewalls that block fragmented packets and/or + block UDP packets that are greater than 512 bytes. + This is independent of the advertised receive + buffer (<span class="command"><strong>edns-udp-size</strong></span>). + </p> + <p> + Setting this to a low value will encourage additional + TCP traffic to the nameserver. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>masterfile-format</strong></span></span></dt> +<dd> + <p>Specifies + the file format of zone files (see + <a class="xref" href="Bv9ARM.ch06.html#zonefile_format" title="Additional File Formats">the section called “Additional File Formats”</a>). + The default value is <code class="constant">text</code>, which is the + standard textual representation, except for slave zones, + in which the default value is <code class="constant">raw</code>. + Files in other formats than <code class="constant">text</code> are + typically expected to be generated by the + <span class="command"><strong>named-compilezone</strong></span> tool, or dumped by + <span class="command"><strong>named</strong></span>. + </p> + <p> + Note that when a zone file in a different format than + <code class="constant">text</code> is loaded, <span class="command"><strong>named</strong></span> + may omit some of the checks which would be performed for a + file in the <code class="constant">text</code> format. In particular, + <span class="command"><strong>check-names</strong></span> checks do not apply + for the <code class="constant">raw</code> format. This means + a zone file in the <code class="constant">raw</code> format + must be generated with the same check level as that + specified in the <span class="command"><strong>named</strong></span> configuration + file. Also, <code class="constant">map</code> format files are + loaded directly into memory via memory mapping, with only + minimal checking. + </p> + <p> + This statement sets the + <span class="command"><strong>masterfile-format</strong></span> for all zones, + but can be overridden on a per-zone or per-view basis + by including a <span class="command"><strong>masterfile-format</strong></span> + statement within the <span class="command"><strong>zone</strong></span> or + <span class="command"><strong>view</strong></span> block in the configuration + file. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>masterfile-style</strong></span></span></dt> +<dd> + <p> + Specifies the formatting of zone files during dump + when the <code class="option">masterfile-format</code> is + <code class="constant">text</code>. (This option is ignored + with any other <code class="option">masterfile-format</code>.) + </p> + <p> + When set to <code class="constant">relative</code>, + records are printed in a multi-line format with owner + names expressed relative to a shared origin. When set + to <code class="constant">full</code>, records are printed in + a single-line format with absolute owner names. + The <code class="constant">full</code> format is most suitable + when a zone file needs to be processed automatically + by a script. The <code class="constant">relative</code> format + is more human-readable, and is thus suitable when a + zone is to be edited by hand. The default is + <code class="constant">relative</code>. + </p> + </dd> +<dt> +<a name="max-recursion-depth"></a><span class="term"><span class="command"><strong>max-recursion-depth</strong></span></span> +</dt> +<dd> + <p> + Sets the maximum number of levels of recursion + that are permitted at any one time while servicing + a recursive query. Resolving a name may require + looking up a name server address, which in turn + requires resolving another name, etc; if the number + of indirections exceeds this value, the recursive + query is terminated and returns SERVFAIL. The + default is 7. + </p> + </dd> +<dt> +<a name="max-recursion-queries"></a><span class="term"><span class="command"><strong>max-recursion-queries</strong></span></span> +</dt> +<dd> + <p> + Sets the maximum number of iterative queries that + may be sent while servicing a recursive query. + If more queries are sent, the recursive query + is terminated and returns SERVFAIL. Queries to + look up top level domains such as "com" and "net" + and the DNS root zone are exempt from this limitation. + The default is 75. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>notify-delay</strong></span></span></dt> +<dd> + <p> + The delay, in seconds, between sending sets of notify + messages for a zone. The default is five (5) seconds. + </p> + <p> + The overall rate that NOTIFY messages are sent for all + zones is controlled by <span class="command"><strong>serial-query-rate</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-rsa-exponent-size</strong></span></span></dt> +<dd> + <p> + The maximum RSA exponent size, in bits, that will + be accepted when validating. Valid values are 35 + to 4096 bits. The default zero (0) is also accepted + and is equivalent to 4096. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>prefetch</strong></span></span></dt> +<dd> + <p> + When a query is received for cached data which + is to expire shortly, <span class="command"><strong>named</strong></span> can + refresh the data from the authoritative server + immediately, ensuring that the cache always has an + answer available. + </p> + <p> + The <code class="option">prefetch</code> specifies the + "trigger" TTL value at which prefetch of the current + query will take place: when a cache record with a + lower TTL value is encountered during query processing, + it will be refreshed. Valid trigger TTL values are 1 to + 10 seconds. Values larger than 10 seconds will be silently + reduced to 10. + Setting a trigger TTL to zero (0) causes + prefetch to be disabled. + The default trigger TTL is <code class="literal">2</code>. + </p> + <p> + An optional second argument specifies the "eligibility" + TTL: the smallest <span class="emphasis"><em>original</em></span> + TTL value that will be accepted for a record to be + eligible for prefetching. The eligibility TTL must + be at least six seconds longer than the trigger TTL; + if it isn't, <span class="command"><strong>named</strong></span> will silently + adjust it upward. + The default eligibility TTL is <code class="literal">9</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>v6-bias</strong></span></span></dt> +<dd> + <p> + When determining the next nameserver to try + preference IPv6 nameservers by this many milliseconds. + The default is <code class="literal">50</code> milliseconds. + </p> + </dd> +</dl></div> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="builtin"></a>Built-in server information zones</h4></div></div></div> + + <p> + The server provides some helpful diagnostic information + through a number of built-in zones under the + pseudo-top-level-domain <code class="literal">bind</code> in the + <span class="command"><strong>CHAOS</strong></span> class. These zones are part + of a + built-in view (see <a class="xref" href="Bv9ARM.ch06.html#view_statement_grammar" title="view Statement Grammar">the section called “<span class="command"><strong>view</strong></span> Statement Grammar”</a>) of + class + <span class="command"><strong>CHAOS</strong></span> which is separate from the + default view of class <span class="command"><strong>IN</strong></span>. Most global + configuration options (<span class="command"><strong>allow-query</strong></span>, + etc) will apply to this view, but some are locally + overridden: <span class="command"><strong>notify</strong></span>, + <span class="command"><strong>recursion</strong></span> and + <span class="command"><strong>allow-new-zones</strong></span> are + always set to <strong class="userinput"><code>no</code></strong>, and + <span class="command"><strong>rate-limit</strong></span> is set to allow + three responses per second. + </p> + <p> + If you need to disable these zones, use the options + below, or hide the built-in <span class="command"><strong>CHAOS</strong></span> + view by + defining an explicit view of class <span class="command"><strong>CHAOS</strong></span> + that matches all clients. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>version</strong></span></span></dt> +<dd> + <p> + The version the server should report + via a query of the name <code class="literal">version.bind</code> + with type <span class="command"><strong>TXT</strong></span>, class <span class="command"><strong>CHAOS</strong></span>. + The default is the real version number of this server. + Specifying <span class="command"><strong>version none</strong></span> + disables processing of the queries. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>hostname</strong></span></span></dt> +<dd> + <p> + The hostname the server should report via a query of + the name <code class="filename">hostname.bind</code> + with type <span class="command"><strong>TXT</strong></span>, class <span class="command"><strong>CHAOS</strong></span>. + This defaults to the hostname of the machine hosting the + name server as + found by the gethostname() function. The primary purpose of such queries + is to + identify which of a group of anycast servers is actually + answering your queries. Specifying <span class="command"><strong>hostname none;</strong></span> + disables processing of the queries. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>server-id</strong></span></span></dt> +<dd> + <p> + The ID the server should report when receiving a Name + Server Identifier (NSID) query, or a query of the name + <code class="filename">ID.SERVER</code> with type + <span class="command"><strong>TXT</strong></span>, class <span class="command"><strong>CHAOS</strong></span>. + The primary purpose of such queries is to + identify which of a group of anycast servers is actually + answering your queries. Specifying <span class="command"><strong>server-id none;</strong></span> + disables processing of the queries. + Specifying <span class="command"><strong>server-id hostname;</strong></span> will cause <span class="command"><strong>named</strong></span> to + use the hostname as found by the gethostname() function. + The default <span class="command"><strong>server-id</strong></span> is <span class="command"><strong>none</strong></span>. + </p> + </dd> +</dl></div> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="empty"></a>Built-in Empty Zones</h4></div></div></div> + + <p> + The <span class="command"><strong>named</strong></span> server has some built-in + empty zones (SOA and NS records only). + These are for zones that should normally be answered locally + and which queries should not be sent to the Internet's root + servers. The official servers which cover these namespaces + return NXDOMAIN responses to these queries. In particular, + these cover the reverse namespaces for addresses from + RFC 1918, RFC 4193, RFC 5737 and RFC 6598. They also include the + reverse namespace for IPv6 local address (locally assigned), + IPv6 link local addresses, the IPv6 loopback address and the + IPv6 unknown address. + </p> + <p> + The server will attempt to determine if a built-in zone + already exists or is active (covered by a forward-only + forwarding declaration) and will not create an empty + zone in that case. + </p> + <p> + The current list of empty zones is: + </p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem">10.IN-ADDR.ARPA</li> +<li class="listitem">16.172.IN-ADDR.ARPA</li> +<li class="listitem">17.172.IN-ADDR.ARPA</li> +<li class="listitem">18.172.IN-ADDR.ARPA</li> +<li class="listitem">19.172.IN-ADDR.ARPA</li> +<li class="listitem">20.172.IN-ADDR.ARPA</li> +<li class="listitem">21.172.IN-ADDR.ARPA</li> +<li class="listitem">22.172.IN-ADDR.ARPA</li> +<li class="listitem">23.172.IN-ADDR.ARPA</li> +<li class="listitem">24.172.IN-ADDR.ARPA</li> +<li class="listitem">25.172.IN-ADDR.ARPA</li> +<li class="listitem">26.172.IN-ADDR.ARPA</li> +<li class="listitem">27.172.IN-ADDR.ARPA</li> +<li class="listitem">28.172.IN-ADDR.ARPA</li> +<li class="listitem">29.172.IN-ADDR.ARPA</li> +<li class="listitem">30.172.IN-ADDR.ARPA</li> +<li class="listitem">31.172.IN-ADDR.ARPA</li> +<li class="listitem">168.192.IN-ADDR.ARPA</li> +<li class="listitem">64.100.IN-ADDR.ARPA</li> +<li class="listitem">65.100.IN-ADDR.ARPA</li> +<li class="listitem">66.100.IN-ADDR.ARPA</li> +<li class="listitem">67.100.IN-ADDR.ARPA</li> +<li class="listitem">68.100.IN-ADDR.ARPA</li> +<li class="listitem">69.100.IN-ADDR.ARPA</li> +<li class="listitem">70.100.IN-ADDR.ARPA</li> +<li class="listitem">71.100.IN-ADDR.ARPA</li> +<li class="listitem">72.100.IN-ADDR.ARPA</li> +<li class="listitem">73.100.IN-ADDR.ARPA</li> +<li class="listitem">74.100.IN-ADDR.ARPA</li> +<li class="listitem">75.100.IN-ADDR.ARPA</li> +<li class="listitem">76.100.IN-ADDR.ARPA</li> +<li class="listitem">77.100.IN-ADDR.ARPA</li> +<li class="listitem">78.100.IN-ADDR.ARPA</li> +<li class="listitem">79.100.IN-ADDR.ARPA</li> +<li class="listitem">80.100.IN-ADDR.ARPA</li> +<li class="listitem">81.100.IN-ADDR.ARPA</li> +<li class="listitem">82.100.IN-ADDR.ARPA</li> +<li class="listitem">83.100.IN-ADDR.ARPA</li> +<li class="listitem">84.100.IN-ADDR.ARPA</li> +<li class="listitem">85.100.IN-ADDR.ARPA</li> +<li class="listitem">86.100.IN-ADDR.ARPA</li> +<li class="listitem">87.100.IN-ADDR.ARPA</li> +<li class="listitem">88.100.IN-ADDR.ARPA</li> +<li class="listitem">89.100.IN-ADDR.ARPA</li> +<li class="listitem">90.100.IN-ADDR.ARPA</li> +<li class="listitem">91.100.IN-ADDR.ARPA</li> +<li class="listitem">92.100.IN-ADDR.ARPA</li> +<li class="listitem">93.100.IN-ADDR.ARPA</li> +<li class="listitem">94.100.IN-ADDR.ARPA</li> +<li class="listitem">95.100.IN-ADDR.ARPA</li> +<li class="listitem">96.100.IN-ADDR.ARPA</li> +<li class="listitem">97.100.IN-ADDR.ARPA</li> +<li class="listitem">98.100.IN-ADDR.ARPA</li> +<li class="listitem">99.100.IN-ADDR.ARPA</li> +<li class="listitem">100.100.IN-ADDR.ARPA</li> +<li class="listitem">101.100.IN-ADDR.ARPA</li> +<li class="listitem">102.100.IN-ADDR.ARPA</li> +<li class="listitem">103.100.IN-ADDR.ARPA</li> +<li class="listitem">104.100.IN-ADDR.ARPA</li> +<li class="listitem">105.100.IN-ADDR.ARPA</li> +<li class="listitem">106.100.IN-ADDR.ARPA</li> +<li class="listitem">107.100.IN-ADDR.ARPA</li> +<li class="listitem">108.100.IN-ADDR.ARPA</li> +<li class="listitem">109.100.IN-ADDR.ARPA</li> +<li class="listitem">110.100.IN-ADDR.ARPA</li> +<li class="listitem">111.100.IN-ADDR.ARPA</li> +<li class="listitem">112.100.IN-ADDR.ARPA</li> +<li class="listitem">113.100.IN-ADDR.ARPA</li> +<li class="listitem">114.100.IN-ADDR.ARPA</li> +<li class="listitem">115.100.IN-ADDR.ARPA</li> +<li class="listitem">116.100.IN-ADDR.ARPA</li> +<li class="listitem">117.100.IN-ADDR.ARPA</li> +<li class="listitem">118.100.IN-ADDR.ARPA</li> +<li class="listitem">119.100.IN-ADDR.ARPA</li> +<li class="listitem">120.100.IN-ADDR.ARPA</li> +<li class="listitem">121.100.IN-ADDR.ARPA</li> +<li class="listitem">122.100.IN-ADDR.ARPA</li> +<li class="listitem">123.100.IN-ADDR.ARPA</li> +<li class="listitem">124.100.IN-ADDR.ARPA</li> +<li class="listitem">125.100.IN-ADDR.ARPA</li> +<li class="listitem">126.100.IN-ADDR.ARPA</li> +<li class="listitem">127.100.IN-ADDR.ARPA</li> +<li class="listitem">0.IN-ADDR.ARPA</li> +<li class="listitem">127.IN-ADDR.ARPA</li> +<li class="listitem">254.169.IN-ADDR.ARPA</li> +<li class="listitem">2.0.192.IN-ADDR.ARPA</li> +<li class="listitem">100.51.198.IN-ADDR.ARPA</li> +<li class="listitem">113.0.203.IN-ADDR.ARPA</li> +<li class="listitem">255.255.255.255.IN-ADDR.ARPA</li> +<li class="listitem">0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.ARPA</li> +<li class="listitem">1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.ARPA</li> +<li class="listitem">8.B.D.0.1.0.0.2.IP6.ARPA</li> +<li class="listitem">D.F.IP6.ARPA</li> +<li class="listitem">8.E.F.IP6.ARPA</li> +<li class="listitem">9.E.F.IP6.ARPA</li> +<li class="listitem">A.E.F.IP6.ARPA</li> +<li class="listitem">B.E.F.IP6.ARPA</li> +<li class="listitem">EMPTY.AS112.ARPA</li> +<li class="listitem">HOME.ARPA</li> +</ul></div> +<p> + </p> + <p> + Empty zones are settable at the view level and only apply to + views of class IN. Disabled empty zones are only inherited + from options if there are no disabled empty zones specified + at the view level. To override the options list of disabled + zones, you can disable the root zone at the view level, for example: +</p> +<pre class="programlisting"> + disable-empty-zone "."; +</pre> +<p> + </p> + <p> + If you are using the address ranges covered here, you should + already have reverse zones covering the addresses you use. + In practice this appears to not be the case with many queries + being made to the infrastructure servers for names in these + spaces. So many in fact that sacrificial servers were needed + to be deployed to channel the query load away from the + infrastructure servers. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> +<p> + The real parent servers for these zones should disable all + empty zone under the parent zone they serve. For the real + root servers, this is all built-in empty zones. This will + enable them to return referrals to deeper in the tree. + </p> +</div> + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>empty-server</strong></span></span></dt> +<dd> + <p> + Specify what server name will appear in the returned + SOA record for empty zones. If none is specified, then + the zone's name will be used. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>empty-contact</strong></span></span></dt> +<dd> + <p> + Specify what contact name will appear in the returned + SOA record for empty zones. If none is specified, then + "." will be used. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>empty-zones-enable</strong></span></span></dt> +<dd> + <p> + Enable or disable all empty zones. By default, they + are enabled. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>disable-empty-zone</strong></span></span></dt> +<dd> + <p> + Disable individual empty zones. By default, none are + disabled. This option can be specified multiple times. + </p> + </dd> +</dl></div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="acache"></a>Additional Section Caching</h4></div></div></div> + + + <p> + The additional section cache, also called <span class="command"><strong>acache</strong></span>, + is an internal cache to improve the response performance of BIND 9. + When additional section caching is enabled, BIND 9 will + cache an internal short-cut to the additional section content for + each answer RR. + Note that <span class="command"><strong>acache</strong></span> is an internal caching + mechanism of BIND 9, and is not related to the DNS caching + server function. + </p> + + <p> + Additional section caching does not change the + response content (except the RRsets ordering of the additional + section, see below), but can improve the response performance + significantly. + It is particularly effective when BIND 9 acts as an authoritative + server for a zone that has many delegations with many glue RRs. + </p> + + <p> + In order to obtain the maximum performance improvement + from additional section caching, setting + <span class="command"><strong>additional-from-cache</strong></span> + to <span class="command"><strong>no</strong></span> is recommended, since the current + implementation of <span class="command"><strong>acache</strong></span> + does not short-cut of additional section information from the + DNS cache data. + </p> + + <p> + One obvious disadvantage of <span class="command"><strong>acache</strong></span> is + that it requires much more + memory for the internal cached data. + Thus, if the response performance does not matter and memory + consumption is much more critical, the + <span class="command"><strong>acache</strong></span> mechanism can be + disabled by setting <span class="command"><strong>acache-enable</strong></span> to + <span class="command"><strong>no</strong></span>. + It is also possible to specify the upper limit of memory + consumption + for acache by using <span class="command"><strong>max-acache-size</strong></span>. + </p> + + <p> + Additional section caching also has a minor effect on the + RRset ordering in the additional section. + Without <span class="command"><strong>acache</strong></span>, + <span class="command"><strong>cyclic</strong></span> order is effective for the additional + section as well as the answer and authority sections. + However, additional section caching fixes the ordering when it + first caches an RRset for the additional section, and the same + ordering will be kept in succeeding responses, regardless of the + setting of <span class="command"><strong>rrset-order</strong></span>. + The effect of this should be minor, however, since an + RRset in the additional section + typically only contains a small number of RRs (and in many cases + it only contains a single RR), in which case the + ordering does not matter much. + </p> + + <p> + The following is a summary of options related to + <span class="command"><strong>acache</strong></span>. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>acache-enable</strong></span></span></dt> +<dd> + <p> + If <span class="command"><strong>yes</strong></span>, additional section caching is + enabled. The default value is <span class="command"><strong>no</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>acache-cleaning-interval</strong></span></span></dt> +<dd> + <p> + The server will remove stale cache entries, based on an LRU + based + algorithm, every <span class="command"><strong>acache-cleaning-interval</strong></span> minutes. + The default is 60 minutes. + If set to 0, no periodic cleaning will occur. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-acache-size</strong></span></span></dt> +<dd> + <p> + The maximum amount of memory in bytes to use for the server's acache. + When the amount of data in the acache reaches this limit, + the server + will clean more aggressively so that the limit is not + exceeded. + In a server with multiple views, the limit applies + separately to the + acache of each view. + The default is <code class="literal">16M</code>. + </p> + </dd> +</dl></div> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="content_filtering"></a>Content Filtering</h4></div></div></div> + + <p> + <acronym class="acronym">BIND</acronym> 9 provides the ability to filter + out DNS responses from external DNS servers containing + certain types of data in the answer section. + Specifically, it can reject address (A or AAAA) records if + the corresponding IPv4 or IPv6 addresses match the given + <code class="varname">address_match_list</code> of the + <span class="command"><strong>deny-answer-addresses</strong></span> option. + It can also reject CNAME or DNAME records if the "alias" + name (i.e., the CNAME alias or the substituted query name + due to DNAME) matches the + given <code class="varname">namelist</code> of the + <span class="command"><strong>deny-answer-aliases</strong></span> option, where + "match" means the alias name is a subdomain of one of + the <code class="varname">name_list</code> elements. + If the optional <code class="varname">namelist</code> is specified + with <span class="command"><strong>except-from</strong></span>, records whose query name + matches the list will be accepted regardless of the filter + setting. + Likewise, if the alias name is a subdomain of the + corresponding zone, the <span class="command"><strong>deny-answer-aliases</strong></span> + filter will not apply; + for example, even if "example.com" is specified for + <span class="command"><strong>deny-answer-aliases</strong></span>, + </p> +<pre class="programlisting">www.example.com. CNAME xxx.example.com.</pre> + + <p> + returned by an "example.com" server will be accepted. + </p> + + <p> + In the <code class="varname">address_match_list</code> of the + <span class="command"><strong>deny-answer-addresses</strong></span> option, only + <code class="varname">ip_addr</code> + and <code class="varname">ip_prefix</code> + are meaningful; + any <code class="varname">key_id</code> will be silently ignored. + </p> + + <p> + If a response message is rejected due to the filtering, + the entire message is discarded without being cached, and + a SERVFAIL error will be returned to the client. + </p> + + <p> + This filtering is intended to prevent "DNS rebinding attacks," in + which an attacker, in response to a query for a domain name the + attacker controls, returns an IP address within your own network or + an alias name within your own domain. + A naive web browser or script could then serve as an + unintended proxy, allowing the attacker + to get access to an internal node of your local network + that couldn't be externally accessed otherwise. + See the paper available at + <a class="link" href="http://portal.acm.org/citation.cfm?id=1315245.1315298" target="_top"> + http://portal.acm.org/citation.cfm?id=1315245.1315298 + </a> + for more details about the attacks. + </p> + + <p> + For example, if you own a domain named "example.net" and + your internal network uses an IPv4 prefix 192.0.2.0/24, + you might specify the following rules: + </p> + +<pre class="programlisting">deny-answer-addresses { 192.0.2.0/24; } except-from { "example.net"; }; +deny-answer-aliases { "example.net"; }; +</pre> + + <p> + If an external attacker lets a web browser in your local + network look up an IPv4 address of "attacker.example.com", + the attacker's DNS server would return a response like this: + </p> + +<pre class="programlisting">attacker.example.com. A 192.0.2.1</pre> + + <p> + in the answer section. + Since the rdata of this record (the IPv4 address) matches + the specified prefix 192.0.2.0/24, this response will be + ignored. + </p> + + <p> + On the other hand, if the browser looks up a legitimate + internal web server "www.example.net" and the + following response is returned to + the <acronym class="acronym">BIND</acronym> 9 server + </p> + +<pre class="programlisting">www.example.net. A 192.0.2.2</pre> + + <p> + it will be accepted since the owner name "www.example.net" + matches the <span class="command"><strong>except-from</strong></span> element, + "example.net". + </p> + + <p> + Note that this is not really an attack on the DNS per se. + In fact, there is nothing wrong for an "external" name to + be mapped to your "internal" IP address or domain name + from the DNS point of view. + It might actually be provided for a legitimate purpose, + such as for debugging. + As long as the mapping is provided by the correct owner, + it is not possible or does not make sense to detect + whether the intent of the mapping is legitimate or not + within the DNS. + The "rebinding" attack must primarily be protected at the + application that uses the DNS. + For a large site, however, it may be difficult to protect + all possible applications at once. + This filtering feature is provided only to help such an + operational environment; + it is generally discouraged to turn it on unless you are + very sure you have no other choice and the attack is a + real threat for your applications. + </p> + + <p> + Care should be particularly taken if you want to use this + option for addresses within 127.0.0.0/8. + These addresses are obviously "internal", but many + applications conventionally rely on a DNS mapping from + some name to such an address. + Filtering out DNS records containing this address + spuriously can break such applications. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="rpz"></a>Response Policy Zone (RPZ) Rewriting</h4></div></div></div> + + <p> + <acronym class="acronym">BIND</acronym> 9 includes a limited + mechanism to modify DNS responses for requests + analogous to email anti-spam DNS blacklists. + Responses can be changed to deny the existence of domains (NXDOMAIN), + deny the existence of IP addresses for domains (NODATA), + or contain other IP addresses or data. + </p> + + <p> + Response policy zones are named in the + <span class="command"><strong>response-policy</strong></span> option for the view or among the + global options if there is no response-policy option for the view. + Response policy zones are ordinary DNS zones containing RRsets + that can be queried normally if allowed. + It is usually best to restrict those queries with something like + <span class="command"><strong>allow-query { localhost; };</strong></span>. + Note that zones using <span class="command"><strong>masterfile-format map</strong></span> + cannot be used as policy zones. + </p> + + <p> + A <span class="command"><strong>response-policy</strong></span> option can support + multiple policy zones. To maximize performance, a radix + tree is used to quickly identify response policy zones + containing triggers that match the current query. This + imposes an upper limit of 32 on the number of policy zones + in a single <span class="command"><strong>response-policy</strong></span> option; more + than that is a configuration error. + </p> + + <p> + Five policy triggers can be encoded in RPZ records. + </p> +<div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>RPZ-CLIENT-IP</strong></span></span></dt> +<dd> + <p> + IP records are triggered by the IP address of the + DNS client. + Client IP address triggers are encoded in records that have + owner names that are subdomains of + <span class="command"><strong>rpz-client-ip</strong></span> relativized to the + policy zone origin name + and encode an address or address block. + IPv4 addresses are represented as + <strong class="userinput"><code>prefixlength.B4.B3.B2.B1.rpz-client-ip</code></strong>. + The IPv4 prefix length must be between 1 and 32. + All four bytes, B4, B3, B2, and B1, must be present. + B4 is the decimal value of the least significant byte of the + IPv4 address as in IN-ADDR.ARPA. + </p> + + <p> + IPv6 addresses are encoded in a format similar + to the standard IPv6 text representation, + <strong class="userinput"><code>prefixlength.W8.W7.W6.W5.W4.W3.W2.W1.rpz-client-ip</code></strong>. + Each of W8,...,W1 is a one to four digit hexadecimal number + representing 16 bits of the IPv6 address as in the standard + text representation of IPv6 addresses, but reversed as in + IP6.ARPA. (Note that this representation of IPv6 + address is different from IP6.ARPA where each hex + digit occupies a label.) + All 8 words must be present except when one set of consecutive + zero words is replaced with <strong class="userinput"><code>.zz.</code></strong> + analogous to double colons (::) in standard IPv6 text + encodings. + The IPv6 prefix length must be between 1 and 128. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>QNAME</strong></span></span></dt> +<dd> + <p> + QNAME policy records are triggered by query names of + requests and targets of CNAME records resolved to generate + the response. + The owner name of a QNAME policy record is + the query name relativized to the policy zone. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>RPZ-IP</strong></span></span></dt> +<dd> + <p> + IP triggers are IP addresses in an + A or AAAA record in the ANSWER section of a response. + They are encoded like client-IP triggers except as + subdomains of <span class="command"><strong>rpz-ip</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>RPZ-NSDNAME</strong></span></span></dt> +<dd> + <p> + NSDNAME triggers match names of authoritative servers + for the query name, a parent of the query name, a CNAME for + query name, or a parent of a CNAME. + They are encoded as subdomains of + <span class="command"><strong>rpz-nsdname</strong></span> relativized + to the RPZ origin name. + NSIP triggers match IP addresses in A and + AAAA RRsets for domains that can be checked against NSDNAME + policy records. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>RPZ-NSIP</strong></span></span></dt> +<dd> + <p> + NSIP triggers match the IP addresses of authoritative + servers. They are enncoded like IP triggers, except as + subdomains of <span class="command"><strong>rpz-nsip</strong></span>. + NSDNAME and NSIP triggers are checked only for names with at + least <span class="command"><strong>min-ns-dots</strong></span> dots. + The default value of <span class="command"><strong>min-ns-dots</strong></span> is + 1, to exclude top level domains. + </p> + <p> + If a name server's IP address is not yet known, + <span class="command"><strong>named</strong></span> will recursively look up + the IP address before applying an RPZ-NSIP rule. + This can cause a processing delay. To speed up + processing at the cost of precision, the + <span class="command"><strong>nsip-wait-recurse</strong></span> option + can be used: when set to <strong class="userinput"><code>no</code></strong>, + RPZ-NSIP rules will only be applied when a name + servers's IP address has already been looked up and + cached. If a server's IP address is not in the + cache, then the RPZ-NSIP rule will be ignored, + but the address will be looked up in the + background, and the rule will be applied + to subsequent queries. The default is + <strong class="userinput"><code>yes</code></strong>, meaning RPZ-NSIP + rules should always be applied even if an + address needs to be looked up first. + </p> + </dd> +</dl></div> +<p> + </p> + + <p> + The query response is checked against all response policy zones, + so two or more policy records can be triggered by a response. + Because DNS responses are rewritten according to at most one + policy record, a single record encoding an action (other than + <span class="command"><strong>DISABLED</strong></span> actions) must be chosen. + Triggers or the records that encode them are chosen for the + rewriting in the following order: + </p> +<div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem">Choose the triggered record in the zone that appears + first in the <span class="command"><strong>response-policy</strong></span> option. + </li> +<li class="listitem">Prefer CLIENT-IP to QNAME to IP to NSDNAME to NSIP + triggers in a single zone. + </li> +<li class="listitem">Among NSDNAME triggers, prefer the + trigger that matches the smallest name under the DNSSEC ordering. + </li> +<li class="listitem">Among IP or NSIP triggers, prefer the trigger + with the longest prefix. + </li> +<li class="listitem">Among triggers with the same prefix length, + prefer the IP or NSIP trigger that matches + the smallest IP address. + </li> +</ol></div> +<p> + </p> + + <p> + When the processing of a response is restarted to resolve + DNAME or CNAME records and a policy record set has + not been triggered, + all response policy zones are again consulted for the + DNAME or CNAME names and addresses. + </p> + + <p> + RPZ record sets are any types of DNS record except + DNAME or DNSSEC that encode actions or responses to + individual queries. + Any of the policies can be used with any of the triggers. + For example, while the <span class="command"><strong>TCP-only</strong></span> policy is + commonly used with <span class="command"><strong>client-IP</strong></span> triggers, + it can be used with any type of trigger to force the use of + TCP for responses with owner names in a zone. + </p> +<div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>PASSTHRU</strong></span></span></dt> +<dd> + <p> + The whitelist policy is specified + by a CNAME whose target is <span class="command"><strong>rpz-passthru</strong></span>. + It causes the response to not be rewritten + and is most often used to "poke holes" in policies for + CIDR blocks. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>DROP</strong></span></span></dt> +<dd> + <p> + The blacklist policy is specified + by a CNAME whose target is <span class="command"><strong>rpz-drop</strong></span>. + It causes the response to be discarded. + Nothing is sent to the DNS client. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>TCP-Only</strong></span></span></dt> +<dd> + <p> + The "slip" policy is specified + by a CNAME whose target is <span class="command"><strong>rpz-tcp-only</strong></span>. + It changes UDP responses to short, truncated DNS responses + that require the DNS client to try again with TCP. + It is used to mitigate distributed DNS reflection attacks. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>NXDOMAIN</strong></span></span></dt> +<dd> + <p> + The domain undefined response is encoded + by a CNAME whose target is the root domain (.) + </p> + </dd> +<dt><span class="term"><span class="command"><strong>NODATA</strong></span></span></dt> +<dd> + <p> + The empty set of resource records is specified by + CNAME whose target is the wildcard top-level + domain (*.). + It rewrites the response to NODATA or ANCOUNT=1. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>Local Data</strong></span></span></dt> +<dd> + <p> + A set of ordinary DNS records can be used to answer queries. + Queries for record types not the set are answered with + NODATA. + </p> + + <p> + A special form of local data is a CNAME whose target is a + wildcard such as *.example.com. + It is used as if were an ordinary CNAME after the asterisk (*) + has been replaced with the query name. + The purpose for this special form is query logging in the + walled garden's authority DNS server. + </p> + </dd> +</dl></div> +<p> + </p> + + <p> + All of the actions specified in all of the individual records + in a policy zone + can be overridden with a <span class="command"><strong>policy</strong></span> clause in the + <span class="command"><strong>response-policy</strong></span> option. + An organization using a policy zone provided by another + organization might use this mechanism to redirect domains + to its own walled garden. + </p> +<div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>GIVEN</strong></span></span></dt> +<dd> + <p>The placeholder policy says "do not override but + perform the action specified in the zone." + </p> + </dd> +<dt><span class="term"><span class="command"><strong>DISABLED</strong></span></span></dt> +<dd> + <p> + The testing override policy causes policy zone records to do + nothing but log what they would have done if the + policy zone were not disabled. + The response to the DNS query will be written (or not) + according to any triggered policy records that are not + disabled. + Disabled policy zones should appear first, + because they will often not be logged + if a higher precedence trigger is found first. + </p> + </dd> +<dt> +<span class="term"><span class="command"><strong>PASSTHRU</strong></span>, </span><span class="term"><span class="command"><strong>DROP</strong></span>, </span><span class="term"><span class="command"><strong>TCP-Only</strong></span>, </span><span class="term"><span class="command"><strong>NXDOMAIN</strong></span>, </span><span class="term"><span class="command"><strong>NODATA</strong></span></span> +</dt> +<dd> + <p> + override with the corresponding per-record policy. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>CNAME domain</strong></span></span></dt> +<dd> + <p> + causes all RPZ policy records to act as if they were + "cname domain" records. + </p> + </dd> +</dl></div> +<p> + </p> + + <p> + By default, the actions encoded in a response policy zone + are applied only to queries that ask for recursion (RD=1). + That default can be changed for a single policy zone or + all response policy zones in a view + with a <span class="command"><strong>recursive-only no</strong></span> clause. + This feature is useful for serving the same zone files + both inside and outside an RFC 1918 cloud and using RPZ to + delete answers that would otherwise contain RFC 1918 values + on the externally visible name server or view. + </p> + + <p> + Also by default, RPZ actions are applied only to DNS requests + that either do not request DNSSEC metadata (DO=0) or when no + DNSSEC records are available for request name in the original + zone (not the response policy zone). This default can be + changed for all response policy zones in a view with a + <span class="command"><strong>break-dnssec yes</strong></span> clause. In that case, RPZ + actions are applied regardless of DNSSEC. The name of the + clause option reflects the fact that results rewritten by RPZ + actions cannot verify. + </p> + + <p> + No DNS records are needed for a QNAME or Client-IP trigger. + The name or IP address itself is sufficient, + so in principle the query name need not be recursively resolved. + However, not resolving the requested + name can leak the fact that response policy rewriting is in use + and that the name is listed in a policy zone to operators of + servers for listed names. To prevent that information leak, by + default any recursion needed for a request is done before any + policy triggers are considered. Because listed domains often + have slow authoritative servers, this default behavior can cost + significant time. + The <span class="command"><strong>qname-wait-recurse no</strong></span> option + overrides that default behavior when recursion cannot + change a non-error response. + The option does not affect QNAME or client-IP triggers + in policy zones listed + after other zones containing IP, NSIP and NSDNAME triggers, because + those may depend on the A, AAAA, and NS records that would be + found during recursive resolution. It also does not affect + DNSSEC requests (DO=1) unless <span class="command"><strong>break-dnssec yes</strong></span> + is in use, because the response would depend on whether or not + RRSIG records were found during resolution. + Using this option can cause error responses such as SERVFAIL to + appear to be rewritten, since no recursion is being done to + discover problems at the authoritative server. + </p> + + <p> + The TTL of a record modified by RPZ policies is set from the + TTL of the relevant record in policy zone. It is then limited + to a maximum value. + The <span class="command"><strong>max-policy-ttl</strong></span> clause changes the + maximum seconds from its default of 5. + </p> + + <p> + For example, you might use this option statement + </p> +<pre class="programlisting"> response-policy { zone "badlist"; };</pre> + <p> + and this zone statement + </p> +<pre class="programlisting"> zone "badlist" {type master; file "master/badlist"; allow-query {none;}; };</pre> + <p> + with this zone file + </p> +<pre class="programlisting">$TTL 1H +@ SOA LOCALHOST. named-mgr.example.com (1 1h 15m 30d 2h) + NS LOCALHOST. + +; QNAME policy records. There are no periods (.) after the owner names. +nxdomain.domain.com CNAME . ; NXDOMAIN policy +*.nxdomain.domain.com CNAME . ; NXDOMAIN policy +nodata.domain.com CNAME *. ; NODATA policy +*.nodata.domain.com CNAME *. ; NODATA policy +bad.domain.com A 10.0.0.1 ; redirect to a walled garden + AAAA 2001:2::1 +bzone.domain.com CNAME garden.example.com. + +; do not rewrite (PASSTHRU) OK.DOMAIN.COM +ok.domain.com CNAME rpz-passthru. + +; redirect x.bzone.domain.com to x.bzone.domain.com.garden.example.com +*.bzone.domain.com CNAME *.garden.example.com. + + +; IP policy records that rewrite all responses containing A records in 127/8 +; except 127.0.0.1 +8.0.0.0.127.rpz-ip CNAME . +32.1.0.0.127.rpz-ip CNAME rpz-passthru. + +; NSDNAME and NSIP policy records +ns.domain.com.rpz-nsdname CNAME . +48.zz.2.2001.rpz-nsip CNAME . + +; blacklist and whitelist some DNS clients +112.zz.2001.rpz-client-ip CNAME rpz-drop. +8.0.0.0.127.rpz-client-ip CNAME rpz-drop. + +; force some DNS clients and responses in the example.com zone to TCP +16.0.0.1.10.rpz-client-ip CNAME rpz-tcp-only. +example.com CNAME rpz-tcp-only. +*.example.com CNAME rpz-tcp-only. + +</pre> + <p> + RPZ can affect server performance. + Each configured response policy zone requires the server to + perform one to four additional database lookups before a + query can be answered. + For example, a DNS server with four policy zones, each with all + four kinds of response triggers, QNAME, IP, NSIP, and + NSDNAME, requires a total of 17 times as many database + lookups as a similar DNS server with no response policy zones. + A <acronym class="acronym">BIND9</acronym> server with adequate memory and one + response policy zone with QNAME and IP triggers might achieve a + maximum queries-per-second rate about 20% lower. + A server with four response policy zones with QNAME and IP + triggers might have a maximum QPS rate about 50% lower. + </p> + + <p> + Responses rewritten by RPZ are counted in the + <span class="command"><strong>RPZRewrites</strong></span> statistics. + </p> + + <p> + The <span class="command"><strong>log</strong></span> clause can be used to optionally + turn off rewrite logging for a particular response policy + zone. By default, all rewrites are logged. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="rrl"></a>Response Rate Limiting</h4></div></div></div> + + <p> + Excessive almost identical UDP <span class="emphasis"><em>responses</em></span> + can be controlled by configuring a + <span class="command"><strong>rate-limit</strong></span> clause in an + <span class="command"><strong>options</strong></span> or <span class="command"><strong>view</strong></span> statement. + This mechanism keeps authoritative BIND 9 from being used + in amplifying reflection denial of service (DoS) attacks. + Short truncated (TC=1) responses can be sent to provide + rate-limited responses to legitimate clients within + a range of forged, attacked IP addresses. + Legitimate clients react to dropped or truncated response + by retrying with UDP or with TCP respectively. + </p> + + <p> + This mechanism is intended for authoritative DNS servers. + It can be used on recursive servers but can slow + applications such as SMTP servers (mail receivers) and + HTTP clients (web browsers) that repeatedly request the + same domains. + When possible, closing "open" recursive servers is better. + </p> + + <p> + Response rate limiting uses a "credit" or "token bucket" scheme. + Each combination of identical response and client + has a conceptual account that earns a specified number + of credits every second. + A prospective response debits its account by one. + Responses are dropped or truncated + while the account is negative. + Responses are tracked within a rolling window of time + which defaults to 15 seconds, but can be configured with + the <span class="command"><strong>window</strong></span> option to any value from + 1 to 3600 seconds (1 hour). + The account cannot become more positive than + the per-second limit + or more negative than <span class="command"><strong>window</strong></span> + times the per-second limit. + When the specified number of credits for a class of + responses is set to 0, those responses are not rate limited. + </p> + + <p> + The notions of "identical response" and "DNS client" + for rate limiting are not simplistic. + All responses to an address block are counted as if to a + single client. + The prefix lengths of addresses blocks are + specified with <span class="command"><strong>ipv4-prefix-length</strong></span> (default 24) + and <span class="command"><strong>ipv6-prefix-length</strong></span> (default 56). + </p> + + <p> + All non-empty responses for a valid domain name (qname) + and record type (qtype) are identical and have a limit specified + with <span class="command"><strong>responses-per-second</strong></span> + (default 0 or no limit). + All empty (NODATA) responses for a valid domain, + regardless of query type, are identical. + Responses in the NODATA class are limited by + <span class="command"><strong>nodata-per-second</strong></span> + (default <span class="command"><strong>responses-per-second</strong></span>). + Requests for any and all undefined subdomains of a given + valid domain result in NXDOMAIN errors, and are identical + regardless of query type. + They are limited by <span class="command"><strong>nxdomains-per-second</strong></span> + (default <span class="command"><strong>responses-per-second</strong></span>). + This controls some attacks using random names, but + can be relaxed or turned off (set to 0) + on servers that expect many legitimate + NXDOMAIN responses, such as from anti-spam blacklists. + Referrals or delegations to the server of a given + domain are identical and are limited by + <span class="command"><strong>referrals-per-second</strong></span> + (default <span class="command"><strong>responses-per-second</strong></span>). + </p> + + <p> + Responses generated from local wildcards are counted and limited + as if they were for the parent domain name. + This controls flooding using random.wild.example.com. + </p> + + <p> + All requests that result in DNS errors other + than NXDOMAIN, such as SERVFAIL and FORMERR, are identical + regardless of requested name (qname) or record type (qtype). + This controls attacks using invalid requests or distant, + broken authoritative servers. + By default the limit on errors is the same as the + <span class="command"><strong>responses-per-second</strong></span> value, + but it can be set separately with + <span class="command"><strong>errors-per-second</strong></span>. + </p> + + <p> + Many attacks using DNS involve UDP requests with forged source + addresses. + Rate limiting prevents the use of BIND 9 to flood a network + with responses to requests with forged source addresses, + but could let a third party block responses to legitimate requests. + There is a mechanism that can answer some legitimate + requests from a client whose address is being forged in a flood. + Setting <span class="command"><strong>slip</strong></span> to 2 (its default) causes every + other UDP request to be answered with a small truncated (TC=1) + response. + The small size and reduced frequency, and so lack of + amplification, of "slipped" responses make them unattractive + for reflection DoS attacks. + <span class="command"><strong>slip</strong></span> must be between 0 and 10. + A value of 0 does not "slip": + no truncated responses are sent due to rate limiting, + all responses are dropped. + A value of 1 causes every response to slip; + values between 2 and 10 cause every n'th response to slip. + Some error responses including REFUSED and SERVFAIL + cannot be replaced with truncated responses and are instead + leaked at the <span class="command"><strong>slip</strong></span> rate. + </p> + + <p> + (NOTE: Dropped responses from an authoritative server may + reduce the difficulty of a third party successfully forging + a response to a recursive resolver. The best security + against forged responses is for authoritative operators + to sign their zones using DNSSEC and for resolver operators + to validate the responses. When this is not an option, + operators who are more concerned with response integrity + than with flood mitigation may consider setting + <span class="command"><strong>slip</strong></span> to 1, causing all rate-limited + responses to be truncated rather than dropped. This reduces + the effectiveness of rate-limiting against reflection attacks.) + </p> + + <p> + When the approximate query per second rate exceeds + the <span class="command"><strong>qps-scale</strong></span> value, + then the <span class="command"><strong>responses-per-second</strong></span>, + <span class="command"><strong>errors-per-second</strong></span>, + <span class="command"><strong>nxdomains-per-second</strong></span> and + <span class="command"><strong>all-per-second</strong></span> values are reduced by the + ratio of the current rate to the <span class="command"><strong>qps-scale</strong></span> value. + This feature can tighten defenses during attacks. + For example, with + <span class="command"><strong>qps-scale 250; responses-per-second 20;</strong></span> and + a total query rate of 1000 queries/second for all queries from + all DNS clients including via TCP, + then the effective responses/second limit changes to + (250/1000)*20 or 5. + Responses sent via TCP are not limited + but are counted to compute the query per second rate. + </p> + + <p> + Rate limiters for different name spaces maintain + separate counters: If, for example, there is a + <span class="command"><strong>rate-limit</strong></span> statement for "com" and + another for "example.com", queries matching "example.com" + will not be debited against the rate limiter for "com". + </p> + + <p> + If a <span class="command"><strong>rate-limit</strong></span> statement does not specify a + <span class="command"><strong>domain</strong></span>, then it applies to the root domain + (".") and thus affects the entire DNS namespace, except those + portions covered by other <span class="command"><strong>rate-limit</strong></span> + statements. + </p> + + <p> + Communities of DNS clients can be given their own parameters or no + rate limiting by putting + <span class="command"><strong>rate-limit</strong></span> statements in <span class="command"><strong>view</strong></span> + statements instead of the global <span class="command"><strong>option</strong></span> + statement. + A <span class="command"><strong>rate-limit</strong></span> statement in a view replaces, + rather than supplementing, a <span class="command"><strong>rate-limit</strong></span> + statement among the main options. + DNS clients within a view can be exempted from rate limits + with the <span class="command"><strong>exempt-clients</strong></span> clause. + </p> + + <p> + UDP responses of all kinds can be limited with the + <span class="command"><strong>all-per-second</strong></span> phrase. This rate + limiting is unlike the rate limiting provided by + <span class="command"><strong>responses-per-second</strong></span>, + <span class="command"><strong>errors-per-second</strong></span>, and + <span class="command"><strong>nxdomains-per-second</strong></span> on a DNS server + which are often invisible to the victim of a DNS + reflection attack. Unless the forged requests of the + attack are the same as the legitimate requests of the + victim, the victim's requests are not affected. Responses + affected by an <span class="command"><strong>all-per-second</strong></span> limit + are always dropped; the <span class="command"><strong>slip</strong></span> value + has no effect. An <span class="command"><strong>all-per-second</strong></span> + limit should be at least 4 times as large as the other + limits, because single DNS clients often send bursts + of legitimate requests. For example, the receipt of a + single mail message can prompt requests from an SMTP + server for NS, PTR, A, and AAAA records as the incoming + SMTP/TCP/IP connection is considered. The SMTP server + can need additional NS, A, AAAA, MX, TXT, and SPF records + as it considers the STMP <span class="command"><strong>Mail From</strong></span> + command. Web browsers often repeatedly resolve the + same names that are repeated in HTML <IMG> tags + in a page. <span class="command"><strong>all-per-second</strong></span> is similar + to the rate limiting offered by firewalls but often + inferior. Attacks that justify ignoring the contents + of DNS responses are likely to be attacks on the DNS + server itself. They usually should be discarded before + the DNS server spends resources make TCP connections + or parsing DNS requests, but that rate limiting must + be done before the DNS server sees the requests. + </p> + + <p> + The maximum size of the table used to track requests and + rate limit responses is set with <span class="command"><strong>max-table-size</strong></span>. + Each entry in the table is between 40 and 80 bytes. + The table needs approximately as many entries as the number + of requests received per second. + The default is 20,000. + To reduce the cold start of growing the table, + <span class="command"><strong>min-table-size</strong></span> (default 500) + can set the minimum table size. + Enable <span class="command"><strong>rate-limit</strong></span> category logging to monitor + expansions of the table and inform + choices for the initial and maximum table size. + </p> + + <p> + Use <span class="command"><strong>log-only yes</strong></span> to test rate limiting parameters + without actually dropping any requests. + </p> + + <p> + Responses dropped by rate limits are included in the + <span class="command"><strong>RateDropped</strong></span> and <span class="command"><strong>QryDropped</strong></span> + statistics. + Responses that truncated by rate limits are included in + <span class="command"><strong>RateSlipped</strong></span> and <span class="command"><strong>RespTruncated</strong></span>. + </p> + </div> + + <div class="section"> +<div class="titlepage"></div> + <p> + Named supports NXDOMAIN redirection via two methods: + </p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem">Redirect zone <a class="xref" href="Bv9ARM.ch06.html#zone_statement_grammar" title="zone Statement Grammar">the section called “<span class="command"><strong>zone</strong></span> + Statement Grammar”</a> +</li> +<li class="listitem">Redirect namespace</li> +</ul></div> +<p> + </p> + <p> + With both methods when named gets a NXDOMAIN response + it examines a separate namespace to see if the NXDOMAIN + response should be replaced with an alternative response. + </p> + <p> + With a redirect zone (<span class="command"><strong>zone "." { type redirect; };</strong></span>), the + data used to replace the NXDOMAIN is held in a single + zone which is not part of the normal namespace. All the + redirect information is contained in the zone; there are + no delegations. + </p> + <p> + With a redirect namespace (<span class="command"><strong>option { nxdomain-redirect + <suffix> };</strong></span>) the data used to replace the + NXDOMAIN is part of the normal namespace and is looked up by + appending the specified suffix to the original query name. + This roughly doubles the cache required to process NXDOMAIN + responses as you have the original NXDOMAIN response and + the replacement data or a NXDOMAIN indicating that there + is no replacement. + </p> + <p> + If both a redirect zone and a redirect namespace are configured, + the redirect zone is tried first. + </p> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="server_statement_grammar"></a><span class="command"><strong>server</strong></span> Statement Grammar</h3></div></div></div> + <pre class="programlisting"> +<span class="command"><strong>server</strong></span> <em class="replaceable"><code>netprefix</code></em> { + <span class="command"><strong>bogus</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>edns</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>edns-udp-size</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>edns-version</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>keys</strong></span> <em class="replaceable"><code>server_key</code></em>; + <span class="command"><strong>max-udp-size</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>notify-source</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ + <span class="command"><strong>dscp</strong></span> <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>notify-source-v6</strong></span> ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] + [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>provide-ixfr</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>query-source</strong></span> ( ( [ address ] ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( + <em class="replaceable"><code>integer</code></em> | * ) ] ) | ( [ [ address ] ( <em class="replaceable"><code>ipv4_address</code></em> | * ) ] + <span class="command"><strong>port</strong></span> ( <em class="replaceable"><code>integer</code></em> | * ) ) ) [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>query-source-v6</strong></span> ( ( [ address ] ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( + <em class="replaceable"><code>integer</code></em> | * ) ] ) | ( [ [ address ] ( <em class="replaceable"><code>ipv6_address</code></em> | * ) ] + <span class="command"><strong>port</strong></span> ( <em class="replaceable"><code>integer</code></em> | * ) ) ) [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>request-expire</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>request-ixfr</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>request-nsid</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>send-cookie</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>tcp-only</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>transfer-format</strong></span> ( many-answers | one-answer ); + <span class="command"><strong>transfer-source</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ + <span class="command"><strong>dscp</strong></span> <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>transfer-source-v6</strong></span> ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) + ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>transfers</strong></span> <em class="replaceable"><code>integer</code></em>; +}; +</pre> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="server_statement_definition_and_usage"></a><span class="command"><strong>server</strong></span> Statement Definition and + Usage</h3></div></div></div> + + <p> + The <span class="command"><strong>server</strong></span> statement defines + characteristics + to be associated with a remote name server. If a prefix length is + specified, then a range of servers is covered. Only the most + specific + server clause applies regardless of the order in + <code class="filename">named.conf</code>. + </p> + + <p> + The <span class="command"><strong>server</strong></span> statement can occur at + the top level of the + configuration file or inside a <span class="command"><strong>view</strong></span> + statement. + If a <span class="command"><strong>view</strong></span> statement contains + one or more <span class="command"><strong>server</strong></span> statements, only + those + apply to the view and any top-level ones are ignored. + If a view contains no <span class="command"><strong>server</strong></span> + statements, + any top-level <span class="command"><strong>server</strong></span> statements are + used as + defaults. + </p> + + <p> + If you discover that a remote server is giving out bad data, + marking it as bogus will prevent further queries to it. The + default + value of <span class="command"><strong>bogus</strong></span> is <span class="command"><strong>no</strong></span>. + </p> + <p> + The <span class="command"><strong>provide-ixfr</strong></span> clause determines + whether + the local server, acting as master, will respond with an + incremental + zone transfer when the given remote server, a slave, requests it. + If set to <span class="command"><strong>yes</strong></span>, incremental transfer + will be provided + whenever possible. If set to <span class="command"><strong>no</strong></span>, + all transfers + to the remote server will be non-incremental. If not set, the + value + of the <span class="command"><strong>provide-ixfr</strong></span> option in the + view or + global options block is used as a default. + </p> + + <p> + The <span class="command"><strong>request-ixfr</strong></span> clause determines + whether + the local server, acting as a slave, will request incremental zone + transfers from the given remote server, a master. If not set, the + value of the <span class="command"><strong>request-ixfr</strong></span> option in + the view or global options block is used as a default. It may + also be set in the zone block and, if set there, it will + override the global or view setting for that zone. + </p> + + <p> + IXFR requests to servers that do not support IXFR will + automatically + fall back to AXFR. Therefore, there is no need to manually list + which servers support IXFR and which ones do not; the global + default + of <span class="command"><strong>yes</strong></span> should always work. + The purpose of the <span class="command"><strong>provide-ixfr</strong></span> and + <span class="command"><strong>request-ixfr</strong></span> clauses is + to make it possible to disable the use of IXFR even when both + master + and slave claim to support it, for example if one of the servers + is buggy and crashes or corrupts data when IXFR is used. + </p> + + <p> + The <span class="command"><strong>request-expire</strong></span> clause determines + whether the local server, when acting as a slave, will + request the EDNS EXPIRE value. The EDNS EXPIRE value + indicates the remaining time before the zone data will + expire and need to be be refreshed. This is used + when a secondary server transfers a zone from another + secondary server; when transferring from the primary, the + expiration timer is set from the EXPIRE field of the SOA + record instead. + The default is <span class="command"><strong>yes</strong></span>. + </p> + + <p> + The <span class="command"><strong>edns</strong></span> clause determines whether + the local server will attempt to use EDNS when communicating + with the remote server. The default is <span class="command"><strong>yes</strong></span>. + </p> + + <p> + The <span class="command"><strong>edns-udp-size</strong></span> option sets the + EDNS UDP size that is advertised by <span class="command"><strong>named</strong></span> + when querying the remote server. Valid values are 512 + to 4096 bytes (values outside this range will be silently + adjusted to the nearest value within it). This option + is useful when you wish to advertise a different value + to this server than the value you advertise globally, + for example, when there is a firewall at the remote + site that is blocking large replies. (Note: Currently, + this sets a single UDP size for all packets sent to the + server; <span class="command"><strong>named</strong></span> will not deviate from + this value. This differs from the behavior of + <span class="command"><strong>edns-udp-size</strong></span> in <span class="command"><strong>options</strong></span> + or <span class="command"><strong>view</strong></span> statements, where it specifies + a maximum value. The <span class="command"><strong>server</strong></span> statement + behavior may be brought into conformance with the + <span class="command"><strong>options/view</strong></span> behavior in future releases.) + </p> + + <p> + The <span class="command"><strong>edns-version</strong></span> option sets the + maximum EDNS VERSION that will be sent to the server(s) + by the resolver. The actual EDNS version sent is still + subject to normal EDNS version negotiation rules (see + RFC 6891), the maximum EDNS version supported by the + server, and any other heuristics that indicate that a + lower version should be sent. This option is intended + to be used when a remote server reacts badly to a given + EDNS version or higher; it should be set to the highest + version the remote server is known to support. Valid + values are 0 to 255; higher values will be silently + adjusted. This option will not be needed until higher + EDNS versions than 0 are in use. + </p> + + <p> + The <span class="command"><strong>max-udp-size</strong></span> option sets the + maximum EDNS UDP message size <span class="command"><strong>named</strong></span> + will send. Valid values are 512 to 4096 bytes (values + outside this range will be silently adjusted). This + option is useful when you know that there is a firewall + that is blocking large replies from <span class="command"><strong>named</strong></span>. + </p> + + <p> + The <span class="command"><strong>tcp-only</strong></span> option sets the transport + protocol to TCP. The default is to use the UDP transport + and to fallback on TCP only when a truncated response + is received. + </p> + + <p> + The server supports two zone transfer methods. The first, <span class="command"><strong>one-answer</strong></span>, + uses one DNS message per resource record transferred. <span class="command"><strong>many-answers</strong></span> packs + as many resource records as possible into a message. <span class="command"><strong>many-answers</strong></span> is + more efficient, but is only known to be understood by <acronym class="acronym">BIND</acronym> 9, <acronym class="acronym">BIND</acronym> + 8.x, and patched versions of <acronym class="acronym">BIND</acronym> + 4.9.5. You can specify which method + to use for a server with the <span class="command"><strong>transfer-format</strong></span> option. + If <span class="command"><strong>transfer-format</strong></span> is not + specified, the <span class="command"><strong>transfer-format</strong></span> + specified + by the <span class="command"><strong>options</strong></span> statement will be + used. + </p> + + <p><span class="command"><strong>transfers</strong></span> + is used to limit the number of concurrent inbound zone + transfers from the specified server. If no + <span class="command"><strong>transfers</strong></span> clause is specified, the + limit is set according to the + <span class="command"><strong>transfers-per-ns</strong></span> option. + </p> + + <p> + The <span class="command"><strong>keys</strong></span> clause identifies a + <span class="command"><strong>key_id</strong></span> defined by the <span class="command"><strong>key</strong></span> statement, + to be used for transaction security (TSIG, <a class="xref" href="Bv9ARM.ch04.html#tsig" title="TSIG">the section called “TSIG”</a>) + when talking to the remote server. + When a request is sent to the remote server, a request signature + will be generated using the key specified here and appended to the + message. A request originating from the remote server is not + required + to be signed by this key. + </p> + + <p> + Only a single key per server is currently supported. + </p> + + <p> + The <span class="command"><strong>transfer-source</strong></span> and + <span class="command"><strong>transfer-source-v6</strong></span> clauses specify + the IPv4 and IPv6 source + address to be used for zone transfer with the remote server, + respectively. + For an IPv4 remote server, only <span class="command"><strong>transfer-source</strong></span> can + be specified. + Similarly, for an IPv6 remote server, only + <span class="command"><strong>transfer-source-v6</strong></span> can be + specified. + For more details, see the description of + <span class="command"><strong>transfer-source</strong></span> and + <span class="command"><strong>transfer-source-v6</strong></span> in + <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. + </p> + + <p> + The <span class="command"><strong>notify-source</strong></span> and + <span class="command"><strong>notify-source-v6</strong></span> clauses specify the + IPv4 and IPv6 source address to be used for notify + messages sent to remote servers, respectively. For an + IPv4 remote server, only <span class="command"><strong>notify-source</strong></span> + can be specified. Similarly, for an IPv6 remote server, + only <span class="command"><strong>notify-source-v6</strong></span> can be specified. + </p> + + <p> + The <span class="command"><strong>query-source</strong></span> and + <span class="command"><strong>query-source-v6</strong></span> clauses specify the + IPv4 and IPv6 source address to be used for queries + sent to remote servers, respectively. For an IPv4 + remote server, only <span class="command"><strong>query-source</strong></span> can + be specified. Similarly, for an IPv6 remote server, + only <span class="command"><strong>query-source-v6</strong></span> can be specified. + </p> + + <p> + The <span class="command"><strong>request-nsid</strong></span> clause determines + whether the local server will add a NSID EDNS option + to requests sent to the server. This overrides + <span class="command"><strong>request-nsid</strong></span> set at the view or + option level. + </p> + + <p> + The <span class="command"><strong>send-cookie</strong></span> clause determines + whether the local server will add a COOKIE EDNS option + to requests sent to the server. This overrides + <span class="command"><strong>send-cookie</strong></span> set at the view or + option level. The <span class="command"><strong>named</strong></span> server may + determine that COOKIE is not supported by the remote server + and not add a COOKIE EDNS option to requests. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="statschannels"></a><span class="command"><strong>statistics-channels</strong></span> Statement Grammar</h3></div></div></div> + <pre class="programlisting"> +<span class="command"><strong>statistics-channels</strong></span> { + <span class="command"><strong>inet</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | <em class="replaceable"><code>ipv6_address</code></em> | + * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ + <span class="command"><strong>allow</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... + } ]; +}; +</pre> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="statistics_channels"></a><span class="command"><strong>statistics-channels</strong></span> Statement Definition and + Usage</h3></div></div></div> + + <p> + The <span class="command"><strong>statistics-channels</strong></span> statement + declares communication channels to be used by system + administrators to get access to statistics information of + the name server. + </p> + + <p> + This statement intends to be flexible to support multiple + communication protocols in the future, but currently only + HTTP access is supported. + It requires that BIND 9 be compiled with libxml2 and/or + json-c (also known as libjson0); the + <span class="command"><strong>statistics-channels</strong></span> statement is + still accepted even if it is built without the library, + but any HTTP access will fail with an error. + </p> + + <p> + An <span class="command"><strong>inet</strong></span> control channel is a TCP socket + listening at the specified <span class="command"><strong>ip_port</strong></span> on the + specified <span class="command"><strong>ip_addr</strong></span>, which can be an IPv4 or IPv6 + address. An <span class="command"><strong>ip_addr</strong></span> of <code class="literal">*</code> + (asterisk) is + interpreted as the IPv4 wildcard address; connections will be + accepted on any of the system's IPv4 addresses. + To listen on the IPv6 wildcard address, + use an <span class="command"><strong>ip_addr</strong></span> of <code class="literal">::</code>. + </p> + + <p> + If no port is specified, port 80 is used for HTTP channels. + The asterisk "<code class="literal">*</code>" cannot be used for + <span class="command"><strong>ip_port</strong></span>. + </p> + + <p> + The attempt of opening a statistics channel is + restricted by the optional <span class="command"><strong>allow</strong></span> clause. + Connections to the statistics channel are permitted based on the + <span class="command"><strong>address_match_list</strong></span>. + If no <span class="command"><strong>allow</strong></span> clause is present, + <span class="command"><strong>named</strong></span> accepts connection + attempts from any address; since the statistics may + contain sensitive internal information, it is highly + recommended to restrict the source of connection requests + appropriately. + </p> + + <p> + If no <span class="command"><strong>statistics-channels</strong></span> statement is present, + <span class="command"><strong>named</strong></span> will not open any communication channels. + </p> + + <p> + The statistics are available in various formats and views + depending on the URI used to access them. For example, if + the statistics channel is configured to listen on 127.0.0.1 + port 8888, then the statistics are accessible in XML format at + <a class="link" href="http://127.0.0.1:8888/" target="_top">http://127.0.0.1:8888/</a> or + <a class="link" href="http://127.0.0.1:8888/xml" target="_top">http://127.0.0.1:8888/xml</a>. A CSS file is + included which can format the XML statistics into tables + when viewed with a stylesheet-capable browser, and into + charts and graphs using the Google Charts API when using a + javascript-capable browser. + </p> + + <p> + Applications that depend on a particular XML schema + can request + <a class="link" href="http://127.0.0.1:8888/xml/v2" target="_top">http://127.0.0.1:8888/xml/v2</a> for version 2 + of the statistics XML schema or + <a class="link" href="http://127.0.0.1:8888/xml/v3" target="_top">http://127.0.0.1:8888/xml/v3</a> for version 3. + If the requested schema is supported by the server, then + it will respond; if not, it will return a "page not found" + error. + </p> + + <p> + Broken-out subsets of the statistics can be viewed at + <a class="link" href="http://127.0.0.1:8888/xml/v3/status" target="_top">http://127.0.0.1:8888/xml/v3/status</a> + (server uptime and last reconfiguration time), + <a class="link" href="http://127.0.0.1:8888/xml/v3/server" target="_top">http://127.0.0.1:8888/xml/v3/server</a> + (server and resolver statistics), + <a class="link" href="http://127.0.0.1:8888/xml/v3/zones" target="_top">http://127.0.0.1:8888/xml/v3/zones</a> + (zone statistics), + <a class="link" href="http://127.0.0.1:8888/xml/v3/net" target="_top">http://127.0.0.1:8888/xml/v3/net</a> + (network status and socket statistics), + <a class="link" href="http://127.0.0.1:8888/xml/v3/mem" target="_top">http://127.0.0.1:8888/xml/v3/mem</a> + (memory manager statistics), + <a class="link" href="http://127.0.0.1:8888/xml/v3/tasks" target="_top">http://127.0.0.1:8888/xml/v3/tasks</a> + (task manager statistics), and + <a class="link" href="http://127.0.0.1:8888/xml/v3/traffic" target="_top">http://127.0.0.1:8888/xml/v3/traffic</a> + (traffic sizes). + </p> + + <p> + The full set of statistics can also be read in JSON format at + <a class="link" href="http://127.0.0.1:8888/json" target="_top">http://127.0.0.1:8888/json</a>, + with the broken-out subsets at + <a class="link" href="http://127.0.0.1:8888/json/v1/status" target="_top">http://127.0.0.1:8888/json/v1/status</a> + (server uptime and last reconfiguration time), + <a class="link" href="http://127.0.0.1:8888/json/v1/server" target="_top">http://127.0.0.1:8888/json/v1/server</a> + (server and resolver statistics), + <a class="link" href="http://127.0.0.1:8888/json/v1/zones" target="_top">http://127.0.0.1:8888/json/v1/zones</a> + (zone statistics), + <a class="link" href="http://127.0.0.1:8888/json/v1/net" target="_top">http://127.0.0.1:8888/json/v1/net</a> + (network status and socket statistics), + <a class="link" href="http://127.0.0.1:8888/json/v1/mem" target="_top">http://127.0.0.1:8888/json/v1/mem</a> + (memory manager statistics), + <a class="link" href="http://127.0.0.1:8888/json/v1/tasks" target="_top">http://127.0.0.1:8888/json/v1/tasks</a> + (task manager statistics), and + <a class="link" href="http://127.0.0.1:8888/json/v1/traffic" target="_top">http://127.0.0.1:8888/json/v1/traffic</a> + (traffic sizes). + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="trusted-keys"></a><span class="command"><strong>trusted-keys</strong></span> Statement Grammar</h3></div></div></div> + <pre class="programlisting"> +<span class="command"><strong>trusted-keys</strong></span> { <em class="replaceable"><code>string</code></em> <em class="replaceable"><code>integer</code></em> <em class="replaceable"><code>integer</code></em> + <em class="replaceable"><code>integer</code></em> <em class="replaceable"><code>quoted_string</code></em>; ... }; +</pre> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="trusted_keys"></a><span class="command"><strong>trusted-keys</strong></span> Statement Definition + and Usage</h3></div></div></div> + + <p> + The <span class="command"><strong>trusted-keys</strong></span> statement defines + DNSSEC security roots. DNSSEC is described in <a class="xref" href="Bv9ARM.ch04.html#DNSSEC" title="DNSSEC">the section called “DNSSEC”</a>. A security root is defined when the + public key for a non-authoritative zone is known, but + cannot be securely obtained through DNS, either because + it is the DNS root zone or because its parent zone is + unsigned. Once a key has been configured as a trusted + key, it is treated as if it had been validated and + proven secure. The resolver attempts DNSSEC validation + on all DNS data in subdomains of a security root. + </p> + <p> + All keys (and corresponding zones) listed in + <span class="command"><strong>trusted-keys</strong></span> are deemed to exist regardless + of what parent zones say. Similarly for all keys listed in + <span class="command"><strong>trusted-keys</strong></span> only those keys are + used to validate the DNSKEY RRset. The parent's DS RRset + will not be used. + </p> + <p> + The <span class="command"><strong>trusted-keys</strong></span> statement can contain + multiple key entries, each consisting of the key's + domain name, flags, protocol, algorithm, and the Base64 + representation of the key data. + Spaces, tabs, newlines and carriage returns are ignored + in the key data, so the configuration may be split up into + multiple lines. + </p> + <p> + <span class="command"><strong>trusted-keys</strong></span> may be set at the top level + of <code class="filename">named.conf</code> or within a view. If it is + set in both places, they are additive: keys defined at the top + level are inherited by all views, but keys defined in a view + are only used within that view. + </p> + <p> + Validation below specified names can be temporarily disabled + by using <span class="command"><strong>rndc nta</strong></span>. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="managed_keys"></a><span class="command"><strong>managed-keys</strong></span> Statement Grammar</h3></div></div></div> + <pre class="programlisting"> +<span class="command"><strong>managed-keys</strong></span> { <em class="replaceable"><code>string</code></em> <em class="replaceable"><code>string</code></em> <em class="replaceable"><code>integer</code></em> + <em class="replaceable"><code>integer</code></em> <em class="replaceable"><code>integer</code></em> <em class="replaceable"><code>quoted_string</code></em>; ... }; +</pre> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="managed-keys"></a><span class="command"><strong>managed-keys</strong></span> Statement Definition + and Usage</h3></div></div></div> + + <p> + The <span class="command"><strong>managed-keys</strong></span> statement, like + <span class="command"><strong>trusted-keys</strong></span>, defines DNSSEC + security roots. The difference is that + <span class="command"><strong>managed-keys</strong></span> can be kept up to date + automatically, without intervention from the resolver + operator. + </p> + <p> + Suppose, for example, that a zone's key-signing + key was compromised, and the zone owner had to revoke and + replace the key. A resolver which had the old key in a + <span class="command"><strong>trusted-keys</strong></span> statement would be + unable to validate this zone any longer; it would + reply with a SERVFAIL response code. This would + continue until the resolver operator had updated the + <span class="command"><strong>trusted-keys</strong></span> statement with the new key. + </p> + <p> + If, however, the zone were listed in a + <span class="command"><strong>managed-keys</strong></span> statement instead, then the + zone owner could add a "stand-by" key to the zone in advance. + <span class="command"><strong>named</strong></span> would store the stand-by key, and + when the original key was revoked, <span class="command"><strong>named</strong></span> + would be able to transition smoothly to the new key. It would + also recognize that the old key had been revoked, and cease + using that key to validate answers, minimizing the damage that + the compromised key could do. + </p> + <p> + A <span class="command"><strong>managed-keys</strong></span> statement contains a list of + the keys to be managed, along with information about how the + keys are to be initialized for the first time. The only + initialization method currently supported is + <code class="literal">initial-key</code>. + This means the <span class="command"><strong>managed-keys</strong></span> statement must + contain a copy of the initializing key. (Future releases may + allow keys to be initialized by other methods, eliminating this + requirement.) + </p> + <p> + Consequently, a <span class="command"><strong>managed-keys</strong></span> statement + appears similar to a <span class="command"><strong>trusted-keys</strong></span>, differing + in the presence of the second field, containing the keyword + <code class="literal">initial-key</code>. The difference is, whereas the + keys listed in a <span class="command"><strong>trusted-keys</strong></span> continue to be + trusted until they are removed from + <code class="filename">named.conf</code>, an initializing key listed + in a <span class="command"><strong>managed-keys</strong></span> statement is only trusted + <span class="emphasis"><em>once</em></span>: for as long as it takes to load the + managed key database and start the RFC 5011 key maintenance + process. + </p> + <p> + The first time <span class="command"><strong>named</strong></span> runs with a managed key + configured in <code class="filename">named.conf</code>, it fetches the + DNSKEY RRset directly from the zone apex, and validates it + using the key specified in the <span class="command"><strong>managed-keys</strong></span> + statement. If the DNSKEY RRset is validly signed, then it is + used as the basis for a new managed keys database. + </p> + <p> + From that point on, whenever <span class="command"><strong>named</strong></span> runs, it + sees the <span class="command"><strong>managed-keys</strong></span> statement, checks to + make sure RFC 5011 key maintenance has already been initialized + for the specified domain, and if so, it simply moves on. The + key specified in the <span class="command"><strong>managed-keys</strong></span> + statement is not used to validate answers; it has been + superseded by the key or keys stored in the managed keys database. + </p> + <p> + The next time <span class="command"><strong>named</strong></span> runs after a name + has been <span class="emphasis"><em>removed</em></span> from the + <span class="command"><strong>managed-keys</strong></span> statement, the corresponding + zone will be removed from the managed keys database, + and RFC 5011 key maintenance will no longer be used for that + domain. + </p> + <p> + In the current implementation, the managed keys database + is stored as a master-format zone file. + </p> + <p> + On servers which do not use views, this file is named + <code class="filename">managed-keys.bind</code>. When views are in + use, there will be a separate managed keys database for each + view; the filename will be the view name (or, if a view name + contains characters which would make it illegal as a filename, + a hash of the view name), followed by + the suffix <code class="filename">.mkeys</code>. + </p> + <p> + When the key database is changed, the zone is updated. + As with any other dynamic zone, changes will be written + into a journal file, e.g., + <code class="filename">managed-keys.bind.jnl</code> or + <code class="filename">internal.mkeys.jnl</code>. + Changes are committed to the master file as soon as + possible afterward; this will usually occur within 30 + seconds. So, whenever <span class="command"><strong>named</strong></span> is using + automatic key maintenance, the zone file and journal file + can be expected to exist in the working directory. + (For this reason among others, the working directory + should be always be writable by <span class="command"><strong>named</strong></span>.) + </p> + <p> + If the <span class="command"><strong>dnssec-validation</strong></span> option is + set to <strong class="userinput"><code>auto</code></strong>, <span class="command"><strong>named</strong></span> + will automatically initialize a managed key for the + root zone. The key that is used to initialize the key + maintenance process is stored in <code class="filename">bind.keys</code>; + the location of this file can be overridden with the + <span class="command"><strong>bindkeys-file</strong></span> option. As a fallback + in the event no <code class="filename">bind.keys</code> can be + found, the initializing key is also compiled directly + into <span class="command"><strong>named</strong></span>. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="view_statement_grammar"></a><span class="command"><strong>view</strong></span> Statement Grammar</h3></div></div></div> + +<pre class="programlisting"><span class="command"><strong>view</strong></span> <em class="replaceable"><code>view_name</code></em> [ <em class="replaceable"><code>class</code></em> ] <span class="command"><strong>{</strong></span> + <span class="command"><strong>match-clients {</strong></span> <em class="replaceable"><code>address_match_list</code></em> <span class="command"><strong>}</strong></span> ; + <span class="command"><strong>match-destinations {</strong></span> <em class="replaceable"><code>address_match_list</code></em> <span class="command"><strong>}</strong></span> ; + <span class="command"><strong>match-recursive-only</strong></span> <em class="replaceable"><code>yes_or_no</code></em> ; + [ <em class="replaceable"><code>view_option</code></em> ; ... ] + [ <em class="replaceable"><code>zone_statement</code></em> ; ... ] +<span class="command"><strong>} </strong></span>; +</pre> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="view_statement"></a><span class="command"><strong>view</strong></span> Statement Definition and Usage</h3></div></div></div> + + <p> + The <span class="command"><strong>view</strong></span> statement is a powerful + feature + of <acronym class="acronym">BIND</acronym> 9 that lets a name server + answer a DNS query differently + depending on who is asking. It is particularly useful for + implementing + split DNS setups without having to run multiple servers. + </p> + + <p> + Each <span class="command"><strong>view</strong></span> statement defines a view + of the + DNS namespace that will be seen by a subset of clients. A client + matches + a view if its source IP address matches the + <code class="varname">address_match_list</code> of the view's + <span class="command"><strong>match-clients</strong></span> clause and its + destination IP address matches + the <code class="varname">address_match_list</code> of the + view's + <span class="command"><strong>match-destinations</strong></span> clause. If not + specified, both + <span class="command"><strong>match-clients</strong></span> and <span class="command"><strong>match-destinations</strong></span> + default to matching all addresses. In addition to checking IP + addresses + <span class="command"><strong>match-clients</strong></span> and <span class="command"><strong>match-destinations</strong></span> + can also take <span class="command"><strong>keys</strong></span> which provide an + mechanism for the + client to select the view. A view can also be specified + as <span class="command"><strong>match-recursive-only</strong></span>, which + means that only recursive + requests from matching clients will match that view. + The order of the <span class="command"><strong>view</strong></span> statements is + significant — + a client request will be resolved in the context of the first + <span class="command"><strong>view</strong></span> that it matches. + </p> + + <p> + Zones defined within a <span class="command"><strong>view</strong></span> + statement will + only be accessible to clients that match the <span class="command"><strong>view</strong></span>. + By defining a zone of the same name in multiple views, different + zone data can be given to different clients, for example, + "internal" + and "external" clients in a split DNS setup. + </p> + + <p> + Many of the options given in the <span class="command"><strong>options</strong></span> statement + can also be used within a <span class="command"><strong>view</strong></span> + statement, and then + apply only when resolving queries with that view. When no + view-specific + value is given, the value in the <span class="command"><strong>options</strong></span> statement + is used as a default. Also, zone options can have default values + specified + in the <span class="command"><strong>view</strong></span> statement; these + view-specific defaults + take precedence over those in the <span class="command"><strong>options</strong></span> statement. + </p> + + <p> + Views are class specific. If no class is given, class IN + is assumed. Note that all non-IN views must contain a hint zone, + since only the IN class has compiled-in default hints. + </p> + + <p> + If there are no <span class="command"><strong>view</strong></span> statements in + the config + file, a default view that matches any client is automatically + created + in class IN. Any <span class="command"><strong>zone</strong></span> statements + specified on + the top level of the configuration file are considered to be part + of + this default view, and the <span class="command"><strong>options</strong></span> + statement will + apply to the default view. If any explicit <span class="command"><strong>view</strong></span> + statements are present, all <span class="command"><strong>zone</strong></span> + statements must + occur inside <span class="command"><strong>view</strong></span> statements. + </p> + + <p> + Here is an example of a typical split DNS setup implemented + using <span class="command"><strong>view</strong></span> statements: + </p> + +<pre class="programlisting">view "internal" { + // This should match our internal networks. + match-clients { 10.0.0.0/8; }; + + // Provide recursive service to internal + // clients only. + recursion yes; + + // Provide a complete view of the example.com + // zone including addresses of internal hosts. + zone "example.com" { + type master; + file "example-internal.db"; + }; +}; + +view "external" { + // Match all clients not matched by the + // previous view. + match-clients { any; }; + + // Refuse recursive service to external clients. + recursion no; + + // Provide a restricted view of the example.com + // zone containing only publicly accessible hosts. + zone "example.com" { + type master; + file "example-external.db"; + }; +}; +</pre> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="zone_statement_grammar"></a><span class="command"><strong>zone</strong></span> + Statement Grammar</h3></div></div></div> + +<pre class="programlisting"> +<span class="command"><strong>zone</strong></span> <em class="replaceable"><code>string</code></em> [ <em class="replaceable"><code>class</code></em> ] { + <span class="command"><strong>type</strong></span> ( master | primary ); + <span class="command"><strong>allow-query</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-query-on</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-transfer</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-update</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>also-notify</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>masters</code></em> | <em class="replaceable"><code>ipv4_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] ) [ key <em class="replaceable"><code>string</code></em> ]; ... }; + <span class="command"><strong>alt-transfer-source</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>alt-transfer-source-v6</strong></span> ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>auto-dnssec</strong></span> ( allow | maintain | off ); + <span class="command"><strong>check-dup-records</strong></span> ( fail | warn | ignore ); + <span class="command"><strong>check-integrity</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>check-mx</strong></span> ( fail | warn | ignore ); + <span class="command"><strong>check-mx-cname</strong></span> ( fail | warn | ignore ); + <span class="command"><strong>check-names</strong></span> ( fail | warn | ignore ); + <span class="command"><strong>check-sibling</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>check-spf</strong></span> ( warn | ignore ); + <span class="command"><strong>check-srv-cname</strong></span> ( fail | warn | ignore ); + <span class="command"><strong>check-wildcard</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>database</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>dialup</strong></span> ( notify | notify-passive | passive | refresh | <em class="replaceable"><code>boolean</code></em> ); + <span class="command"><strong>dlz</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>dnssec-dnskey-kskonly</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>dnssec-loadkeys-interval</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>dnssec-secure-to-insecure</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>dnssec-update-mode</strong></span> ( maintain | no-resign ); + <span class="command"><strong>file</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>forward</strong></span> ( first | only ); + <span class="command"><strong>forwarders</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>ipv4_address</code></em> | <em class="replaceable"><code>ipv6_address</code></em> ) [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ]; ... }; + <span class="command"><strong>inline-signing</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>ixfr-from-differences</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>journal</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>key-directory</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>masterfile-format</strong></span> ( map | raw | text ); + <span class="command"><strong>masterfile-style</strong></span> ( full | relative ); + <span class="command"><strong>max-journal-size</strong></span> ( unlimited | <em class="replaceable"><code>sizeval</code></em> ); + <span class="command"><strong>max-records</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-transfer-idle-out</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-transfer-time-out</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-zone-ttl</strong></span> ( unlimited | <em class="replaceable"><code>ttlval</code></em> ); + <span class="command"><strong>notify</strong></span> ( explicit | master-only | <em class="replaceable"><code>boolean</code></em> ); + <span class="command"><strong>notify-delay</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>notify-source</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>notify-source-v6</strong></span> ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>notify-to-soa</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>serial-update-method</strong></span> ( date | increment | unixtime ); + <span class="command"><strong>sig-signing-nodes</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>sig-signing-signatures</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>sig-signing-type</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>sig-validity-interval</strong></span> <em class="replaceable"><code>integer</code></em> [ <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>update-check-ksk</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>update-policy</strong></span> ( local | { ( deny | grant ) <em class="replaceable"><code>string</code></em> ( 6to4-self | external | krb5-self | krb5-selfsub | krb5-subdomain | ms-self | ms-selfsub | ms-subdomain | name | self | selfsub | selfwild | subdomain | tcp-self | wildcard | zonesub ) [ <em class="replaceable"><code>string</code></em> ] <em class="replaceable"><code>rrtypelist</code></em>; ... }; + <span class="command"><strong>zero-no-soa-ttl</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>zone-statistics</strong></span> ( full | terse | none | <em class="replaceable"><code>boolean</code></em> ); +}; +</pre> +<pre class="programlisting"> +<span class="command"><strong>zone</strong></span> <em class="replaceable"><code>string</code></em> [ <em class="replaceable"><code>class</code></em> ] { + <span class="command"><strong>type</strong></span> ( slave | secondary ); + <span class="command"><strong>allow-notify</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-query</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-query-on</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-transfer</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-update-forwarding</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>also-notify</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>masters</code></em> | <em class="replaceable"><code>ipv4_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] ) [ key <em class="replaceable"><code>string</code></em> ]; ... }; + <span class="command"><strong>alt-transfer-source</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>alt-transfer-source-v6</strong></span> ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>auto-dnssec</strong></span> ( allow | maintain | off ); + <span class="command"><strong>check-names</strong></span> ( fail | warn | ignore ); + <span class="command"><strong>database</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>dialup</strong></span> ( notify | notify-passive | passive | refresh | <em class="replaceable"><code>boolean</code></em> ); + <span class="command"><strong>dlz</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>dnssec-dnskey-kskonly</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>dnssec-loadkeys-interval</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>dnssec-update-mode</strong></span> ( maintain | no-resign ); + <span class="command"><strong>file</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>forward</strong></span> ( first | only ); + <span class="command"><strong>forwarders</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>ipv4_address</code></em> | <em class="replaceable"><code>ipv6_address</code></em> ) [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ]; ... }; + <span class="command"><strong>inline-signing</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>ixfr-from-differences</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>journal</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>key-directory</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>masterfile-format</strong></span> ( map | raw | text ); + <span class="command"><strong>masterfile-style</strong></span> ( full | relative ); + <span class="command"><strong>masters</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>masters</code></em> | <em class="replaceable"><code>ipv4_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] ) [ key <em class="replaceable"><code>string</code></em> ]; ... }; + <span class="command"><strong>max-journal-size</strong></span> ( unlimited | <em class="replaceable"><code>sizeval</code></em> ); + <span class="command"><strong>max-records</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-refresh-time</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-retry-time</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-transfer-idle-in</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-transfer-idle-out</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-transfer-time-in</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-transfer-time-out</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>min-refresh-time</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>min-retry-time</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>multi-master</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>notify</strong></span> ( explicit | master-only | <em class="replaceable"><code>boolean</code></em> ); + <span class="command"><strong>notify-delay</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>notify-source</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>notify-source-v6</strong></span> ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>notify-to-soa</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>request-expire</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>request-ixfr</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>sig-signing-nodes</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>sig-signing-signatures</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>sig-signing-type</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>sig-validity-interval</strong></span> <em class="replaceable"><code>integer</code></em> [ <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>transfer-source</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>transfer-source-v6</strong></span> ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>try-tcp-refresh</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>update-check-ksk</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>use-alt-transfer-source</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>zero-no-soa-ttl</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>zone-statistics</strong></span> ( full | terse | none | <em class="replaceable"><code>boolean</code></em> ); +}; +</pre> +<pre class="programlisting"> +<span class="command"><strong>zone</strong></span> <em class="replaceable"><code>string</code></em> [ <em class="replaceable"><code>class</code></em> ] { + <span class="command"><strong>type</strong></span> hint; + <span class="command"><strong>check-names</strong></span> ( fail | warn | ignore ); + <span class="command"><strong>delegation-only</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>file</strong></span> <em class="replaceable"><code>quoted_string</code></em>; +}; +</pre> +<pre class="programlisting"> +<span class="command"><strong>zone</strong></span> <em class="replaceable"><code>string</code></em> [ <em class="replaceable"><code>class</code></em> ] { + <span class="command"><strong>type</strong></span> stub; + <span class="command"><strong>allow-query</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-query-on</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>check-names</strong></span> ( fail | warn | ignore ); + <span class="command"><strong>database</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>delegation-only</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>dialup</strong></span> ( notify | notify-passive | passive | refresh | <em class="replaceable"><code>boolean</code></em> ); + <span class="command"><strong>file</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>forward</strong></span> ( first | only ); + <span class="command"><strong>forwarders</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>ipv4_address</code></em> | <em class="replaceable"><code>ipv6_address</code></em> ) [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ]; ... }; + <span class="command"><strong>masterfile-format</strong></span> ( map | raw | text ); + <span class="command"><strong>masterfile-style</strong></span> ( full | relative ); + <span class="command"><strong>masters</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>masters</code></em> | <em class="replaceable"><code>ipv4_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] ) [ key <em class="replaceable"><code>string</code></em> ]; ... }; + <span class="command"><strong>max-records</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-refresh-time</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-retry-time</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-transfer-idle-in</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-transfer-time-in</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>min-refresh-time</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>min-retry-time</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>multi-master</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>transfer-source</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>transfer-source-v6</strong></span> ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>use-alt-transfer-source</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>zone-statistics</strong></span> ( full | terse | none | <em class="replaceable"><code>boolean</code></em> ); +}; +</pre> +<pre class="programlisting"> +<span class="command"><strong>zone</strong></span> <em class="replaceable"><code>string</code></em> [ <em class="replaceable"><code>class</code></em> ] { + <span class="command"><strong>type</strong></span> static-stub; + <span class="command"><strong>allow-query</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-query-on</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>forward</strong></span> ( first | only ); + <span class="command"><strong>forwarders</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>ipv4_address</code></em> | <em class="replaceable"><code>ipv6_address</code></em> ) [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ]; ... }; + <span class="command"><strong>max-records</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>server-addresses</strong></span> { ( <em class="replaceable"><code>ipv4_address</code></em> | <em class="replaceable"><code>ipv6_address</code></em> ) [ port <em class="replaceable"><code>integer</code></em> ]; ... }; + <span class="command"><strong>server-names</strong></span> { <em class="replaceable"><code>quoted_string</code></em>; ... }; + <span class="command"><strong>zone-statistics</strong></span> ( full | terse | none | <em class="replaceable"><code>boolean</code></em> ); +}; +</pre> +<pre class="programlisting"> +<span class="command"><strong>zone</strong></span> <em class="replaceable"><code>string</code></em> [ <em class="replaceable"><code>class</code></em> ] { + <span class="command"><strong>type</strong></span> forward; + <span class="command"><strong>delegation-only</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>forward</strong></span> ( first | only ); + <span class="command"><strong>forwarders</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>ipv4_address</code></em> | <em class="replaceable"><code>ipv6_address</code></em> ) [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ]; ... }; +}; +</pre> +<pre class="programlisting"> +<span class="command"><strong>zone</strong></span> <em class="replaceable"><code>string</code></em> [ <em class="replaceable"><code>class</code></em> ] { + <span class="command"><strong>type</strong></span> redirect; + <span class="command"><strong>allow-query</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-query-on</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>dlz</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>file</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>masterfile-format</strong></span> ( map | raw | text ); + <span class="command"><strong>masterfile-style</strong></span> ( full | relative ); + <span class="command"><strong>masters</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>masters</code></em> | <em class="replaceable"><code>ipv4_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] ) [ key <em class="replaceable"><code>string</code></em> ]; ... }; + <span class="command"><strong>max-records</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-zone-ttl</strong></span> ( unlimited | <em class="replaceable"><code>ttlval</code></em> ); + <span class="command"><strong>zone-statistics</strong></span> ( full | terse | none | <em class="replaceable"><code>boolean</code></em> ); +}; +</pre> +<pre class="programlisting"> +<span class="command"><strong>zone</strong></span> <em class="replaceable"><code>string</code></em> [ <em class="replaceable"><code>class</code></em> ] { + <span class="command"><strong>type</strong></span> delegation-only; +}; +</pre> +<pre class="programlisting"> +<span class="command"><strong>zone</strong></span> <em class="replaceable"><code>string</code></em> [ <em class="replaceable"><code>class</code></em> ] { + <span class="command"><strong>in-view</strong></span> <em class="replaceable"><code>string</code></em>; +}; +</pre> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="zone_statement"></a><span class="command"><strong>zone</strong></span> Statement Definition and Usage</h3></div></div></div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="zone_types"></a>Zone Types</h4></div></div></div> + <p> + The <span class="command"><strong>type</strong></span> keyword is required + for the <span class="command"><strong>zone</strong></span> configuration unless + it is an <span class="command"><strong>in-view</strong></span> configuration. Its + acceptable values include: <code class="varname">delegation-only</code>, + <code class="varname">forward</code>, <code class="varname">hint</code>, + <code class="varname">master</code>, <code class="varname">redirect</code>, + <code class="varname">slave</code>, <code class="varname">static-stub</code>, + and <code class="varname">stub</code>. + </p> + + <div class="informaltable"> + <table border="1"> +<colgroup> +<col class="1"> +<col width="4.017in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p> + <code class="varname">master</code> + </p> + </td> +<td> + <p> + The server has a master copy of the data + for the zone and will be able to provide authoritative + answers for + it. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">slave</code> + </p> + </td> +<td> + <p> + A slave zone is a replica of a master + zone. The <span class="command"><strong>masters</strong></span> list + specifies one or more IP addresses + of master servers that the slave contacts to update + its copy of the zone. + Masters list elements can also be names of other + masters lists. + By default, transfers are made from port 53 on the + servers; this can + be changed for all servers by specifying a port number + before the + list of IP addresses, or on a per-server basis after + the IP address. + Authentication to the master can also be done with + per-server TSIG keys. + If a file is specified, then the + replica will be written to this file whenever the zone + is changed, + and reloaded from this file on a server restart. Use + of a file is + recommended, since it often speeds server startup and + eliminates + a needless waste of bandwidth. Note that for large + numbers (in the + tens or hundreds of thousands) of zones per server, it + is best to + use a two-level naming scheme for zone filenames. For + example, + a slave server for the zone <code class="literal">example.com</code> might place + the zone contents into a file called + <code class="filename">ex/example.com</code> where <code class="filename">ex/</code> is + just the first two letters of the zone name. (Most + operating systems + behave very slowly if you put 100000 files into + a single directory.) + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">stub</code> + </p> + </td> +<td> + <p> + A stub zone is similar to a slave zone, + except that it replicates only the NS records of a + master zone instead + of the entire zone. Stub zones are not a standard part + of the DNS; + they are a feature specific to the <acronym class="acronym">BIND</acronym> implementation. + </p> + + <p> + Stub zones can be used to eliminate the need for glue + NS record + in a parent zone at the expense of maintaining a stub + zone entry and + a set of name server addresses in <code class="filename">named.conf</code>. + This usage is not recommended for new configurations, + and BIND 9 + supports it only in a limited way. + In <acronym class="acronym">BIND</acronym> 4/8, zone + transfers of a parent zone + included the NS records from stub children of that + zone. This meant + that, in some cases, users could get away with + configuring child stubs + only in the master server for the parent zone. <acronym class="acronym">BIND</acronym> + 9 never mixes together zone data from different zones + in this + way. Therefore, if a <acronym class="acronym">BIND</acronym> 9 master serving a parent + zone has child stub zones configured, all the slave + servers for the + parent zone also need to have the same child stub + zones + configured. + </p> + + <p> + Stub zones can also be used as a way of forcing the + resolution + of a given domain to use a particular set of + authoritative servers. + For example, the caching name servers on a private + network using + RFC1918 addressing may be configured with stub zones + for + <code class="literal">10.in-addr.arpa</code> + to use a set of internal name servers as the + authoritative + servers for that domain. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">static-stub</code> + </p> + </td> +<td> + <p> + A static-stub zone is similar to a stub zone + with the following exceptions: + the zone data is statically configured, rather + than transferred from a master server; + when recursion is necessary for a query that + matches a static-stub zone, the locally + configured data (nameserver names and glue addresses) + is always used even if different authoritative + information is cached. + </p> + <p> + Zone data is configured via the + <span class="command"><strong>server-addresses</strong></span> and + <span class="command"><strong>server-names</strong></span> zone options. + </p> + <p> + The zone data is maintained in the form of NS + and (if necessary) glue A or AAAA RRs + internally, which can be seen by dumping zone + databases by <span class="command"><strong>rndc dumpdb -all</strong></span>. + The configured RRs are considered local configuration + parameters rather than public data. + Non recursive queries (i.e., those with the RD + bit off) to a static-stub zone are therefore + prohibited and will be responded with REFUSED. + </p> + <p> + Since the data is statically configured, no + zone maintenance action takes place for a static-stub + zone. + For example, there is no periodic refresh + attempt, and an incoming notify message + will be rejected with an rcode of NOTAUTH. + </p> + <p> + Each static-stub zone is configured with + internally generated NS and (if necessary) + glue A or AAAA RRs + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">forward</code> + </p> + </td> +<td> + <p> + A "forward zone" is a way to configure + forwarding on a per-domain basis. A <span class="command"><strong>zone</strong></span> statement + of type <span class="command"><strong>forward</strong></span> can + contain a <span class="command"><strong>forward</strong></span> + and/or <span class="command"><strong>forwarders</strong></span> + statement, + which will apply to queries within the domain given by + the zone + name. If no <span class="command"><strong>forwarders</strong></span> + statement is present or + an empty list for <span class="command"><strong>forwarders</strong></span> is given, then no + forwarding will be done for the domain, canceling the + effects of + any forwarders in the <span class="command"><strong>options</strong></span> statement. Thus + if you want to use this type of zone to change the + behavior of the + global <span class="command"><strong>forward</strong></span> option + (that is, "forward first" + to, then "forward only", or vice versa, but want to + use the same + servers as set globally) you need to re-specify the + global forwarders. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">hint</code> + </p> + </td> +<td> + <p> + The initial set of root name servers is + specified using a "hint zone". When the server starts + up, it uses + the root hints to find a root name server and get the + most recent + list of root name servers. If no hint zone is + specified for class + IN, the server uses a compiled-in default set of root + servers hints. + Classes other than IN have no built-in defaults hints. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">redirect</code> + </p> + </td> +<td> + <p> + Redirect zones are used to provide answers to + queries when normal resolution would result in + NXDOMAIN being returned. + Only one redirect zone is supported + per view. <span class="command"><strong>allow-query</strong></span> can be + used to restrict which clients see these answers. + </p> + <p> + If the client has requested DNSSEC records (DO=1) and + the NXDOMAIN response is signed then no substitution + will occur. + </p> + <p> + To redirect all NXDOMAIN responses to + 100.100.100.2 and + 2001:ffff:ffff::100.100.100.2, one would + configure a type redirect zone named ".", + with the zone file containing wildcard records + that point to the desired addresses: + <code class="literal">"*. IN A 100.100.100.2"</code> + and + <code class="literal">"*. IN AAAA 2001:ffff:ffff::100.100.100.2"</code>. + </p> + <p> + To redirect all Spanish names (under .ES) one + would use similar entries but with the names + "*.ES." instead of "*.". To redirect all + commercial Spanish names (under COM.ES) one + would use wildcard entries called "*.COM.ES.". + </p> + <p> + Note that the redirect zone supports all + possible types; it is not limited to A and + AAAA records. + </p> + <p> + Because redirect zones are not referenced + directly by name, they are not kept in the + zone lookup table with normal master and slave + zones. Consequently, it is not currently possible + to use + <span class="command"><strong>rndc reload + <em class="replaceable"><code>zonename</code></em></strong></span> + to reload a redirect zone. However, when using + <span class="command"><strong>rndc reload</strong></span> without specifying + a zone name, redirect zones will be reloaded along + with other zones. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">delegation-only</code> + </p> + </td> +<td> + <p> + This is used to enforce the delegation-only + status of infrastructure zones (e.g. COM, + NET, ORG). Any answer that is received + without an explicit or implicit delegation + in the authority section will be treated + as NXDOMAIN. This does not apply to the + zone apex. This should not be applied to + leaf zones. + </p> + <p> + <code class="varname">delegation-only</code> has no + effect on answers received from forwarders. + </p> + <p> + See caveats in <a class="xref" href="Bv9ARM.ch06.html#root_delegation_only"><span class="command"><strong>root-delegation-only</strong></span></a>. + </p> + </td> +</tr> +</tbody> +</table> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="class"></a>Class</h4></div></div></div> + + <p> + The zone's name may optionally be followed by a class. If + a class is not specified, class <code class="literal">IN</code> (for <code class="varname">Internet</code>), + is assumed. This is correct for the vast majority of cases. + </p> + <p> + The <code class="literal">hesiod</code> class is + named for an information service from MIT's Project Athena. It + is + used to share information about various systems databases, such + as users, groups, printers and so on. The keyword + <code class="literal">HS</code> is + a synonym for hesiod. + </p> + <p> + Another MIT development is Chaosnet, a LAN protocol created + in the mid-1970s. Zone data for it can be specified with the <code class="literal">CHAOS</code> class. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="zone_options"></a>Zone Options</h4></div></div></div> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>allow-notify</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>allow-notify</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#access_control" title="Access Control">the section called “Access Control”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-query</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>allow-query</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#access_control" title="Access Control">the section called “Access Control”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-query-on</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>allow-query-on</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#access_control" title="Access Control">the section called “Access Control”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-transfer</strong></span></span></dt> +<dd> + <p> + See the description of <span class="command"><strong>allow-transfer</strong></span> + in <a class="xref" href="Bv9ARM.ch06.html#access_control" title="Access Control">the section called “Access Control”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-update</strong></span></span></dt> +<dd> + <p> + See the description of <span class="command"><strong>allow-update</strong></span> + in <a class="xref" href="Bv9ARM.ch06.html#access_control" title="Access Control">the section called “Access Control”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>update-policy</strong></span></span></dt> +<dd> + <p> + Specifies a "Simple Secure Update" policy. See + <a class="xref" href="Bv9ARM.ch06.html#dynamic_update_policies" title="Dynamic Update Policies">the section called “Dynamic Update Policies”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-update-forwarding</strong></span></span></dt> +<dd> + <p> + See the description of <span class="command"><strong>allow-update-forwarding</strong></span> + in <a class="xref" href="Bv9ARM.ch06.html#access_control" title="Access Control">the section called “Access Control”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>also-notify</strong></span></span></dt> +<dd> + <p> + Only meaningful if <span class="command"><strong>notify</strong></span> + is + active for this zone. The set of machines that will + receive a + <code class="literal">DNS NOTIFY</code> message + for this zone is made up of all the listed name servers + (other than + the primary master) for the zone plus any IP addresses + specified + with <span class="command"><strong>also-notify</strong></span>. A port + may be specified + with each <span class="command"><strong>also-notify</strong></span> + address to send the notify + messages to a port other than the default of 53. + A TSIG key may also be specified to cause the + <code class="literal">NOTIFY</code> to be signed by the + given key. + <span class="command"><strong>also-notify</strong></span> is not + meaningful for stub zones. + The default is the empty list. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-names</strong></span></span></dt> +<dd> + <p> + This option is used to restrict the character set and + syntax of + certain domain names in master files and/or DNS responses + received from the + network. The default varies according to zone type. For <span class="command"><strong>master</strong></span> zones the default is <span class="command"><strong>fail</strong></span>. For <span class="command"><strong>slave</strong></span> + zones the default is <span class="command"><strong>warn</strong></span>. + It is not implemented for <span class="command"><strong>hint</strong></span> zones. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-mx</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>check-mx</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-spf</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>check-spf</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-wildcard</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>check-wildcard</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-integrity</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>check-integrity</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-sibling</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>check-sibling</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>zero-no-soa-ttl</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>zero-no-soa-ttl</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>update-check-ksk</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>update-check-ksk</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-loadkeys-interval</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>dnssec-loadkeys-interval</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#options" title="options Statement Definition and Usage">the section called “<span class="command"><strong>options</strong></span> Statement Definition and + Usage”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-update-mode</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>dnssec-update-mode</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#options" title="options Statement Definition and Usage">the section called “<span class="command"><strong>options</strong></span> Statement Definition and + Usage”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-dnskey-kskonly</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>dnssec-dnskey-kskonly</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>try-tcp-refresh</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>try-tcp-refresh</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>database</strong></span></span></dt> +<dd> + <p> + Specify the type of database to be used for storing the + zone data. The string following the <span class="command"><strong>database</strong></span> keyword + is interpreted as a list of whitespace-delimited words. + The first word + identifies the database type, and any subsequent words are + passed + as arguments to the database to be interpreted in a way + specific + to the database type. + </p> + <p> + The default is <strong class="userinput"><code>"rbt"</code></strong>, BIND 9's + native in-memory + red-black-tree database. This database does not take + arguments. + </p> + <p> + Other values are possible if additional database drivers + have been linked into the server. Some sample drivers are + included + with the distribution but none are linked in by default. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dialup</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>dialup</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>delegation-only</strong></span></span></dt> +<dd> + <p> + The flag only applies to forward, hint and stub + zones. If set to <strong class="userinput"><code>yes</code></strong>, + then the zone will also be treated as if it is + also a delegation-only type zone. + </p> + <p> + See caveats in <a class="xref" href="Bv9ARM.ch06.html#root_delegation_only"><span class="command"><strong>root-delegation-only</strong></span></a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>file</strong></span></span></dt> +<dd> + <p> + Set the zone's filename. In <span class="command"><strong>master</strong></span>, + <span class="command"><strong>hint</strong></span>, and <span class="command"><strong>redirect</strong></span> + zones which do not have <span class="command"><strong>masters</strong></span> + defined, zone data is loaded from this file. In + <span class="command"><strong>slave</strong></span>, <span class="command"><strong>stub</strong></span>, and + <span class="command"><strong>redirect</strong></span> zones which do have + <span class="command"><strong>masters</strong></span> defined, zone data is + retrieved from another server and saved in this file. + This option is not applicable to other zone types. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>forward</strong></span></span></dt> +<dd> + <p> + Only meaningful if the zone has a forwarders + list. The <span class="command"><strong>only</strong></span> value causes + the lookup to fail + after trying the forwarders and getting no answer, while <span class="command"><strong>first</strong></span> would + allow a normal lookup to be tried. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>forwarders</strong></span></span></dt> +<dd> + <p> + Used to override the list of global forwarders. + If it is not specified in a zone of type <span class="command"><strong>forward</strong></span>, + no forwarding is done for the zone and the global options are + not used. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>ixfr-base</strong></span></span></dt> +<dd> + <p> + Was used in <acronym class="acronym">BIND</acronym> 8 to + specify the name + of the transaction log (journal) file for dynamic update + and IXFR. + <acronym class="acronym">BIND</acronym> 9 ignores the option + and constructs the name of the journal + file by appending "<code class="filename">.jnl</code>" + to the name of the + zone file. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>ixfr-tmp-file</strong></span></span></dt> +<dd> + <p> + Was an undocumented option in <acronym class="acronym">BIND</acronym> 8. + Ignored in <acronym class="acronym">BIND</acronym> 9. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>journal</strong></span></span></dt> +<dd> + <p> + Allow the default journal's filename to be overridden. + The default is the zone's filename with "<code class="filename">.jnl</code>" appended. + This is applicable to <span class="command"><strong>master</strong></span> and <span class="command"><strong>slave</strong></span> zones. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-journal-size</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>max-journal-size</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#server_resource_limits" title="Server Resource Limits">the section called “Server Resource Limits”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-records</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>max-records</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#server_resource_limits" title="Server Resource Limits">the section called “Server Resource Limits”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-transfer-time-in</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>max-transfer-time-in</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-transfer-idle-in</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>max-transfer-idle-in</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-transfer-time-out</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>max-transfer-time-out</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-transfer-idle-out</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>max-transfer-idle-out</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>notify</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>notify</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>notify-delay</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>notify-delay</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#tuning" title="Tuning">the section called “Tuning”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>notify-to-soa</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>notify-to-soa</strong></span> in + <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>pubkey</strong></span></span></dt> +<dd> + <p> + In <acronym class="acronym">BIND</acronym> 8, this option was + intended for specifying + a public zone key for verification of signatures in DNSSEC + signed + zones when they are loaded from disk. <acronym class="acronym">BIND</acronym> 9 does not verify signatures + on load and ignores the option. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>zone-statistics</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>zone-statistics</strong></span> in + <a class="xref" href="Bv9ARM.ch06.html#options" title="options Statement Definition and Usage">the section called “<span class="command"><strong>options</strong></span> Statement Definition and + Usage”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>server-addresses</strong></span></span></dt> +<dd> + <p> + Only meaningful for static-stub zones. + This is a list of IP addresses to which queries + should be sent in recursive resolution for the + zone. + A non empty list for this option will internally + configure the apex NS RR with associated glue A or + AAAA RRs. + </p> + <p> + For example, if "example.com" is configured as a + static-stub zone with 192.0.2.1 and 2001:db8::1234 + in a <span class="command"><strong>server-addresses</strong></span> option, + the following RRs will be internally configured. + </p> +<pre class="programlisting">example.com. NS example.com. +example.com. A 192.0.2.1 +example.com. AAAA 2001:db8::1234</pre> + <p> + These records are internally used to resolve + names under the static-stub zone. + For instance, if the server receives a query for + "www.example.com" with the RD bit on, the server + will initiate recursive resolution and send + queries to 192.0.2.1 and/or 2001:db8::1234. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>server-names</strong></span></span></dt> +<dd> + <p> + Only meaningful for static-stub zones. + This is a list of domain names of nameservers that + act as authoritative servers of the static-stub + zone. + These names will be resolved to IP addresses when + <span class="command"><strong>named</strong></span> needs to send queries to + these servers. + To make this supplemental resolution successful, + these names must not be a subdomain of the origin + name of static-stub zone. + That is, when "example.net" is the origin of a + static-stub zone, "ns.example" and + "master.example.com" can be specified in the + <span class="command"><strong>server-names</strong></span> option, but + "ns.example.net" cannot, and will be rejected by + the configuration parser. + </p> + <p> + A non empty list for this option will internally + configure the apex NS RR with the specified names. + For example, if "example.com" is configured as a + static-stub zone with "ns1.example.net" and + "ns2.example.net" + in a <span class="command"><strong>server-names</strong></span> option, + the following RRs will be internally configured. + </p> +<pre class="programlisting">example.com. NS ns1.example.net. +example.com. NS ns2.example.net. +</pre> + <p> + These records are internally used to resolve + names under the static-stub zone. + For instance, if the server receives a query for + "www.example.com" with the RD bit on, the server + initiate recursive resolution, + resolve "ns1.example.net" and/or + "ns2.example.net" to IP addresses, and then send + queries to (one or more of) these addresses. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>sig-validity-interval</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>sig-validity-interval</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#tuning" title="Tuning">the section called “Tuning”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>sig-signing-nodes</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>sig-signing-nodes</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#tuning" title="Tuning">the section called “Tuning”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>sig-signing-signatures</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>sig-signing-signatures</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#tuning" title="Tuning">the section called “Tuning”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>sig-signing-type</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>sig-signing-type</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#tuning" title="Tuning">the section called “Tuning”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>transfer-source</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>transfer-source</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>transfer-source-v6</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>transfer-source-v6</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>alt-transfer-source</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>alt-transfer-source</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>alt-transfer-source-v6</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>alt-transfer-source-v6</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>use-alt-transfer-source</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>use-alt-transfer-source</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>notify-source</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>notify-source</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>notify-source-v6</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>notify-source-v6</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. + </p> + </dd> +<dt> +<span class="term"><span class="command"><strong>min-refresh-time</strong></span>, </span><span class="term"><span class="command"><strong>max-refresh-time</strong></span>, </span><span class="term"><span class="command"><strong>min-retry-time</strong></span>, </span><span class="term"><span class="command"><strong>max-retry-time</strong></span></span> +</dt> +<dd> + <p> + See the description in <a class="xref" href="Bv9ARM.ch06.html#tuning" title="Tuning">the section called “Tuning”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>ixfr-from-differences</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>ixfr-from-differences</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + (Note that the <span class="command"><strong>ixfr-from-differences</strong></span> + <strong class="userinput"><code>master</code></strong> and + <strong class="userinput"><code>slave</code></strong> choices are not + available at the zone level.) + </p> + </dd> +<dt><span class="term"><span class="command"><strong>key-directory</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>key-directory</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#options" title="options Statement Definition and Usage">the section called “<span class="command"><strong>options</strong></span> Statement Definition and + Usage”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>auto-dnssec</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>auto-dnssec</strong></span> in + <a class="xref" href="Bv9ARM.ch06.html#options" title="options Statement Definition and Usage">the section called “<span class="command"><strong>options</strong></span> Statement Definition and + Usage”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>serial-update-method</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>serial-update-method</strong></span> in + <a class="xref" href="Bv9ARM.ch06.html#options" title="options Statement Definition and Usage">the section called “<span class="command"><strong>options</strong></span> Statement Definition and + Usage”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>inline-signing</strong></span></span></dt> +<dd> + <p> + If <code class="literal">yes</code>, this enables + "bump in the wire" signing of a zone, where a + unsigned zone is transferred in or loaded from + disk and a signed version of the zone is served, + with possibly, a different serial number. This + behavior is disabled by default. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>multi-master</strong></span></span></dt> +<dd> + <p> + See the description of <span class="command"><strong>multi-master</strong></span> in + <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>masterfile-format</strong></span></span></dt> +<dd> + <p> + See the description of <span class="command"><strong>masterfile-format</strong></span> + in <a class="xref" href="Bv9ARM.ch06.html#tuning" title="Tuning">the section called “Tuning”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-zone-ttl</strong></span></span></dt> +<dd> + <p> + See the description of <span class="command"><strong>max-zone-ttl</strong></span> + in <a class="xref" href="Bv9ARM.ch06.html#options" title="options Statement Definition and Usage">the section called “<span class="command"><strong>options</strong></span> Statement Definition and + Usage”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-secure-to-insecure</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>dnssec-secure-to-insecure</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +</dl></div> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="dynamic_update_policies"></a>Dynamic Update Policies</h4></div></div></div> + + <p><acronym class="acronym">BIND</acronym> 9 supports two alternative + methods of granting clients the right to perform + dynamic updates to a zone, configured by the + <span class="command"><strong>allow-update</strong></span> and + <span class="command"><strong>update-policy</strong></span> option, respectively. + </p> + <p> + The <span class="command"><strong>allow-update</strong></span> clause is a simple + access control list. Any client that matches + the ACL is granted permission to update any record + in the zone. + </p> + <p> + The <span class="command"><strong>update-policy</strong></span> clause + allows more fine-grained control over what updates are + allowed. It specifies a set of rules, in which each rule + either grants or denies permission for one or more + names in the zone to be updated by one or more + identities. Identity is determined by the key that + signed the update request using either TSIG or SIG(0). + In most cases, <span class="command"><strong>update-policy</strong></span> rules + only apply to key-based identities. There is no way + to specify update permissions based on client source + address. + </p> + <p> + <span class="command"><strong>update-policy</strong></span> rules are only meaningful + for zones of type <span class="command"><strong>master</strong></span>, and are + not allowed in any other zone type. + It is a configuration error to specify both + <span class="command"><strong>allow-update</strong></span> and + <span class="command"><strong>update-policy</strong></span> at the same time. + </p> + <p> + A pre-defined <span class="command"><strong>update-policy</strong></span> rule can be + switched on with the command + <span class="command"><strong>update-policy local;</strong></span>. + Using this in a zone causes + <span class="command"><strong>named</strong></span> to generate a TSIG session key + when starting up and store it in a file; this key can then + be used by local clients to update the zone while + <span class="command"><strong>named</strong></span> is running. + By default, the session key is stored in the file + <code class="filename">/var/run/named/session.key</code>, the key name + is "local-ddns", and the key algorithm is HMAC-SHA256. + These values are configurable with the + <span class="command"><strong>session-keyfile</strong></span>, + <span class="command"><strong>session-keyname</strong></span> and + <span class="command"><strong>session-keyalg</strong></span> options, respectively. + A client running on the local system, if run with appropriate + permissions, may read the session key from the key file and + use it to sign update requests. The zone's update + policy will be set to allow that key to change any record + within the zone. Assuming the key name is "local-ddns", + this policy is equivalent to: + </p> + + <pre class="programlisting">update-policy { grant local-ddns zonesub any; }; + </pre> + + <p> + ...with the additional restriction that only clients + connecting from the local system will be permitted to send + updates. + </p> + <p> + Note that only one session key is generated by + <span class="command"><strong>named</strong></span>; all zones configured to use + <span class="command"><strong>update-policy local</strong></span> will accept the same key. + </p> + <p> + The command <span class="command"><strong>nsupdate -l</strong></span> implements this + feature, sending requests to localhost and signing them using + the key retrieved from the session key file. + </p> + + <p> + Other rule definitions look like this: + </p> + +<pre class="programlisting"> +( <span class="command"><strong>grant</strong></span> | <span class="command"><strong>deny</strong></span> ) <em class="replaceable"><code>identity</code></em> <em class="replaceable"><code>ruletype</code></em> [<span class="optional"> <em class="replaceable"><code>name</code></em> </span>] [<span class="optional"> <em class="replaceable"><code>types</code></em> </span>] +</pre> + + <p> + Each rule grants or denies privileges. Rules are checked + in the order in which they are specified in the + <span class="command"><strong>update-policy</strong></span> statement. Once a message + has successfully matched a rule, the operation is immediately + granted or denied, and no further rules are examined. There + are 13 types of rules; the rule type is specified by the + <span class="command"><strong>ruletype</strong></span> field, and the interpretation + of other fields varies depending on the rule type. + </p> + <p> + In general, a rule is matched when the + key that signed an update request matches the + <span class="command"><strong>identity</strong></span> field, the name of the record + to be updated matches the <span class="command"><strong>name</strong></span> field + (in the manner specified by the <span class="command"><strong>ruletype</strong></span> + field), and the type of the record to be updated matches the + <span class="command"><strong>types</strong></span> field. Details for each rule type + are described below. + </p> + <p> + The <span class="command"><strong>identity</strong></span> field must be set to + a fully-qualified domain name. In most cases, this + represensts the name of the TSIG or SIG(0) key that must be + used to sign the update request. If the specified name is a + wildcard, it is subject to DNS wildcard expansion, and the + rule may apply to multiple identities. When a TKEY exchange + has been used to create a shared secret, the identity of + the key used to authenticate the TKEY exchange will be + used as the identity of the shared secret. Some rule types + use identities matching the client's Kerberos principal + (e.g, <strong class="userinput"><code>"host/machine@REALM"</code></strong>) or + Windows realm (<strong class="userinput"><code>machine$@REALM</code></strong>). + </p> + <p> + The <em class="replaceable"><code>name</code></em> field also specifies + a fully-qualified domain name. This often + represents the name of the record to be updated. + Interpretation of this field is dependent on rule type. + </p> + <p> + If no <span class="command"><strong>types</strong></span> are explicitly specified, + then a rule matches all types except RRSIG, NS, SOA, NSEC + and NSEC3. Types may be specified by name, including + "ANY" (ANY matches all types except NSEC and NSEC3, + which can never be updated). Note that when an attempt + is made to delete all records associated with a name, + the rules are checked for each existing record type. + </p> + <p> + The <em class="replaceable"><code>ruletype</code></em> field has 16 + values: + <code class="varname">name</code>, <code class="varname">subdomain</code>, + <code class="varname">wildcard</code>, <code class="varname">self</code>, + <code class="varname">selfsub</code>, <code class="varname">selfwild</code>, + <code class="varname">krb5-self</code>, <code class="varname">ms-self</code>, + <code class="varname">krb5-selfsub</code>, <code class="varname">ms-selfsub</code>, + <code class="varname">krb5-subdomain</code>, + <code class="varname">ms-subdomain</code>, + <code class="varname">tcp-self</code>, <code class="varname">6to4-self</code>, + <code class="varname">zonesub</code>, and <code class="varname">external</code>. + </p> + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="0.819in" class="1"> +<col width="3.681in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p> + <code class="varname">name</code> + </p> + </td> +<td> + <p> + Exact-match semantics. This rule matches + when the name being updated is identical + to the contents of the + <em class="replaceable"><code>name</code></em> field. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">subdomain</code> + </p> + </td> +<td> + <p> + This rule matches when the name being updated + is a subdomain of, or identical to, the + contents of the <em class="replaceable"><code>name</code></em> + field. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">zonesub</code> + </p> + </td> +<td> + <p> + This rule is similar to subdomain, except that + it matches when the name being updated is a + subdomain of the zone in which the + <span class="command"><strong>update-policy</strong></span> statement + appears. This obviates the need to type the zone + name twice, and enables the use of a standard + <span class="command"><strong>update-policy</strong></span> statement in + multiple zones without modification. + </p> + <p> + When this rule is used, the + <em class="replaceable"><code>name</code></em> field is omitted. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">wildcard</code> + </p> + </td> +<td> + <p> + The <em class="replaceable"><code>name</code></em> field + is subject to DNS wildcard expansion, and + this rule matches when the name being updated + is a valid expansion of the wildcard. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">self</code> + </p> + </td> +<td> + <p> + This rule matches when the name of the record + being updated matches the contents of the + <em class="replaceable"><code>identity</code></em> field. + The <em class="replaceable"><code>name</code></em> field + is ignored. To avoid confusion, it is recommended + that this field be set to the same value as the + <em class="replaceable"><code>identity</code></em> field or to + "." + </p> + <p> + The <code class="varname">self</code> rule type is + most useful when allowing one key per + name to update, where the key has the same + name as the record to be updated. In this case, + the <em class="replaceable"><code>identity</code></em> field + can be specified as <code class="constant">*</code> + (an asterisk). + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">selfsub</code> + </p> + </td> +<td> + <p> + This rule is similar to <code class="varname">self</code> + except that subdomains of <code class="varname">self</code> + can also be updated. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">selfwild</code> + </p> + </td> +<td> + <p> + This rule is similar to <code class="varname">self</code> + except that only subdomains of + <code class="varname">self</code> can be updated. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">ms-self</code> + </p> + </td> +<td> + <p> + When a client sends an UPDATE using a Windows + machine principal (for example, 'machine$@REALM'), + this rule allows records with the absolute name + of 'machine.REALM' to be updated. + </p> + <p> + The realm to be matched is specified in the + <em class="replaceable"><code>identity</code></em> field. + </p> + <p> + The <em class="replaceable"><code>name</code></em> field has + no effect on this rule; it should be set to "." + as a placeholder. + </p> + <p> + For example, + <strong class="userinput"><code>grant EXAMPLE.COM ms-self . A AAAA</code></strong> + allows any machine with a valid principal in + the realm <strong class="userinput"><code>EXAMPLE.COM</code></strong> to update + its own address records. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">ms-selfsub</code> + </p> + </td> +<td> + <p> + This is similar to <span class="command"><strong>ms-self</strong></span> + except it also allows updates to any subdomain of + the name specified in the Windows machine + principal, not just to the name itself. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">ms-subdomain</code> + </p> + </td> +<td> + <p> + When a client sends an UPDATE using a Windows + machine principal (for example, 'machine$@REALM'), + this rule allows any machine in the specified + realm to update any record in the zone or in a + specified subdomain of the zone. + </p> + <p> + The realm to be matched is specified in the + <em class="replaceable"><code>identity</code></em> field. + </p> + <p> + The <em class="replaceable"><code>name</code></em> field + specifies the subdomain that may be updated. + If set to "." (or any other name at or above + the zone apex), any name in the zone can be + updated. + </p> + <p> + For example, if <span class="command"><strong>update-policy</strong></span> + for the zone "example.com" includes + <strong class="userinput"><code>grant EXAMPLE.COM ms-subdomain hosts.example.com. A AAAA</code></strong>, + any machine with a valid principal in + the realm <strong class="userinput"><code>EXAMPLE.COM</code></strong> will + be able to update address records at or below + "hosts.example.com". + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">krb5-self</code> + </p> + </td> +<td> + <p> + When a client sends an UPDATE using a + Kerberos machine principal (for example, + 'host/machine@REALM'), this rule allows + records with the absolute name of 'machine' + to be updated provided it has been authenticated + by REALM. This is similar but not identical + to <span class="command"><strong>ms-self</strong></span> due to the + 'machine' part of the Kerberos principal + being an absolute name instead of a unqualified + name. + </p> + <p> + The realm to be matched is specified in the + <em class="replaceable"><code>identity</code></em> field. + </p> + <p> + The <em class="replaceable"><code>name</code></em> field has + no effect on this rule; it should be set to "." + as a placeholder. + </p> + <p> + For example, + <strong class="userinput"><code>grant EXAMPLE.COM krb5-self . A AAAA</code></strong> + allows any machine with a valid principal in + the realm <strong class="userinput"><code>EXAMPLE.COM</code></strong> to update + its own address records. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">krb5-selfsub</code> + </p> + </td> +<td> + <p> + This is similar to <span class="command"><strong>krb5-self</strong></span> + except it also allows updates to any subdomain of + the name specified in the 'machine' part of the + Kerberos principal, not just to the name itself. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">krb5-subdomain</code> + </p> + </td> +<td> + <p> + This rule is identical to + <span class="command"><strong>ms-subdomain</strong></span>, except that it works + with Kerberos machine principals (i.e., + 'host/machine@REALM') rather than Windows machine + principals. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">tcp-self</code> + </p> + </td> +<td> + <p> + This rule allows updates that have been sent via + TCP and for which the standard mapping from the + client's IP address into the + <code class="literal">in-addr.arpa</code> and + <code class="literal">ip6.arpa</code> + namespaces match the name to be updated. + The <span class="command"><strong>identity</strong></span> field must match + that name. The <span class="command"><strong>name</strong></span> field + should be set to ".". + Note that, since identity is based on the client's + IP address, it is not necessary for update request + messages to be signed. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + It is theoretically possible to spoof these TCP + sessions. + </div> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">6to4-self</code> + </p> + </td> +<td> + <p> + This allows the name matching a 6to4 IPv6 prefix, + as specified in RFC 3056, to be updated by any + TCP connection from either the 6to4 network or + from the corresponding IPv4 address. This is + intended to allow NS or DNAME RRsets to be added + to the <code class="literal">ip6.arpa</code> reverse tree. + </p> + <p> + The <span class="command"><strong>identity</strong></span> field must match + the 6to4 prefix in <code class="literal">ip6.arpa</code>. + The <span class="command"><strong>name</strong></span> field should + be set to ".". + Note that, since identity is based on the client's + IP address, it is not necessary for update request + messages to be signed. + </p> + <p> + In addition, if specified for an + <code class="literal">ip6.arpa</code> name outside of the + <code class="literal">2.0.0.2.ip6.arpa</code> namespace, + the corresponding /48 reverse name can be updated. + For example, TCP/IPv6 connections + from 2001:DB8:ED0C::/48 can update records at + <code class="literal">C.0.D.E.8.B.D.0.1.0.0.2.ip6.arpa</code>. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + It is theoretically possible to spoof these TCP + sessions. + </div> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">external</code> + </p> + </td> +<td> + <p> + This rule allows <span class="command"><strong>named</strong></span> + to defer the decision of whether to allow a + given update to an external daemon. + </p> + <p> + The method of communicating with the daemon is + specified in the <em class="replaceable"><code>identity</code></em> + field, the format of which is + "<code class="constant">local:</code><em class="replaceable"><code>path</code></em>", + where <em class="replaceable"><code>path</code></em> is the location + of a UNIX-domain socket. (Currently, "local" is the + only supported mechanism.) + </p> + <p> + Requests to the external daemon are sent over the + UNIX-domain socket as datagrams with the following + format: + </p> + <pre class="programlisting"> + Protocol version number (4 bytes, network byte order, currently 1) + Request length (4 bytes, network byte order) + Signer (null-terminated string) + Name (null-terminated string) + TCP source address (null-terminated string) + Rdata type (null-terminated string) + Key (null-terminated string) + TKEY token length (4 bytes, network byte order) + TKEY token (remainder of packet)</pre> + <p> + The daemon replies with a four-byte value in + network byte order, containing either 0 or 1; 0 + indicates that the specified update is not + permitted, and 1 indicates that it is. + </p> + </td> +</tr> +</tbody> +</table> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="multiple_views"></a>Multiple views</h4></div></div></div> + + <p> + When multiple views are in use, a zone may be + referenced by more than one of them. Often, the views + will contain different zones with the same name, allowing + different clients to receive different answers for the same + queries. At times, however, it is desirable for multiple + views to contain identical zones. The + <span class="command"><strong>in-view</strong></span> zone option provides an efficient + way to do this: it allows a view to reference a zone that + was defined in a previously configured view. Example: + </p> + <pre class="programlisting"> +view internal { + match-clients { 10/8; }; + + zone example.com { + type master; + file "example-external.db"; + }; +}; + +view external { + match-clients { any; }; + + zone example.com { + in-view internal; + }; +}; + </pre> + <p> + An <span class="command"><strong>in-view</strong></span> option cannot refer to a view + that is configured later in the configuration file. + </p> + <p> + A <span class="command"><strong>zone</strong></span> statement which uses the + <span class="command"><strong>in-view</strong></span> option may not use any other + options with the exception of <span class="command"><strong>forward</strong></span> + and <span class="command"><strong>forwarders</strong></span>. (These options control + the behavior of the containing view, rather than changing + the zone object itself.) + </p> + <p> + Zone level acls (e.g. allow-query, allow-transfer) and + other configuration details of the zone are all set + in the view the referenced zone is defined in. Care + need to be taken to ensure that acls are wide enough + for all views referencing the zone. + </p> + <p> + An <span class="command"><strong>in-view</strong></span> zone cannot be used as a + response policy zone. + </p> + <p> + An <span class="command"><strong>in-view</strong></span> zone is not intended to reference + a <span class="command"><strong>forward</strong></span> zone. + </p> + </div> + + </div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="zone_file"></a>Zone File</h2></div></div></div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="types_of_resource_records_and_when_to_use_them"></a>Types of Resource Records and When to Use Them</h3></div></div></div> + + <p> + This section, largely borrowed from RFC 1034, describes the + concept of a Resource Record (RR) and explains when each is used. + Since the publication of RFC 1034, several new RRs have been + identified + and implemented in the DNS. These are also included. + </p> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.7.6.2.3"></a>Resource Records</h4></div></div></div> + + <p> + A domain name identifies a node. Each node has a set of + resource information, which may be empty. The set of resource + information associated with a particular name is composed of + separate RRs. The order of RRs in a set is not significant and + need not be preserved by name servers, resolvers, or other + parts of the DNS. However, sorting of multiple RRs is + permitted for optimization purposes, for example, to specify + that a particular nearby server be tried first. See <a class="xref" href="Bv9ARM.ch06.html#the_sortlist_statement" title="The sortlist Statement">the section called “The <span class="command"><strong>sortlist</strong></span> Statement”</a> and <a class="xref" href="Bv9ARM.ch06.html#rrset_ordering" title="RRset Ordering">the section called “RRset Ordering”</a>. + </p> + + <p> + The components of a Resource Record are: + </p> + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.000in" class="1"> +<col width="3.500in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p> + owner name + </p> + </td> +<td> + <p> + The domain name where the RR is found. + </p> + </td> +</tr> +<tr> +<td> + <p> + type + </p> + </td> +<td> + <p> + An encoded 16-bit value that specifies + the type of the resource record. + </p> + </td> +</tr> +<tr> +<td> + <p> + TTL + </p> + </td> +<td> + <p> + The time-to-live of the RR. This field + is a 32-bit integer in units of seconds, and is + primarily used by + resolvers when they cache RRs. The TTL describes how + long a RR can + be cached before it should be discarded. + </p> + </td> +</tr> +<tr> +<td> + <p> + class + </p> + </td> +<td> + <p> + An encoded 16-bit value that identifies + a protocol family or instance of a protocol. + </p> + </td> +</tr> +<tr> +<td> + <p> + RDATA + </p> + </td> +<td> + <p> + The resource data. The format of the + data is type (and sometimes class) specific. + </p> + </td> +</tr> +</tbody> +</table> + </div> + <p> + The following are <span class="emphasis"><em>types</em></span> of valid RRs: + </p> + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="0.875in" class="1"> +<col width="3.625in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p> + A + </p> + </td> +<td> + <p> + A host address. In the IN class, this is a + 32-bit IP address. Described in RFC 1035. + </p> + </td> +</tr> +<tr> +<td> + <p> + AAAA + </p> + </td> +<td> + <p> + IPv6 address. Described in RFC 1886. + </p> + </td> +</tr> +<tr> +<td> + <p> + A6 + </p> + </td> +<td> + <p> + IPv6 address. This can be a partial + address (a suffix) and an indirection to the name + where the rest of the + address (the prefix) can be found. Experimental. + Described in RFC 2874. + </p> + </td> +</tr> +<tr> +<td> + <p> + AFSDB + </p> + </td> +<td> + <p> + Location of AFS database servers. + Experimental. Described in RFC 1183. + </p> + </td> +</tr> +<tr> +<td> + <p> + APL + </p> + </td> +<td> + <p> + Address prefix list. Experimental. + Described in RFC 3123. + </p> + </td> +</tr> +<tr> +<td> + <p> + ATMA + </p> + </td> +<td> + <p> + ATM Address. + </p> + </td> +</tr> +<tr> +<td> + <p> + AVC + </p> + </td> +<td> + <p> + Application Visibility and Control record. + </p> + </td> +</tr> +<tr> +<td> + <p> + CAA + </p> + </td> +<td> + <p> + Identifies which Certificate Authorities can issue + certificates for this domain and what rules they + need to follow when doing so. Defined in RFC 6844. + </p> + </td> +</tr> +<tr> +<td> + <p> + CDNSKEY + </p> + </td> +<td> + <p> + Identifies which DNSKEY records should be published + as DS records in the parent zone. + </p> + </td> +</tr> +<tr> +<td> + <p> + CDS + </p> + </td> +<td> + <p> + Contains the set of DS records that should be published + by the parent zone. + </p> + </td> +</tr> +<tr> +<td> + <p> + CERT + </p> + </td> +<td> + <p> + Holds a digital certificate. + Described in RFC 2538. + </p> + </td> +</tr> +<tr> +<td> + <p> + CNAME + </p> + </td> +<td> + <p> + Identifies the canonical name of an alias. + Described in RFC 1035. + </p> + </td> +</tr> +<tr> +<td> + <p> + CSYNC + </p> + </td> +<td> + <p> + Child-to-Parent Synchronization in DNS as described + in RFC 7477. + </p> + </td> +</tr> +<tr> +<td> + <p> + DHCID + </p> + </td> +<td> + <p> + Is used for identifying which DHCP client is + associated with this name. Described in RFC 4701. + </p> + </td> +</tr> +<tr> +<td> + <p> + DLV + </p> + </td> +<td> + <p> + A DNS Look-aside Validation record which contains + the records that are used as trust anchors for + zones in a DLV namespace. Described in RFC 4431. + </p> + </td> +</tr> +<tr> +<td> + <p> + DNAME + </p> + </td> +<td> + <p> + Replaces the domain name specified with + another name to be looked up, effectively aliasing an + entire + subtree of the domain name space rather than a single + record + as in the case of the CNAME RR. + Described in RFC 2672. + </p> + </td> +</tr> +<tr> +<td> + <p> + DNSKEY + </p> + </td> +<td> + <p> + Stores a public key associated with a signed + DNS zone. Described in RFC 4034. + </p> + </td> +</tr> +<tr> +<td> + <p> + DOA + </p> + </td> +<td> + <p> + Implements the Digital Object Architecture over + DNS. Experimental. + </p> + </td> +</tr> +<tr> +<td> + <p> + DS + </p> + </td> +<td> + <p> + Stores the hash of a public key associated with a + signed DNS zone. Described in RFC 4034. + </p> + </td> +</tr> +<tr> +<td> + <p> + EID + </p> + </td> +<td> + <p> + End Point Identifier. + </p> + </td> +</tr> +<tr> +<td> + <p> + EUI48 + </p> + </td> +<td> + <p> + A 48-bit EUI address. Described in RFC 7043. + </p> + </td> +</tr> +<tr> +<td> + <p> + EUI64 + </p> + </td> +<td> + <p> + A 64-bit EUI address. Described in RFC 7043. + </p> + </td> +</tr> +<tr> +<td> + <p> + GID + </p> + </td> +<td> + <p> + Reserved. + </p> + </td> +</tr> +<tr> +<td> + <p> + GPOS + </p> + </td> +<td> + <p> + Specifies the global position. Superseded by LOC. + </p> + </td> +</tr> +<tr> +<td> + <p> + HINFO + </p> + </td> +<td> + <p> + Identifies the CPU and OS used by a host. + Described in RFC 1035. + </p> + </td> +</tr> +<tr> +<td> + <p> + HIP + </p> + </td> +<td> + <p> + Host Identity Protocol Address. + Described in RFC 5205. + </p> + </td> +</tr> +<tr> +<td> + <p> + IPSECKEY + </p> + </td> +<td> + <p> + Provides a method for storing IPsec keying material in + DNS. Described in RFC 4025. + </p> + </td> +</tr> +<tr> +<td> + <p> + ISDN + </p> + </td> +<td> + <p> + Representation of ISDN addresses. + Experimental. Described in RFC 1183. + </p> + </td> +</tr> +<tr> +<td> + <p> + KEY + </p> + </td> +<td> + <p> + Stores a public key associated with a + DNS name. Used in original DNSSEC; replaced + by DNSKEY in DNSSECbis, but still used with + SIG(0). Described in RFCs 2535 and 2931. + </p> + </td> +</tr> +<tr> +<td> + <p> + KX + </p> + </td> +<td> + <p> + Identifies a key exchanger for this + DNS name. Described in RFC 2230. + </p> + </td> +</tr> +<tr> +<td> + <p> + L32 + </p> + </td> +<td> + <p> + Holds 32-bit Locator values for + Identifier-Locator Network Protocol. Described + in RFC 6742. + </p> + </td> +</tr> +<tr> +<td> + <p> + L64 + </p> + </td> +<td> + <p> + Holds 64-bit Locator values for + Identifier-Locator Network Protocol. Described + in RFC 6742. + </p> + </td> +</tr> +<tr> +<td> + <p> + LOC + </p> + </td> +<td> + <p> + For storing GPS info. Described in RFC 1876. + Experimental. + </p> + </td> +</tr> +<tr> +<td> + <p> + LP + </p> + </td> +<td> + <p> + Identifier-Locator Network Protocol. + Described in RFC 6742. + </p> + </td> +</tr> +<tr> +<td> + <p> + MB + </p> + </td> +<td> + <p> + Mail Box. Historical. + </p> + </td> +</tr> +<tr> +<td> + <p> + MD + </p> + </td> +<td> + <p> + Mail Destination. Historical. + </p> + </td> +</tr> +<tr> +<td> + <p> + MF + </p> + </td> +<td> + <p> + Mail Forwarder. Historical. + </p> + </td> +</tr> +<tr> +<td> + <p> + MG + </p> + </td> +<td> + <p> + Mail Group. Historical. + </p> + </td> +</tr> +<tr> +<td> + <p> + MINFO + </p> + </td> +<td> + <p> + Mail Information. + </p> + </td> +</tr> +<tr> +<td> + <p> + MR + </p> + </td> +<td> + <p> + Mail Rename. Historical. + </p> + </td> +</tr> +<tr> +<td> + <p> + MX + </p> + </td> +<td> + <p> + Identifies a mail exchange for the domain with + a 16-bit preference value (lower is better) + followed by the host name of the mail exchange. + Described in RFC 974, RFC 1035. + </p> + </td> +</tr> +<tr> +<td> + <p> + NAPTR + </p> + </td> +<td> + <p> + Name authority pointer. Described in RFC 2915. + </p> + </td> +</tr> +<tr> +<td> + <p> + NID + </p> + </td> +<td> + <p> + Holds values for Node Identifiers in + Identifier-Locator Network Protocol. Described + in RFC 6742. + </p> + </td> +</tr> +<tr> +<td> + <p> + NINFO + </p> + </td> +<td> + <p> + Contains zone status information. + </p> + </td> +</tr> +<tr> +<td> + <p> + NIMLOC + </p> + </td> +<td> + <p> + Nimrod Locator. + </p> + </td> +</tr> +<tr> +<td> + <p> + NSAP + </p> + </td> +<td> + <p> + A network service access point. + Described in RFC 1706. + </p> + </td> +</tr> +<tr> +<td> + <p> + NSAP-PTR + </p> + </td> +<td> + <p> + Historical. + </p> + </td> +</tr> +<tr> +<td> + <p> + NS + </p> + </td> +<td> + <p> + The authoritative name server for the + domain. Described in RFC 1035. + </p> + </td> +</tr> +<tr> +<td> + <p> + NSEC + </p> + </td> +<td> + <p> + Used in DNSSECbis to securely indicate that + RRs with an owner name in a certain name interval do + not exist in + a zone and indicate what RR types are present for an + existing name. + Described in RFC 4034. + </p> + </td> +</tr> +<tr> +<td> + <p> + NSEC3 + </p> + </td> +<td> + <p> + Used in DNSSECbis to securely indicate that + RRs with an owner name in a certain name + interval do not exist in a zone and indicate + what RR types are present for an existing + name. NSEC3 differs from NSEC in that it + prevents zone enumeration but is more + computationally expensive on both the server + and the client than NSEC. Described in RFC + 5155. + </p> + </td> +</tr> +<tr> +<td> + <p> + NSEC3PARAM + </p> + </td> +<td> + <p> + Used in DNSSECbis to tell the authoritative + server which NSEC3 chains are available to use. + Described in RFC 5155. + </p> + </td> +</tr> +<tr> +<td> + <p> + NULL + </p> + </td> +<td> + <p> + This is an opaque container. + </p> + </td> +</tr> +<tr> +<td> + <p> + NXT + </p> + </td> +<td> + <p> + Used in DNSSEC to securely indicate that + RRs with an owner name in a certain name interval do + not exist in + a zone and indicate what RR types are present for an + existing name. + Used in original DNSSEC; replaced by NSEC in + DNSSECbis. + Described in RFC 2535. + </p> + </td> +</tr> +<tr> +<td> + <p> + OPENPGPKEY + </p> + </td> +<td> + <p> + Used to hold an OPENPGPKEY. + </p> + </td> +</tr> +<tr> +<td> + <p> + PTR + </p> + </td> +<td> + <p> + A pointer to another part of the domain + name space. Described in RFC 1035. + </p> + </td> +</tr> +<tr> +<td> + <p> + PX + </p> + </td> +<td> + <p> + Provides mappings between RFC 822 and X.400 + addresses. Described in RFC 2163. + </p> + </td> +</tr> +<tr> +<td> + <p> + RKEY + </p> + </td> +<td> + <p> + Resource key. + </p> + </td> +</tr> +<tr> +<td> + <p> + RP + </p> + </td> +<td> + <p> + Information on persons responsible + for the domain. Experimental. Described in RFC 1183. + </p> + </td> +</tr> +<tr> +<td> + <p> + RRSIG + </p> + </td> +<td> + <p> + Contains DNSSECbis signature data. Described + in RFC 4034. + </p> + </td> +</tr> +<tr> +<td> + <p> + RT + </p> + </td> +<td> + <p> + Route-through binding for hosts that + do not have their own direct wide area network + addresses. + Experimental. Described in RFC 1183. + </p> + </td> +</tr> +<tr> +<td> + <p> + SIG + </p> + </td> +<td> + <p> + Contains DNSSEC signature data. Used in + original DNSSEC; replaced by RRSIG in + DNSSECbis, but still used for SIG(0). + Described in RFCs 2535 and 2931. + </p> + </td> +</tr> +<tr> +<td> + <p> + SINK + </p> + </td> +<td> + <p> + The kitchen sink record. + </p> + </td> +</tr> +<tr> +<td> + <p> + SMIMEA + </p> + </td> +<td> + <p> + The S/MIME Security Certificate Association. + </p> + </td> +</tr> +<tr> +<td> + <p> + SOA + </p> + </td> +<td> + <p> + Identifies the start of a zone of authority. + Described in RFC 1035. + </p> + </td> +</tr> +<tr> +<td> + <p> + SPF + </p> + </td> +<td> + <p> + Contains the Sender Policy Framework information + for a given email domain. Described in RFC 4408. + </p> + </td> +</tr> +<tr> +<td> + <p> + SRV + </p> + </td> +<td> + <p> + Information about well known network + services (replaces WKS). Described in RFC 2782. + </p> + </td> +</tr> +<tr> +<td> + <p> + SSHFP + </p> + </td> +<td> + <p> + Provides a way to securely publish a secure shell key's + fingerprint. Described in RFC 4255. + </p> + </td> +</tr> +<tr> +<td> + <p> + TA + </p> + </td> +<td> + <p> + Trust Anchor. Experimental. + </p> + </td> +</tr> +<tr> +<td> + <p> + TALINK + </p> + </td> +<td> + <p> + Trust Anchor Link. Experimental. + </p> + </td> +</tr> +<tr> +<td> + <p> + TLSA + </p> + </td> +<td> + <p> + Transport Layer Security Certificate Association. + Described in RFC 6698. + </p> + </td> +</tr> +<tr> +<td> + <p> + TXT + </p> + </td> +<td> + <p> + Text records. Described in RFC 1035. + </p> + </td> +</tr> +<tr> +<td> + <p> + UID + </p> + </td> +<td> + <p> + Reserved. + </p> + </td> +</tr> +<tr> +<td> + <p> + UINFO + </p> + </td> +<td> + <p> + Reserved. + </p> + </td> +</tr> +<tr> +<td> + <p> + UNSPEC + </p> + </td> +<td> + <p> + Reserved. Historical. + </p> + </td> +</tr> +<tr> +<td> + <p> + URI + </p> + </td> +<td> + <p> + Holds a URI. Described in RFC 7553. + </p> + </td> +</tr> +<tr> +<td> + <p> + WKS + </p> + </td> +<td> + <p> + Information about which well known + network services, such as SMTP, that a domain + supports. Historical. + </p> + </td> +</tr> +<tr> +<td> + <p> + X25 + </p> + </td> +<td> + <p> + Representation of X.25 network addresses. + Experimental. Described in RFC 1183. + </p> + </td> +</tr> +</tbody> +</table> + </div> + <p> + The following <span class="emphasis"><em>classes</em></span> of resource records + are currently valid in the DNS: + </p> + <div class="informaltable"> +<table border="1"> +<colgroup> +<col width="0.875in" class="1"> +<col width="3.625in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p> + IN + </p> + </td> +<td> + <p> + The Internet. + </p> + </td> +</tr> +<tr> +<td> + <p> + CH + </p> + </td> +<td> + <p> + Chaosnet, a LAN protocol created at MIT in the + mid-1970s. + Rarely used for its historical purpose, but reused for + BIND's + built-in server information zones, e.g., + <code class="literal">version.bind</code>. + </p> + </td> +</tr> +<tr> +<td> + <p> + HS + </p> + </td> +<td> + <p> + Hesiod, an information service + developed by MIT's Project Athena. It is used to share + information + about various systems databases, such as users, + groups, printers + and so on. + </p> + </td> +</tr> +</tbody> +</table> + </div> + + <p> + The owner name is often implicit, rather than forming an + integral + part of the RR. For example, many name servers internally form + tree + or hash structures for the name space, and chain RRs off nodes. + The remaining RR parts are the fixed header (type, class, TTL) + which is consistent for all RRs, and a variable part (RDATA) + that + fits the needs of the resource being described. + </p> + <p> + The meaning of the TTL field is a time limit on how long an + RR can be kept in a cache. This limit does not apply to + authoritative + data in zones; it is also timed out, but by the refreshing + policies + for the zone. The TTL is assigned by the administrator for the + zone where the data originates. While short TTLs can be used to + minimize caching, and a zero TTL prohibits caching, the + realities + of Internet performance suggest that these times should be on + the + order of days for the typical host. If a change can be + anticipated, + the TTL can be reduced prior to the change to minimize + inconsistency + during the change, and then increased back to its former value + following + the change. + </p> + <p> + The data in the RDATA section of RRs is carried as a combination + of binary strings and domain names. The domain names are + frequently + used as "pointers" to other data in the DNS. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="rr_text"></a>Textual expression of RRs</h4></div></div></div> + + <p> + RRs are represented in binary form in the packets of the DNS + protocol, and are usually represented in highly encoded form + when + stored in a name server or resolver. In the examples provided + in + RFC 1034, a style similar to that used in master files was + employed + in order to show the contents of RRs. In this format, most RRs + are shown on a single line, although continuation lines are + possible + using parentheses. + </p> + <p> + The start of the line gives the owner of the RR. If a line + begins with a blank, then the owner is assumed to be the same as + that of the previous RR. Blank lines are often included for + readability. + </p> + <p> + Following the owner, we list the TTL, type, and class of the + RR. Class and type use the mnemonics defined above, and TTL is + an integer before the type field. In order to avoid ambiguity + in + parsing, type and class mnemonics are disjoint, TTLs are + integers, + and the type mnemonic is always last. The IN class and TTL + values + are often omitted from examples in the interests of clarity. + </p> + <p> + The resource data or RDATA section of the RR are given using + knowledge of the typical representation for the data. + </p> + <p> + For example, we might show the RRs carried in a message as: + </p> + <div class="informaltable"> +<table border="1"> +<colgroup> +<col width="1.381in" class="1"> +<col width="1.020in" class="2"> +<col width="2.099in" class="3"> +</colgroup> +<tbody> +<tr> +<td> + <p> + <code class="literal">ISI.EDU.</code> + </p> + </td> +<td> + <p> + <code class="literal">MX</code> + </p> + </td> +<td> + <p> + <code class="literal">10 VENERA.ISI.EDU.</code> + </p> + </td> +</tr> +<tr> +<td> + <p></p> + </td> +<td> + <p> + <code class="literal">MX</code> + </p> + </td> +<td> + <p> + <code class="literal">10 VAXA.ISI.EDU</code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="literal">VENERA.ISI.EDU</code> + </p> + </td> +<td> + <p> + <code class="literal">A</code> + </p> + </td> +<td> + <p> + <code class="literal">128.9.0.32</code> + </p> + </td> +</tr> +<tr> +<td> + <p></p> + </td> +<td> + <p> + <code class="literal">A</code> + </p> + </td> +<td> + <p> + <code class="literal">10.1.0.52</code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="literal">VAXA.ISI.EDU</code> + </p> + </td> +<td> + <p> + <code class="literal">A</code> + </p> + </td> +<td> + <p> + <code class="literal">10.2.0.27</code> + </p> + </td> +</tr> +<tr> +<td> + <p></p> + </td> +<td> + <p> + <code class="literal">A</code> + </p> + </td> +<td> + <p> + <code class="literal">128.9.0.33</code> + </p> + </td> +</tr> +</tbody> +</table> + </div> + <p> + The MX RRs have an RDATA section which consists of a 16-bit + number followed by a domain name. The address RRs use a + standard + IP address format to contain a 32-bit internet address. + </p> + <p> + The above example shows six RRs, with two RRs at each of three + domain names. + </p> + <p> + Similarly we might see: + </p> + <div class="informaltable"> +<table border="1"> +<colgroup> +<col width="1.491in" class="1"> +<col width="1.067in" class="2"> +<col width="2.067in" class="3"> +</colgroup> +<tbody> +<tr> +<td> + <p> + <code class="literal">XX.LCS.MIT.EDU.</code> + </p> + </td> +<td> + <p> + <code class="literal">IN A</code> + </p> + </td> +<td> + <p> + <code class="literal">10.0.0.44</code> + </p> + </td> +</tr> +<tr> +<td> </td> +<td> + <p> + <code class="literal">CH A</code> + </p> + </td> +<td> + <p> + <code class="literal">MIT.EDU. 2420</code> + </p> + </td> +</tr> +</tbody> +</table> + </div> + <p> + This example shows two addresses for + <code class="literal">XX.LCS.MIT.EDU</code>, each of a different class. + </p> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mx_records"></a>Discussion of MX Records</h3></div></div></div> + + <p> + As described above, domain servers store information as a + series of resource records, each of which contains a particular + piece of information about a given domain name (which is usually, + but not always, a host). The simplest way to think of a RR is as + a typed pair of data, a domain name matched with a relevant datum, + and stored with some additional type information to help systems + determine when the RR is relevant. + </p> + + <p> + MX records are used to control delivery of email. The data + specified in the record is a priority and a domain name. The + priority + controls the order in which email delivery is attempted, with the + lowest number first. If two priorities are the same, a server is + chosen randomly. If no servers at a given priority are responding, + the mail transport agent will fall back to the next largest + priority. + Priority numbers do not have any absolute meaning — they are + relevant + only respective to other MX records for that domain name. The + domain + name given is the machine to which the mail will be delivered. + It <span class="emphasis"><em>must</em></span> have an associated address record + (A or AAAA) — CNAME is not sufficient. + </p> + <p> + For a given domain, if there is both a CNAME record and an + MX record, the MX record is in error, and will be ignored. + Instead, + the mail will be delivered to the server specified in the MX + record + pointed to by the CNAME. + For example: + </p> + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.708in" class="1"> +<col width="0.444in" class="2"> +<col width="0.444in" class="3"> +<col width="0.976in" class="4"> +<col width="1.553in" class="5"> +</colgroup> +<tbody> +<tr> +<td> + <p> + <code class="literal">example.com.</code> + </p> + </td> +<td> + <p> + <code class="literal">IN</code> + </p> + </td> +<td> + <p> + <code class="literal">MX</code> + </p> + </td> +<td> + <p> + <code class="literal">10</code> + </p> + </td> +<td> + <p> + <code class="literal">mail.example.com.</code> + </p> + </td> +</tr> +<tr> +<td> + <p></p> + </td> +<td> + <p> + <code class="literal">IN</code> + </p> + </td> +<td> + <p> + <code class="literal">MX</code> + </p> + </td> +<td> + <p> + <code class="literal">10</code> + </p> + </td> +<td> + <p> + <code class="literal">mail2.example.com.</code> + </p> + </td> +</tr> +<tr> +<td> + <p></p> + </td> +<td> + <p> + <code class="literal">IN</code> + </p> + </td> +<td> + <p> + <code class="literal">MX</code> + </p> + </td> +<td> + <p> + <code class="literal">20</code> + </p> + </td> +<td> + <p> + <code class="literal">mail.backup.org.</code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="literal">mail.example.com.</code> + </p> + </td> +<td> + <p> + <code class="literal">IN</code> + </p> + </td> +<td> + <p> + <code class="literal">A</code> + </p> + </td> +<td> + <p> + <code class="literal">10.0.0.1</code> + </p> + </td> +<td> + <p></p> + </td> +</tr> +<tr> +<td> + <p> + <code class="literal">mail2.example.com.</code> + </p> + </td> +<td> + <p> + <code class="literal">IN</code> + </p> + </td> +<td> + <p> + <code class="literal">A</code> + </p> + </td> +<td> + <p> + <code class="literal">10.0.0.2</code> + </p> + </td> +<td> + <p></p> + </td> +</tr> +</tbody> +</table> + </div> +<p> + Mail delivery will be attempted to <code class="literal">mail.example.com</code> and + <code class="literal">mail2.example.com</code> (in + any order), and if neither of those succeed, delivery to <code class="literal">mail.backup.org</code> will + be attempted. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="Setting_TTLs"></a>Setting TTLs</h3></div></div></div> + + <p> + The time-to-live of the RR field is a 32-bit integer represented + in units of seconds, and is primarily used by resolvers when they + cache RRs. The TTL describes how long a RR can be cached before it + should be discarded. The following three types of TTL are + currently + used in a zone file. + </p> + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="0.750in" class="1"> +<col width="4.375in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p> + SOA + </p> + </td> +<td> + <p> + The last field in the SOA is the negative + caching TTL. This controls how long other servers will + cache no-such-domain + (NXDOMAIN) responses from you. + </p> + <p> + The maximum time for + negative caching is 3 hours (3h). + </p> + </td> +</tr> +<tr> +<td> + <p> + $TTL + </p> + </td> +<td> + <p> + The $TTL directive at the top of the + zone file (before the SOA) gives a default TTL for every + RR without + a specific TTL set. + </p> + </td> +</tr> +<tr> +<td> + <p> + RR TTLs + </p> + </td> +<td> + <p> + Each RR can have a TTL as the second + field in the RR, which will control how long other + servers can cache it. + </p> + </td> +</tr> +</tbody> +</table> + </div> + <p> + All of these TTLs default to units of seconds, though units + can be explicitly specified, for example, <code class="literal">1h30m</code>. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="ipv4_reverse"></a>Inverse Mapping in IPv4</h3></div></div></div> + + <p> + Reverse name resolution (that is, translation from IP address + to name) is achieved by means of the <span class="emphasis"><em>in-addr.arpa</em></span> domain + and PTR records. Entries in the in-addr.arpa domain are made in + least-to-most significant order, read left to right. This is the + opposite order to the way IP addresses are usually written. Thus, + a machine with an IP address of 10.1.2.3 would have a + corresponding + in-addr.arpa name of + 3.2.1.10.in-addr.arpa. This name should have a PTR resource record + whose data field is the name of the machine or, optionally, + multiple + PTR records if the machine has more than one name. For example, + in the [<span class="optional">example.com</span>] domain: + </p> + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.125in" class="1"> +<col width="4.000in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p> + <code class="literal">$ORIGIN</code> + </p> + </td> +<td> + <p> + <code class="literal">2.1.10.in-addr.arpa</code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="literal">3</code> + </p> + </td> +<td> + <p> + <code class="literal">IN PTR foo.example.com.</code> + </p> + </td> +</tr> +</tbody> +</table> + </div> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + The <span class="command"><strong>$ORIGIN</strong></span> lines in the examples + are for providing context to the examples only — they do not + necessarily + appear in the actual usage. They are only used here to indicate + that the example is relative to the listed origin. + </p> + </div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="zone_directives"></a>Other Zone File Directives</h3></div></div></div> + + <p> + The Master File Format was initially defined in RFC 1035 and + has subsequently been extended. While the Master File Format + itself + is class independent all records in a Master File must be of the + same + class. + </p> + <p> + Master File Directives include <span class="command"><strong>$ORIGIN</strong></span>, <span class="command"><strong>$INCLUDE</strong></span>, + and <span class="command"><strong>$TTL.</strong></span> + </p> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="atsign"></a>The <span class="command"><strong>@</strong></span> (at-sign)</h4></div></div></div> + + <p> + When used in the label (or name) field, the asperand or + at-sign (@) symbol represents the current origin. + At the start of the zone file, it is the + <<code class="varname">zone_name</code>> (followed by + trailing dot). + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="origin_directive"></a>The <span class="command"><strong>$ORIGIN</strong></span> Directive</h4></div></div></div> + + <p> + Syntax: <span class="command"><strong>$ORIGIN</strong></span> + <em class="replaceable"><code>domain-name</code></em> + [<span class="optional"><em class="replaceable"><code>comment</code></em></span>] + </p> + <p><span class="command"><strong>$ORIGIN</strong></span> + sets the domain name that will be appended to any + unqualified records. When a zone is first read in there + is an implicit <span class="command"><strong>$ORIGIN</strong></span> + <<code class="varname">zone_name</code>><span class="command"><strong>.</strong></span> + (followed by trailing dot). + The current <span class="command"><strong>$ORIGIN</strong></span> is appended to + the domain specified in the <span class="command"><strong>$ORIGIN</strong></span> + argument if it is not absolute. + </p> + +<pre class="programlisting"> +$ORIGIN example.com. +WWW CNAME MAIN-SERVER +</pre> + + <p> + is equivalent to + </p> + +<pre class="programlisting"> +WWW.EXAMPLE.COM. CNAME MAIN-SERVER.EXAMPLE.COM. +</pre> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="include_directive"></a>The <span class="command"><strong>$INCLUDE</strong></span> Directive</h4></div></div></div> + + <p> + Syntax: <span class="command"><strong>$INCLUDE</strong></span> + <em class="replaceable"><code>filename</code></em> + [<span class="optional"> +<em class="replaceable"><code>origin</code></em> </span>] + [<span class="optional"> <em class="replaceable"><code>comment</code></em> </span>] + </p> + <p> + Read and process the file <code class="filename">filename</code> as + if it were included into the file at this point. If <span class="command"><strong>origin</strong></span> is + specified the file is processed with <span class="command"><strong>$ORIGIN</strong></span> set + to that value, otherwise the current <span class="command"><strong>$ORIGIN</strong></span> is + used. + </p> + <p> + The origin and the current domain name + revert to the values they had prior to the <span class="command"><strong>$INCLUDE</strong></span> once + the file has been read. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + RFC 1035 specifies that the current origin should be restored + after + an <span class="command"><strong>$INCLUDE</strong></span>, but it is silent + on whether the current + domain name should also be restored. BIND 9 restores both of + them. + This could be construed as a deviation from RFC 1035, a + feature, or both. + </p> + </div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="ttl_directive"></a>The <span class="command"><strong>$TTL</strong></span> Directive</h4></div></div></div> + + <p> + Syntax: <span class="command"><strong>$TTL</strong></span> + <em class="replaceable"><code>default-ttl</code></em> + [<span class="optional"> +<em class="replaceable"><code>comment</code></em> </span>] + </p> + <p> + Set the default Time To Live (TTL) for subsequent records + with undefined TTLs. Valid TTLs are of the range 0-2147483647 + seconds. + </p> + <p><span class="command"><strong>$TTL</strong></span> + is defined in RFC 2308. + </p> + </div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="generate_directive"></a><acronym class="acronym">BIND</acronym> Master File Extension: the <span class="command"><strong>$GENERATE</strong></span> Directive</h3></div></div></div> + + <p> + Syntax: <span class="command"><strong>$GENERATE</strong></span> + <em class="replaceable"><code>range</code></em> + <em class="replaceable"><code>lhs</code></em> + [<span class="optional"><em class="replaceable"><code>ttl</code></em></span>] + [<span class="optional"><em class="replaceable"><code>class</code></em></span>] + <em class="replaceable"><code>type</code></em> + <em class="replaceable"><code>rhs</code></em> + [<span class="optional"><em class="replaceable"><code>comment</code></em></span>] + </p> + <p><span class="command"><strong>$GENERATE</strong></span> + is used to create a series of resource records that only + differ from each other by an + iterator. <span class="command"><strong>$GENERATE</strong></span> can be used to + easily generate the sets of records required to support + sub /24 reverse delegations described in RFC 2317: + Classless IN-ADDR.ARPA delegation. + </p> + +<pre class="programlisting">$ORIGIN 0.0.192.IN-ADDR.ARPA. +$GENERATE 1-2 @ NS SERVER$.EXAMPLE. +$GENERATE 1-127 $ CNAME $.0</pre> + + <p> + is equivalent to + </p> + +<pre class="programlisting">0.0.0.192.IN-ADDR.ARPA. NS SERVER1.EXAMPLE. +0.0.0.192.IN-ADDR.ARPA. NS SERVER2.EXAMPLE. +1.0.0.192.IN-ADDR.ARPA. CNAME 1.0.0.0.192.IN-ADDR.ARPA. +2.0.0.192.IN-ADDR.ARPA. CNAME 2.0.0.0.192.IN-ADDR.ARPA. +... +127.0.0.192.IN-ADDR.ARPA. CNAME 127.0.0.0.192.IN-ADDR.ARPA. +</pre> + + <p> + Generate a set of A and MX records. Note the MX's right hand + side is a quoted string. The quotes will be stripped when the + right hand side is processed. + </p> + +<pre class="programlisting"> +$ORIGIN EXAMPLE. +$GENERATE 1-127 HOST-$ A 1.2.3.$ +$GENERATE 1-127 HOST-$ MX "0 ."</pre> + + <p> + is equivalent to + </p> + +<pre class="programlisting">HOST-1.EXAMPLE. A 1.2.3.1 +HOST-1.EXAMPLE. MX 0 . +HOST-2.EXAMPLE. A 1.2.3.2 +HOST-2.EXAMPLE. MX 0 . +HOST-3.EXAMPLE. A 1.2.3.3 +HOST-3.EXAMPLE. MX 0 . +... +HOST-127.EXAMPLE. A 1.2.3.127 +HOST-127.EXAMPLE. MX 0 . +</pre> + + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="0.875in" class="1"> +<col width="4.250in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p><span class="command"><strong>range</strong></span></p> + </td> +<td> + <p> + This can be one of two forms: start-stop + or start-stop/step. If the first form is used, then step + is set to 1. start, stop and step must be positive + integers between 0 and (2^31)-1. start must not be + larger than stop. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>lhs</strong></span></p> + </td> +<td> + <p>This + describes the owner name of the resource records + to be created. Any single <span class="command"><strong>$</strong></span> + (dollar sign) + symbols within the <span class="command"><strong>lhs</strong></span> string + are replaced by the iterator value. + + To get a $ in the output, you need to escape the + <span class="command"><strong>$</strong></span> using a backslash + <span class="command"><strong>\</strong></span>, + e.g. <span class="command"><strong>\$</strong></span>. The + <span class="command"><strong>$</strong></span> may optionally be followed + by modifiers which change the offset from the + iterator, field width and base. + + Modifiers are introduced by a + <span class="command"><strong>{</strong></span> (left brace) immediately following the + <span class="command"><strong>$</strong></span> as + <span class="command"><strong>${offset[,width[,base]]}</strong></span>. + For example, <span class="command"><strong>${-20,3,d}</strong></span> + subtracts 20 from the current value, prints the + result as a decimal in a zero-padded field of + width 3. + + Available output forms are decimal + (<span class="command"><strong>d</strong></span>), octal + (<span class="command"><strong>o</strong></span>), hexadecimal + (<span class="command"><strong>x</strong></span> or <span class="command"><strong>X</strong></span> + for uppercase) and nibble + (<span class="command"><strong>n</strong></span> or <span class="command"><strong>N</strong></span>\ + for uppercase). The default modifier is + <span class="command"><strong>${0,0,d}</strong></span>. If the + <span class="command"><strong>lhs</strong></span> is not absolute, the + current <span class="command"><strong>$ORIGIN</strong></span> is appended + to the name. + </p> + <p> + In nibble mode the value will be treated as + if it was a reversed hexadecimal string + with each hexadecimal digit as a separate + label. The width field includes the label + separator. + </p> + <p> + For compatibility with earlier versions, + <span class="command"><strong>$$</strong></span> is still recognized as + indicating a literal $ in the output. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>ttl</strong></span></p> + </td> +<td> + <p> + Specifies the time-to-live of the generated records. If + not specified this will be inherited using the + normal TTL inheritance rules. + </p> + <p><span class="command"><strong>class</strong></span> + and <span class="command"><strong>ttl</strong></span> can be + entered in either order. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>class</strong></span></p> + </td> +<td> + <p> + Specifies the class of the generated records. + This must match the zone class if it is + specified. + </p> + <p><span class="command"><strong>class</strong></span> + and <span class="command"><strong>ttl</strong></span> can be + entered in either order. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>type</strong></span></p> + </td> +<td> + <p> + Any valid type. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>rhs</strong></span></p> + </td> +<td> + <p> + <span class="command"><strong>rhs</strong></span>, optionally, quoted string. + </p> + </td> +</tr> +</tbody> +</table> + </div> + <p> + The <span class="command"><strong>$GENERATE</strong></span> directive is a <acronym class="acronym">BIND</acronym> extension + and not part of the standard zone file format. + </p> + <p> + BIND 8 did not support the optional TTL and CLASS fields. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="zonefile_format"></a>Additional File Formats</h3></div></div></div> + + <p> + In addition to the standard textual format, BIND 9 + supports the ability to read or dump to zone files in + other formats. + </p> + <p> + The <code class="constant">raw</code> format is + a binary representation of zone data in a manner similar + to that used in zone transfers. Since it does not require + parsing text, load time is significantly reduced. + </p> + <p> + An even faster alternative is the <code class="constant">map</code> + format, which is an image of a <acronym class="acronym">BIND</acronym> 9 + in-memory zone database; it is capable of being loaded + directly into memory via the <span class="command"><strong>mmap()</strong></span> + function; the zone can begin serving queries almost + immediately. + </p> + <p> + For a primary server, a zone file in + <code class="constant">raw</code> or <code class="constant">map</code> + format is expected to be generated from a textual zone + file by the <span class="command"><strong>named-compilezone</strong></span> command. + For a secondary server or for a dynamic zone, it is automatically + generated (if this format is specified by the + <span class="command"><strong>masterfile-format</strong></span> option) when + <span class="command"><strong>named</strong></span> dumps the zone contents after + zone transfer or when applying prior updates. + </p> + <p> + If a zone file in a binary format needs manual modification, + it first must be converted to a textual form by the + <span class="command"><strong>named-compilezone</strong></span> command. All + necessary modification should go to the text file, which + should then be converted to the binary form by the + <span class="command"><strong>named-compilezone</strong></span> command again. + </p> + <p> + Note that <span class="command"><strong>map</strong></span> format is extremely + architecture-specific. A <code class="constant">map</code> + file <span class="emphasis"><em>cannot</em></span> be used on a system + with different pointer size, endianness or data alignment + than the system on which it was generated, and should in + general be used only inside a single system. + While <code class="constant">raw</code> format uses + network byte order and avoids architecture-dependent + data alignment so that it is as portable as + possible, it is also primarily expected to be used + inside the same single system. To export a + zone file in either <code class="constant">raw</code> or + <code class="constant">map</code> format, or make a + portable backup of such a file, conversion to + <code class="constant">text</code> format is recommended. + </p> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="statistics"></a>BIND9 Statistics</h2></div></div></div> + + <p> + <acronym class="acronym">BIND</acronym> 9 maintains lots of statistics + information and provides several interfaces for users to + get access to the statistics. + The available statistics include all statistics counters + that were available in <acronym class="acronym">BIND</acronym> 8 and + are meaningful in <acronym class="acronym">BIND</acronym> 9, + and other information that is considered useful. + </p> + + <p> + The statistics information is categorized into the following + sections. + </p> + + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="3.300in" class="1"> +<col width="2.625in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p>Incoming Requests</p> + </td> +<td> + <p> + The number of incoming DNS requests for each OPCODE. + </p> + </td> +</tr> +<tr> +<td> + <p>Incoming Queries</p> + </td> +<td> + <p> + The number of incoming queries for each RR type. + </p> + </td> +</tr> +<tr> +<td> + <p>Outgoing Queries</p> + </td> +<td> + <p> + The number of outgoing queries for each RR + type sent from the internal resolver. + Maintained per view. + </p> + </td> +</tr> +<tr> +<td> + <p>Name Server Statistics</p> + </td> +<td> + <p> + Statistics counters about incoming request processing. + </p> + </td> +</tr> +<tr> +<td> + <p>Zone Maintenance Statistics</p> + </td> +<td> + <p> + Statistics counters regarding zone maintenance + operations such as zone transfers. + </p> + </td> +</tr> +<tr> +<td> + <p>Resolver Statistics</p> + </td> +<td> + <p> + Statistics counters about name resolution + performed in the internal resolver. + Maintained per view. + </p> + </td> +</tr> +<tr> +<td> + <p>Cache DB RRsets</p> + </td> +<td> + <p> + The number of RRsets per RR type and nonexistent + names stored in the cache database. + If the exclamation mark (!) is printed for a RR + type, it means that particular type of RRset is + known to be nonexistent (this is also known as + "NXRRSET"). If a hash mark (#) is present then + the RRset is marked for garbage collection. + Maintained per view. + </p> + </td> +</tr> +<tr> +<td> + <p>Socket I/O Statistics</p> + </td> +<td> + <p> + Statistics counters about network related events. + </p> + </td> +</tr> +</tbody> +</table> + </div> + + <p> + A subset of Name Server Statistics is collected and shown + per zone for which the server has the authority when + <span class="command"><strong>zone-statistics</strong></span> is set to + <strong class="userinput"><code>full</code></strong> (or <strong class="userinput"><code>yes</code></strong> + for backward compatibility. See the description of + <span class="command"><strong>zone-statistics</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#options" title="options Statement Definition and Usage">the section called “<span class="command"><strong>options</strong></span> Statement Definition and + Usage”</a> + for further details. + </p> + + <p> + These statistics counters are shown with their zone and + view names. The view name is omitted when the server is + not configured with explicit views.</p> + + <p> + There are currently two user interfaces to get access to the + statistics. + One is in the plain text format dumped to the file specified + by the <span class="command"><strong>statistics-file</strong></span> configuration option. + The other is remotely accessible via a statistics channel + when the <span class="command"><strong>statistics-channels</strong></span> statement + is specified in the configuration file + (see <a class="xref" href="Bv9ARM.ch06.html#statschannels" title="statistics-channels Statement Grammar">the section called “<span class="command"><strong>statistics-channels</strong></span> Statement Grammar”</a>.) + </p> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="statsfile"></a>The Statistics File</h3></div></div></div> + + <p> + The text format statistics dump begins with a line, like: + </p> + <p> + <span class="command"><strong>+++ Statistics Dump +++ (973798949)</strong></span> + </p> + <p> + The number in parentheses is a standard + Unix-style timestamp, measured as seconds since January 1, 1970. + + Following + that line is a set of statistics information, which is categorized + as described above. + Each section begins with a line, like: + </p> + + <p> + <span class="command"><strong>++ Name Server Statistics ++</strong></span> + </p> + + <p> + Each section consists of lines, each containing the statistics + counter value followed by its textual description. + See below for available counters. + For brevity, counters that have a value of 0 are not shown + in the statistics file. + </p> + + <p> + The statistics dump ends with the line where the + number is identical to the number in the beginning line; for example: + </p> + <p> + <span class="command"><strong>--- Statistics Dump --- (973798949)</strong></span> + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="statistics_counters"></a>Statistics Counters</h3></div></div></div> + + <p> + The following tables summarize statistics counters that + <acronym class="acronym">BIND</acronym> 9 provides. + For each row of the tables, the leftmost column is the + abbreviated symbol name of that counter. + These symbols are shown in the statistics information + accessed via an HTTP statistics channel. + The rightmost column gives the description of the counter, + which is also shown in the statistics file + (but, in this document, possibly with slight modification + for better readability). + Additional notes may also be provided in this column. + When a middle column exists between these two columns, + it gives the corresponding counter name of the + <acronym class="acronym">BIND</acronym> 8 statistics, if applicable. + </p> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="stats_counters"></a>Name Server Statistics Counters</h4></div></div></div> + + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.150in" class="1"> +<col width="1.150in" class="2"> +<col width="3.350in" class="3"> +</colgroup> +<tbody> +<tr> +<td> + <p> + <span class="emphasis"><em>Symbol</em></span> + </p> + </td> +<td> + <p> + <span class="emphasis"><em>BIND8 Symbol</em></span> + </p> + </td> +<td> + <p> + <span class="emphasis"><em>Description</em></span> + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>Requestv4</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RQ</strong></span></p> + </td> +<td> + <p> + IPv4 requests received. + Note: this also counts non query requests. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>Requestv6</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RQ</strong></span></p> + </td> +<td> + <p> + IPv6 requests received. + Note: this also counts non query requests. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>ReqEdns0</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Requests with EDNS(0) received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>ReqBadEDNSVer</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Requests with unsupported EDNS version received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>ReqTSIG</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Requests with TSIG received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>ReqSIG0</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Requests with SIG(0) received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>ReqBadSIG</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Requests with invalid (TSIG or SIG(0)) signature. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>ReqTCP</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RTCP</strong></span></p> + </td> +<td> + <p> + TCP requests received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>AuthQryRej</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RUQ</strong></span></p> + </td> +<td> + <p> + Authoritative (non recursive) queries rejected. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>RecQryRej</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RURQ</strong></span></p> + </td> +<td> + <p> + Recursive queries rejected. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>XfrRej</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RUXFR</strong></span></p> + </td> +<td> + <p> + Zone transfer requests rejected. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>UpdateRej</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RUUpd</strong></span></p> + </td> +<td> + <p> + Dynamic update requests rejected. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>Response</strong></span></p> + </td> +<td> + <p><span class="command"><strong>SAns</strong></span></p> + </td> +<td> + <p> + Responses sent. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>RespTruncated</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Truncated responses sent. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>RespEDNS0</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Responses with EDNS(0) sent. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>RespTSIG</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Responses with TSIG sent. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>RespSIG0</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Responses with SIG(0) sent. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QrySuccess</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Queries resulted in a successful answer. + This means the query which returns a NOERROR response + with at least one answer RR. + This corresponds to the + <span class="command"><strong>success</strong></span> counter + of previous versions of + <acronym class="acronym">BIND</acronym> 9. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryAuthAns</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Queries resulted in authoritative answer. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryNoauthAns</strong></span></p> + </td> +<td> + <p><span class="command"><strong>SNaAns</strong></span></p> + </td> +<td> + <p> + Queries resulted in non authoritative answer. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryReferral</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Queries resulted in referral answer. + This corresponds to the + <span class="command"><strong>referral</strong></span> counter + of previous versions of + <acronym class="acronym">BIND</acronym> 9. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryNxrrset</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Queries resulted in NOERROR responses with no data. + This corresponds to the + <span class="command"><strong>nxrrset</strong></span> counter + of previous versions of + <acronym class="acronym">BIND</acronym> 9. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QrySERVFAIL</strong></span></p> + </td> +<td> + <p><span class="command"><strong>SFail</strong></span></p> + </td> +<td> + <p> + Queries resulted in SERVFAIL. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryFORMERR</strong></span></p> + </td> +<td> + <p><span class="command"><strong>SFErr</strong></span></p> + </td> +<td> + <p> + Queries resulted in FORMERR. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryNXDOMAIN</strong></span></p> + </td> +<td> + <p><span class="command"><strong>SNXD</strong></span></p> + </td> +<td> + <p> + Queries resulted in NXDOMAIN. + This corresponds to the + <span class="command"><strong>nxdomain</strong></span> counter + of previous versions of + <acronym class="acronym">BIND</acronym> 9. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryRecursion</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RFwdQ</strong></span></p> + </td> +<td> + <p> + Queries which caused the server + to perform recursion in order to find the final answer. + This corresponds to the + <span class="command"><strong>recursion</strong></span> counter + of previous versions of + <acronym class="acronym">BIND</acronym> 9. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryDuplicate</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RDupQ</strong></span></p> + </td> +<td> + <p> + Queries which the server attempted to + recurse but discovered an existing query with the same + IP address, port, query ID, name, type and class + already being processed. + This corresponds to the + <span class="command"><strong>duplicate</strong></span> counter + of previous versions of + <acronym class="acronym">BIND</acronym> 9. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryDropped</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Recursive queries for which the server + discovered an excessive number of existing + recursive queries for the same name, type and + class and were subsequently dropped. + This is the number of dropped queries due to + the reason explained with the + <span class="command"><strong>clients-per-query</strong></span> + and + <span class="command"><strong>max-clients-per-query</strong></span> + options + (see the description about + <a class="xref" href="Bv9ARM.ch06.html#clients-per-query"><span class="command"><strong>clients-per-query</strong></span></a>.) + This corresponds to the + <span class="command"><strong>dropped</strong></span> counter + of previous versions of + <acronym class="acronym">BIND</acronym> 9. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryFailure</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Other query failures. + This corresponds to the + <span class="command"><strong>failure</strong></span> counter + of previous versions of + <acronym class="acronym">BIND</acronym> 9. + Note: this counter is provided mainly for + backward compatibility with the previous versions. + Normally a more fine-grained counters such as + <span class="command"><strong>AuthQryRej</strong></span> and + <span class="command"><strong>RecQryRej</strong></span> + that would also fall into this counter are provided, + and so this counter would not be of much + interest in practice. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryNXRedir</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Queries resulted in NXDOMAIN that were redirected. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryNXRedirRLookup</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Queries resulted in NXDOMAIN that were redirected + and resulted in a successful remote lookup. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>XfrReqDone</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Requested zone transfers completed. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>UpdateReqFwd</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Update requests forwarded. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>UpdateRespFwd</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Update responses forwarded. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>UpdateFwdFail</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Dynamic update forward failed. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>UpdateDone</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Dynamic updates completed. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>UpdateFail</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Dynamic updates failed. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>UpdateBadPrereq</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Dynamic updates rejected due to prerequisite failure. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>RateDropped</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Responses dropped by rate limits. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>RateSlipped</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Responses truncated by rate limits. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>RPZRewrites</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Response policy zone rewrites. + </p> + </td> +</tr> +</tbody> +</table> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="zone_stats"></a>Zone Maintenance Statistics Counters</h4></div></div></div> + + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.150in" class="1"> +<col width="3.350in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p> + <span class="emphasis"><em>Symbol</em></span> + </p> + </td> +<td> + <p> + <span class="emphasis"><em>Description</em></span> + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>NotifyOutv4</strong></span></p> + </td> +<td> + <p> + IPv4 notifies sent. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>NotifyOutv6</strong></span></p> + </td> +<td> + <p> + IPv6 notifies sent. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>NotifyInv4</strong></span></p> + </td> +<td> + <p> + IPv4 notifies received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>NotifyInv6</strong></span></p> + </td> +<td> + <p> + IPv6 notifies received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>NotifyRej</strong></span></p> + </td> +<td> + <p> + Incoming notifies rejected. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>SOAOutv4</strong></span></p> + </td> +<td> + <p> + IPv4 SOA queries sent. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>SOAOutv6</strong></span></p> + </td> +<td> + <p> + IPv6 SOA queries sent. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>AXFRReqv4</strong></span></p> + </td> +<td> + <p> + IPv4 AXFR requested. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>AXFRReqv6</strong></span></p> + </td> +<td> + <p> + IPv6 AXFR requested. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>IXFRReqv4</strong></span></p> + </td> +<td> + <p> + IPv4 IXFR requested. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>IXFRReqv6</strong></span></p> + </td> +<td> + <p> + IPv6 IXFR requested. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>XfrSuccess</strong></span></p> + </td> +<td> + <p> + Zone transfer requests succeeded. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>XfrFail</strong></span></p> + </td> +<td> + <p> + Zone transfer requests failed. + </p> + </td> +</tr> +</tbody> +</table> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="resolver_stats"></a>Resolver Statistics Counters</h4></div></div></div> + + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.150in" class="1"> +<col width="1.150in" class="2"> +<col width="3.350in" class="3"> +</colgroup> +<tbody> +<tr> +<td> + <p> + <span class="emphasis"><em>Symbol</em></span> + </p> + </td> +<td> + <p> + <span class="emphasis"><em>BIND8 Symbol</em></span> + </p> + </td> +<td> + <p> + <span class="emphasis"><em>Description</em></span> + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>Queryv4</strong></span></p> + </td> +<td> + <p><span class="command"><strong>SFwdQ</strong></span></p> + </td> +<td> + <p> + IPv4 queries sent. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>Queryv6</strong></span></p> + </td> +<td> + <p><span class="command"><strong>SFwdQ</strong></span></p> + </td> +<td> + <p> + IPv6 queries sent. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>Responsev4</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RR</strong></span></p> + </td> +<td> + <p> + IPv4 responses received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>Responsev6</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RR</strong></span></p> + </td> +<td> + <p> + IPv6 responses received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>NXDOMAIN</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RNXD</strong></span></p> + </td> +<td> + <p> + NXDOMAIN received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>SERVFAIL</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RFail</strong></span></p> + </td> +<td> + <p> + SERVFAIL received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>FORMERR</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RFErr</strong></span></p> + </td> +<td> + <p> + FORMERR received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>OtherError</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RErr</strong></span></p> + </td> +<td> + <p> + Other errors received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>EDNS0Fail</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + EDNS(0) query failures. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>Mismatch</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RDupR</strong></span></p> + </td> +<td> + <p> + Mismatch responses received. + The DNS ID, response's source address, + and/or the response's source port does not + match what was expected. + (The port must be 53 or as defined by + the <span class="command"><strong>port</strong></span> option.) + This may be an indication of a cache + poisoning attempt. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>Truncated</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Truncated responses received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>Lame</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RLame</strong></span></p> + </td> +<td> + <p> + Lame delegations received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>Retry</strong></span></p> + </td> +<td> + <p><span class="command"><strong>SDupQ</strong></span></p> + </td> +<td> + <p> + Query retries performed. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QueryAbort</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Queries aborted due to quota control. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QuerySockFail</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Failures in opening query sockets. + One common reason for such failures is a + failure of opening a new socket due to a + limitation on file descriptors. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QueryTimeout</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Query timeouts. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>GlueFetchv4</strong></span></p> + </td> +<td> + <p><span class="command"><strong>SSysQ</strong></span></p> + </td> +<td> + <p> + IPv4 NS address fetches invoked. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>GlueFetchv6</strong></span></p> + </td> +<td> + <p><span class="command"><strong>SSysQ</strong></span></p> + </td> +<td> + <p> + IPv6 NS address fetches invoked. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>GlueFetchv4Fail</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + IPv4 NS address fetch failed. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>GlueFetchv6Fail</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + IPv6 NS address fetch failed. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>ValAttempt</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + DNSSEC validation attempted. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>ValOk</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + DNSSEC validation succeeded. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>ValNegOk</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + DNSSEC validation on negative information succeeded. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>ValFail</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + DNSSEC validation failed. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryRTTnn</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Frequency table on round trip times (RTTs) of + queries. + Each <span class="command"><strong>nn</strong></span> specifies the corresponding + frequency. + In the sequence of + <span class="command"><strong>nn_1</strong></span>, + <span class="command"><strong>nn_2</strong></span>, + ..., + <span class="command"><strong>nn_m</strong></span>, + the value of <span class="command"><strong>nn_i</strong></span> is the + number of queries whose RTTs are between + <span class="command"><strong>nn_(i-1)</strong></span> (inclusive) and + <span class="command"><strong>nn_i</strong></span> (exclusive) milliseconds. + For the sake of convenience we define + <span class="command"><strong>nn_0</strong></span> to be 0. + The last entry should be represented as + <span class="command"><strong>nn_m+</strong></span>, which means the + number of queries whose RTTs are equal to or over + <span class="command"><strong>nn_m</strong></span> milliseconds. + </p> + </td> +</tr> +</tbody> +</table> + </div> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="socket_stats"></a>Socket I/O Statistics Counters</h4></div></div></div> + + <p> + Socket I/O statistics counters are defined per socket + types, which are + <span class="command"><strong>UDP4</strong></span> (UDP/IPv4), + <span class="command"><strong>UDP6</strong></span> (UDP/IPv6), + <span class="command"><strong>TCP4</strong></span> (TCP/IPv4), + <span class="command"><strong>TCP6</strong></span> (TCP/IPv6), + <span class="command"><strong>Unix</strong></span> (Unix Domain), and + <span class="command"><strong>FDwatch</strong></span> (sockets opened outside the + socket module). + In the following table <span class="command"><strong><TYPE></strong></span> + represents a socket type. + Not all counters are available for all socket types; + exceptions are noted in the description field. + </p> + + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.150in" class="1"> +<col width="3.350in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p> + <span class="emphasis"><em>Symbol</em></span> + </p> + </td> +<td> + <p> + <span class="emphasis"><em>Description</em></span> + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong><TYPE>Open</strong></span></p> + </td> +<td> + <p> + Sockets opened successfully. + This counter is not applicable to the + <span class="command"><strong>FDwatch</strong></span> type. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong><TYPE>OpenFail</strong></span></p> + </td> +<td> + <p> + Failures of opening sockets. + This counter is not applicable to the + <span class="command"><strong>FDwatch</strong></span> type. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong><TYPE>Close</strong></span></p> + </td> +<td> + <p> + Sockets closed. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong><TYPE>BindFail</strong></span></p> + </td> +<td> + <p> + Failures of binding sockets. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong><TYPE>ConnFail</strong></span></p> + </td> +<td> + <p> + Failures of connecting sockets. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong><TYPE>Conn</strong></span></p> + </td> +<td> + <p> + Connections established successfully. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong><TYPE>AcceptFail</strong></span></p> + </td> +<td> + <p> + Failures of accepting incoming connection requests. + This counter is not applicable to the + <span class="command"><strong>UDP</strong></span> and + <span class="command"><strong>FDwatch</strong></span> types. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong><TYPE>Accept</strong></span></p> + </td> +<td> + <p> + Incoming connections successfully accepted. + This counter is not applicable to the + <span class="command"><strong>UDP</strong></span> and + <span class="command"><strong>FDwatch</strong></span> types. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong><TYPE>SendErr</strong></span></p> + </td> +<td> + <p> + Errors in socket send operations. + This counter corresponds + to <span class="command"><strong>SErr</strong></span> counter of + <span class="command"><strong>BIND</strong></span> 8. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong><TYPE>RecvErr</strong></span></p> + </td> +<td> + <p> + Errors in socket receive operations. + This includes errors of send operations on a + connected UDP socket notified by an ICMP error + message. + </p> + </td> +</tr> +</tbody> +</table> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="bind8_compatibility"></a>Compatibility with <span class="emphasis"><em>BIND</em></span> 8 Counters</h4></div></div></div> + + <p> + Most statistics counters that were available + in <span class="command"><strong>BIND</strong></span> 8 are also supported in + <span class="command"><strong>BIND</strong></span> 9 as shown in the above tables. + Here are notes about other counters that do not appear + in these tables. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>RFwdR,SFwdR</strong></span></span></dt> +<dd> + <p> + These counters are not supported + because <span class="command"><strong>BIND</strong></span> 9 does not adopt + the notion of <span class="emphasis"><em>forwarding</em></span> + as <span class="command"><strong>BIND</strong></span> 8 did. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>RAXFR</strong></span></span></dt> +<dd> + <p> + This counter is accessible in the Incoming Queries section. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>RIQ</strong></span></span></dt> +<dd> + <p> + This counter is accessible in the Incoming Requests section. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>ROpts</strong></span></span></dt> +<dd> + <p> + This counter is not supported + because <span class="command"><strong>BIND</strong></span> 9 does not care + about IP options in the first place. + </p> + </dd> +</dl></div> + </div> + </div> + </div> + + </div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="Bv9ARM.ch05.html">Prev</a> </td> +<td width="20%" align="center"> </td> +<td width="40%" align="right"> <a accesskey="n" href="Bv9ARM.ch07.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top">Chapter 5. The <acronym class="acronym">BIND</acronym> 9 Lightweight Resolver </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> Chapter 7. <acronym class="acronym">BIND</acronym> 9 Security Considerations</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/Bv9ARM.ch07.html b/doc/arm/Bv9ARM.ch07.html new file mode 100644 index 0000000..52c0ed9 --- /dev/null +++ b/doc/arm/Bv9ARM.ch07.html @@ -0,0 +1,404 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Chapter 7. BIND 9 Security Considerations</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="prev" href="Bv9ARM.ch06.html" title="Chapter 6. BIND 9 Configuration Reference"> +<link rel="next" href="Bv9ARM.ch08.html" title="Chapter 8. Troubleshooting"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center">Chapter 7. <acronym class="acronym">BIND</acronym> 9 Security Considerations</th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="Bv9ARM.ch06.html">Prev</a> </td> +<th width="60%" align="center"> </th> +<td width="20%" align="right"> <a accesskey="n" href="Bv9ARM.ch08.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="chapter"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="Bv9ARM.ch07"></a>Chapter 7. <acronym class="acronym">BIND</acronym> 9 Security Considerations</h1></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="Bv9ARM.ch07.html#Access_Control_Lists">Access Control Lists</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch07.html#chroot_and_setuid"><span class="command"><strong>Chroot</strong></span> and <span class="command"><strong>Setuid</strong></span></a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch07.html#chroot">The <span class="command"><strong>chroot</strong></span> Environment</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch07.html#setuid">Using the <span class="command"><strong>setuid</strong></span> Function</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch07.html#dynamic_update_security">Dynamic Update Security</a></span></dt> +</dl> +</div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="Access_Control_Lists"></a>Access Control Lists</h2></div></div></div> + + <p> + Access Control Lists (ACLs) are address match lists that + you can set up and nickname for future use in + <span class="command"><strong>allow-notify</strong></span>, <span class="command"><strong>allow-query</strong></span>, + <span class="command"><strong>allow-query-on</strong></span>, <span class="command"><strong>allow-recursion</strong></span>, + <span class="command"><strong>blackhole</strong></span>, <span class="command"><strong>allow-transfer</strong></span>, + <span class="command"><strong>match-clients</strong></span>, etc. + </p> + <p> + Using ACLs allows you to have finer control over who can access + your name server, without cluttering up your config files with huge + lists of IP addresses. + </p> + <p> + It is a <span class="emphasis"><em>good idea</em></span> to use ACLs, and to + control access to your server. Limiting access to your server by + outside parties can help prevent spoofing and denial of service + (DoS) attacks against your server. + </p> + <p> + ACLs match clients on the basis of up to three characteristics: + 1) The client's IP address; 2) the TSIG or SIG(0) key that was + used to sign the request, if any; and 3) an address prefix + encoded in an EDNS Client Subnet option, if any. + </p> + <p> + Here is an example of ACLs based on client addresses: + </p> + +<pre class="programlisting"> +// Set up an ACL named "bogusnets" that will block +// RFC1918 space and some reserved space, which is +// commonly used in spoofing attacks. +acl bogusnets { + 0.0.0.0/8; 192.0.2.0/24; 224.0.0.0/3; + 10.0.0.0/8; 172.16.0.0/12; 192.168.0.0/16; +}; + +// Set up an ACL called our-nets. Replace this with the +// real IP numbers. +acl our-nets { x.x.x.x/24; x.x.x.x/21; }; +options { + ... + ... + allow-query { our-nets; }; + allow-recursion { our-nets; }; + ... + blackhole { bogusnets; }; + ... +}; + +zone "example.com" { + type master; + file "m/example.com"; + allow-query { any; }; +}; +</pre> + + <p> + This allows authoritative queries for "example.com" from any + address, but recursive queries only from the networks specified + in "our-nets", and no queries at all from the networks + specified in "bogusnets". + </p> + <p> + In addition to network addresses and prefixes, which are + matched against the source address of the DNS request, ACLs + may include <code class="option">key</code> elements, which specify the + name of a TSIG or SIG(0) key, or <code class="option">ecs</code> + elements, which specify a network prefix but are only matched + if that prefix matches an EDNS client subnet option included + in the request. + </p> + <p> + The EDNS Client Subnet (ECS) option is used by a recursive + resolver to inform an authoritative name server of the network + address block from which the original query was received, enabling + authoritative servers to give different answers to the same + resolver for different resolver clients. An ACL containing + an element of the form + <span class="command"><strong>ecs <em class="replaceable"><code>prefix</code></em></strong></span> + will match if a request arrives in containing an ECS option + encoding an address within that prefix. If the request has no + ECS option, then "ecs" elements are simply ignored. Addresses + in ACLs that are not prefixed with "ecs" are matched only + against the source address. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + (Note: The authoritative ECS implementation in + <span class="command"><strong>named</strong></span> is based on an early version of the + specification, and is known to have incompatibilities with + other implementations. It is also inefficient, requiring + a separate view for each client subnet to be sent different + answers, and it is unable to correct for overlapping subnets in + the configuration. It can be used for testing purposes, but is + not recommended for production use.) + </p> + </div> + <p> + When <acronym class="acronym">BIND</acronym> 9 is built with GeoIP support, + ACLs can also be used for geographic access restrictions. + This is done by specifying an ACL element of the form: + <span class="command"><strong>geoip [<span class="optional">db <em class="replaceable"><code>database</code></em></span>] <em class="replaceable"><code>field</code></em> <em class="replaceable"><code>value</code></em></strong></span> + </p> + <p> + The <em class="replaceable"><code>field</code></em> indicates which field + to search for a match. Available fields are "country", + "region", "city", "continent", "postal" (postal code), + "metro" (metro code), "area" (area code), "tz" (timezone), + "isp", "org", "asnum", "domain" and "netspeed". + </p> + <p> + <em class="replaceable"><code>value</code></em> is the value to search + for within the database. A string may be quoted if it + contains spaces or other special characters. If this is + an "asnum" search, then the leading "ASNNNN" string can be + used, otherwise the full description must be used (e.g. + "ASNNNN Example Company Name"). If this is a "country" + search and the string is two characters long, then it must + be a standard ISO-3166-1 two-letter country code, and if it + is three characters long then it must be an ISO-3166-1 + three-letter country code; otherwise it is the full name + of the country. Similarly, if this is a "region" search + and the string is two characters long, then it must be a + standard two-letter state or province abbreviation; + otherwise it is the full name of the state or province. + </p> + <p> + The <em class="replaceable"><code>database</code></em> field indicates which + GeoIP database to search for a match. In most cases this is + unnecessary, because most search fields can only be found in + a single database. However, searches for country can be + answered from the "city", "region", or "country" databases, + and searches for region (i.e., state or province) can be + answered from the "city" or "region" databases. For these + search types, specifying a <em class="replaceable"><code>database</code></em> + will force the query to be answered from that database and no + other. If <em class="replaceable"><code>database</code></em> is not + specified, then these queries will be answered from the "city", + database if it is installed, or the "region" database if it is + installed, or the "country" database, in that order. + </p> + <p> + By default, if a DNS query includes an EDNS Client Subnet (ECS) + option which encodes a non-zero address prefix, then GeoIP ACLs + will be matched against that address prefix. Otherwise, they + are matched against the source address of the query. To + prevent GeoIP ACLs from matching against ECS options, set + the <span class="command"><strong>geoip-use-ecs</strong></span> to <code class="literal">no</code>. + </p> + <p> + Some example GeoIP ACLs: + </p> + <pre class="programlisting">geoip country US; +geoip country JAP; +geoip db country country Canada; +geoip db region region WA; +geoip city "San Francisco"; +geoip region Oklahoma; +geoip postal 95062; +geoip tz "America/Los_Angeles"; +geoip org "Internet Systems Consortium"; +</pre> + + <p> + ACLs use a "first-match" logic rather than "best-match": + if an address prefix matches an ACL element, then that ACL + is considered to have matched even if a later element would + have matched more specifically. For example, the ACL + <span class="command"><strong> { 10/8; !10.0.0.1; }</strong></span> would actually + match a query from 10.0.0.1, because the first element + indicated that the query should be accepted, and the second + element is ignored. + </p> + <p> + When using "nested" ACLs (that is, ACLs included or referenced + within other ACLs), a negative match of a nested ACL will + the containing ACL to continue looking for matches. This + enables complex ACLs to be constructed, in which multiple + client characteristics can be checked at the same time. For + example, to construct an ACL which allows queries only when + it originates from a particular network <span class="emphasis"><em>and</em></span> + only when it is signed with a particular key, use: + </p> + <pre class="programlisting"> +allow-query { !{ !10/8; any; }; key example; }; +</pre> + <p> + Within the nested ACL, any address that is + <span class="emphasis"><em>not</em></span> in the 10/8 network prefix will + be rejected, and this will terminate processing of the + ACL. Any address that <span class="emphasis"><em>is</em></span> in the 10/8 + network prefix will be accepted, but this causes a negative + match of the nested ACL, so the containing ACL continues + processing. The query will then be accepted if it is signed + by the key "example", and rejected otherwise. The ACL, then, + will only matches when <span class="emphasis"><em>both</em></span> conditions + are true. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="chroot_and_setuid"></a><span class="command"><strong>Chroot</strong></span> and <span class="command"><strong>Setuid</strong></span> +</h2></div></div></div> + + <p> + On UNIX servers, it is possible to run <acronym class="acronym">BIND</acronym> + in a <span class="emphasis"><em>chrooted</em></span> environment (using + the <span class="command"><strong>chroot()</strong></span> function) by specifying + the <code class="option">-t</code> option for <span class="command"><strong>named</strong></span>. + This can help improve system security by placing + <acronym class="acronym">BIND</acronym> in a "sandbox", which will limit + the damage done if a server is compromised. + </p> + <p> + Another useful feature in the UNIX version of <acronym class="acronym">BIND</acronym> is the + ability to run the daemon as an unprivileged user ( <code class="option">-u</code> <em class="replaceable"><code>user</code></em> ). + We suggest running as an unprivileged user when using the <span class="command"><strong>chroot</strong></span> feature. + </p> + <p> + Here is an example command line to load <acronym class="acronym">BIND</acronym> in a <span class="command"><strong>chroot</strong></span> sandbox, + <span class="command"><strong>/var/named</strong></span>, and to run <span class="command"><strong>named</strong></span> <span class="command"><strong>setuid</strong></span> to + user 202: + </p> + <p> + <strong class="userinput"><code>/usr/local/sbin/named -u 202 -t /var/named</code></strong> + </p> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="chroot"></a>The <span class="command"><strong>chroot</strong></span> Environment</h3></div></div></div> + + <p> + In order for a <span class="command"><strong>chroot</strong></span> environment + to work properly in a particular directory (for example, + <code class="filename">/var/named</code>), you will need to set + up an environment that includes everything + <acronym class="acronym">BIND</acronym> needs to run. From + <acronym class="acronym">BIND</acronym>'s point of view, + <code class="filename">/var/named</code> is the root of the + filesystem. You will need to adjust the values of + options like <span class="command"><strong>directory</strong></span> and + <span class="command"><strong>pid-file</strong></span> to account for this. + </p> + <p> + Unlike with earlier versions of BIND, you typically will + <span class="emphasis"><em>not</em></span> need to compile <span class="command"><strong>named</strong></span> + statically nor install shared libraries under the new root. + However, depending on your operating system, you may need + to set up things like + <code class="filename">/dev/zero</code>, + <code class="filename">/dev/random</code>, + <code class="filename">/dev/log</code>, and + <code class="filename">/etc/localtime</code>. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="setuid"></a>Using the <span class="command"><strong>setuid</strong></span> Function</h3></div></div></div> + + <p> + Prior to running the <span class="command"><strong>named</strong></span> daemon, + use + the <span class="command"><strong>touch</strong></span> utility (to change file + access and + modification times) or the <span class="command"><strong>chown</strong></span> + utility (to + set the user id and/or group id) on files + to which you want <acronym class="acronym">BIND</acronym> + to write. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> +<p> + If the <span class="command"><strong>named</strong></span> daemon is running as an + unprivileged user, it will not be able to bind to new restricted + ports if the server is reloaded. + </p> +</div> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="dynamic_update_security"></a>Dynamic Update Security</h2></div></div></div> + + <p> + Access to the dynamic + update facility should be strictly limited. In earlier versions of + <acronym class="acronym">BIND</acronym>, the only way to do this was + based on the IP + address of the host requesting the update, by listing an IP address + or + network prefix in the <span class="command"><strong>allow-update</strong></span> + zone option. + This method is insecure since the source address of the update UDP + packet + is easily forged. Also note that if the IP addresses allowed by the + <span class="command"><strong>allow-update</strong></span> option include the + address of a slave + server which performs forwarding of dynamic updates, the master can + be + trivially attacked by sending the update to the slave, which will + forward it to the master with its own source IP address causing the + master to approve it without question. + </p> + + <p> + For these reasons, we strongly recommend that updates be + cryptographically authenticated by means of transaction signatures + (TSIG). That is, the <span class="command"><strong>allow-update</strong></span> + option should + list only TSIG key names, not IP addresses or network + prefixes. Alternatively, the new <span class="command"><strong>update-policy</strong></span> + option can be used. + </p> + + <p> + Some sites choose to keep all dynamically-updated DNS data + in a subdomain and delegate that subdomain to a separate zone. This + way, the top-level zone containing critical data such as the IP + addresses + of public web and mail servers need not allow dynamic update at + all. + </p> + + </div> + </div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="Bv9ARM.ch06.html">Prev</a> </td> +<td width="20%" align="center"> </td> +<td width="40%" align="right"> <a accesskey="n" href="Bv9ARM.ch08.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top">Chapter 6. <acronym class="acronym">BIND</acronym> 9 Configuration Reference </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> Chapter 8. Troubleshooting</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/Bv9ARM.ch08.html b/doc/arm/Bv9ARM.ch08.html new file mode 100644 index 0000000..12fdb8e --- /dev/null +++ b/doc/arm/Bv9ARM.ch08.html @@ -0,0 +1,141 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Chapter 8. Troubleshooting</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="prev" href="Bv9ARM.ch07.html" title="Chapter 7. BIND 9 Security Considerations"> +<link rel="next" href="Bv9ARM.ch09.html" title="Appendix A. Release Notes"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center">Chapter 8. Troubleshooting</th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="Bv9ARM.ch07.html">Prev</a> </td> +<th width="60%" align="center"> </th> +<td width="20%" align="right"> <a accesskey="n" href="Bv9ARM.ch09.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="chapter"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="Bv9ARM.ch08"></a>Chapter 8. Troubleshooting</h1></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="Bv9ARM.ch08.html#common_problems">Common Problems</a></span></dt> +<dd><dl><dt><span class="section"><a href="Bv9ARM.ch08.html#id-1.9.2.2">It's not working; how can I figure out what's wrong?</a></span></dt></dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch08.html#id-1.9.3">Incrementing and Changing the Serial Number</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch08.html#more_help">Where Can I Get Help?</a></span></dt> +</dl> +</div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="common_problems"></a>Common Problems</h2></div></div></div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.9.2.2"></a>It's not working; how can I figure out what's wrong?</h3></div></div></div> + + <p> + The best solution to solving installation and + configuration issues is to take preventative measures by setting + up logging files beforehand. The log files provide a + source of hints and information that can be used to figure out + what went wrong and how to fix the problem. + </p> + + </div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="id-1.9.3"></a>Incrementing and Changing the Serial Number</h2></div></div></div> + + <p> + Zone serial numbers are just numbers — they aren't + date related. A lot of people set them to a number that + represents a date, usually of the form YYYYMMDDRR. + Occasionally they will make a mistake and set them to a + "date in the future" then try to correct them by setting + them to the "current date". This causes problems because + serial numbers are used to indicate that a zone has been + updated. If the serial number on the slave server is + lower than the serial number on the master, the slave + server will attempt to update its copy of the zone. + </p> + + <p> + Setting the serial number to a lower number on the master + server than the slave server means that the slave will not perform + updates to its copy of the zone. + </p> + + <p> + The solution to this is to add 2147483647 (2^31-1) to the + number, reload the zone and make sure all slaves have updated to + the new zone serial number, then reset the number to what you want + it to be, and reload the zone again. + </p> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="more_help"></a>Where Can I Get Help?</h2></div></div></div> + + <p> + The Internet Systems Consortium + (<acronym class="acronym">ISC</acronym>) offers a wide range + of support and service agreements for <acronym class="acronym">BIND</acronym> and <acronym class="acronym">DHCP</acronym> servers. Four + levels of premium support are available and each level includes + support for all <acronym class="acronym">ISC</acronym> programs, + significant discounts on products + and training, and a recognized priority on bug fixes and + non-funded feature requests. In addition, <acronym class="acronym">ISC</acronym> offers a standard + support agreement package which includes services ranging from bug + fix announcements to remote support. It also includes training in + <acronym class="acronym">BIND</acronym> and <acronym class="acronym">DHCP</acronym>. + </p> + + <p> + To discuss arrangements for support, contact + <a class="link" href="mailto:info@isc.org" target="_top">info@isc.org</a> or visit the + <acronym class="acronym">ISC</acronym> web page at + <a class="link" href="http://www.isc.org/services/support/" target="_top">http://www.isc.org/services/support/</a> + to read more. + </p> + </div> + </div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="Bv9ARM.ch07.html">Prev</a> </td> +<td width="20%" align="center"> </td> +<td width="40%" align="right"> <a accesskey="n" href="Bv9ARM.ch09.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top">Chapter 7. <acronym class="acronym">BIND</acronym> 9 Security Considerations </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> Appendix A. Release Notes</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/Bv9ARM.ch09.html b/doc/arm/Bv9ARM.ch09.html new file mode 100644 index 0000000..49a6454 --- /dev/null +++ b/doc/arm/Bv9ARM.ch09.html @@ -0,0 +1,350 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Appendix A. Release Notes</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="prev" href="Bv9ARM.ch08.html" title="Chapter 8. Troubleshooting"> +<link rel="next" href="Bv9ARM.ch10.html" title="Appendix B. A Brief History of the DNS and BIND"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center">Appendix A. Release Notes</th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="Bv9ARM.ch08.html">Prev</a> </td> +<th width="60%" align="center"> </th> +<td width="20%" align="right"> <a accesskey="n" href="Bv9ARM.ch10.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="appendix"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="Bv9ARM.ch09"></a>Release Notes</h1></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="Bv9ARM.ch09.html#id-1.10.2">Release Notes for BIND Version 9.11.5-P4</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch09.html#relnotes_intro">Introduction</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch09.html#relnotes_download">Download</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch09.html#relnotes_license">License Change</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch09.html#win_support">Legacy Windows No Longer Supported</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch09.html#relnotes_security">Security Fixes</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch09.html#relnotes_features">New Features</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch09.html#relnotes_removed">Removed Features</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch09.html#relnotes_changes">Feature Changes</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch09.html#relnotes_bugs">Bug Fixes</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch09.html#end_of_life">End of Life</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch09.html#relnotes_thanks">Thank You</a></span></dt> +</dl></dd> +</dl> +</div> + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="id-1.10.2"></a>Release Notes for BIND Version 9.11.5-P4</h2></div></div></div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="relnotes_intro"></a>Introduction</h3></div></div></div> + <p> + This document summarizes changes since the last production + release on the BIND 9.11 (Extended Support Version) branch. + Please see the <code class="filename">CHANGES</code> file for a further + list of bug fixes and other changes. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="relnotes_download"></a>Download</h3></div></div></div> + <p> + The latest versions of BIND 9 software can always be found at + <a class="link" href="http://www.isc.org/downloads/" target="_top">http://www.isc.org/downloads/</a>. + There you will find additional information about each release, + source code, and pre-compiled versions for Microsoft Windows + operating systems. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="relnotes_license"></a>License Change</h3></div></div></div> + <p> + With the release of BIND 9.11.0, ISC changed to the open + source license for BIND from the ISC license to the Mozilla + Public License (MPL 2.0). + </p> + <p> + The MPL-2.0 license requires that if you make changes to + licensed software (e.g. BIND) and distribute them outside + your organization, that you publish those changes under that + same license. It does not require that you publish or disclose + anything other than the changes you made to our software. + </p> + <p> + This requirement will not affect anyone who is using BIND, with + or without modifications, without redistributing it, nor anyone + redistributing it without changes. Therefore, this change will be + without consequence for most individuals and organizations who are + using BIND. + </p> + <p> + Those unsure whether or not the license change affects their + use of BIND, or who wish to discuss how to comply with the + license may contact ISC at <a class="link" href="https://www.isc.org/mission/contact/" target="_top"> + https://www.isc.org/mission/contact/</a>. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="win_support"></a>Legacy Windows No Longer Supported</h3></div></div></div> + <p> + As of BIND 9.11.2, Windows XP and Windows 2003 are no longer supported + platforms for BIND; "XP" binaries are no longer available for download + from ISC. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="relnotes_security"></a>Security Fixes</h3></div></div></div> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <p> + <span class="command"><strong>named</strong></span> could crash during recursive processing + of DNAME records when <span class="command"><strong>deny-answer-aliases</strong></span> was + in use. This flaw is disclosed in CVE-2018-5740. [GL #387] + </p> + </li> +<li class="listitem"> + <p> + When recursion is enabled but the <span class="command"><strong>allow-recursion</strong></span> + and <span class="command"><strong>allow-query-cache</strong></span> ACLs are not specified, they + should be limited to local networks, but they were inadvertently set + to match the default <span class="command"><strong>allow-query</strong></span>, thus allowing + remote queries. This flaw is disclosed in CVE-2018-5738. [GL #309] + </p> + </li> +<li class="listitem"> + <p> + Code change #4964, intended to prevent double signatures + when deleting an inactive zone DNSKEY in some situations, + introduced a new problem during zone processing in which + some delegation glue RRsets are incorrectly identified + as needing RRSIGs, which are then created for them using + the current active ZSK for the zone. In some, but not all + cases, the newly-signed RRsets are added to the zone's + NSEC/NSEC3 chain, but incompletely -- this can result in + a broken chain, affecting validation of proof of nonexistence + for records in the zone. [GL #771] + </p> + </li> +<li class="listitem"> + <p> + <span class="command"><strong>named</strong></span> could crash if it managed a DNSSEC + security root with <span class="command"><strong>managed-keys</strong></span> and the + authoritative zone rolled the key to an algorithm not supported + by BIND 9. This flaw is disclosed in CVE-2018-5745. [GL #780] + </p> + </li> +<li class="listitem"> + <p> + <span class="command"><strong>named</strong></span> leaked memory when processing a + request with multiple Key Tag EDNS options present. ISC + would like to thank Toshifumi Sakaguchi for bringing this + to our attention. This flaw is disclosed in CVE-2018-5744. + [GL #772] + </p> + </li> +<li class="listitem"> + <p> + Zone transfer controls for writable DLZ zones were not + effective as the <span class="command"><strong>allowzonexfr</strong></span> method was + not being called for such zones. This flaw is disclosed in + CVE-2019-6465. [GL #790] + </p> + </li> +</ul></div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="relnotes_features"></a>New Features</h3></div></div></div> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <p> + <span class="command"><strong>named</strong></span> now supports the "root key sentinel" + mechanism. This enables validating resolvers to indicate + which trust anchors are configured for the root, so that + information about root key rollover status can be gathered. + To disable this feature, add + <span class="command"><strong>root-key-sentinel no;</strong></span> to + <code class="filename">named.conf</code>. + </p> + </li> +<li class="listitem"> + <p> + Added the ability not to return a DNS COOKIE option when one + is present in the request. To prevent a cookie being returned, + add <span class="command"><strong>answer-cookie no;</strong></span> to + <code class="filename">named.conf</code>. [GL #173] + </p> + <p> + <span class="command"><strong>answer-cookie no</strong></span> is only intended as a + temporary measure, for use when <span class="command"><strong>named</strong></span> + shares an IP address with other servers that do not yet + support DNS COOKIE. A mismatch between servers on the + same address is not expected to cause operational problems, + but the option to disable COOKIE responses so that all + servers have the same behavior is provided out of an + abundance of caution. DNS COOKIE is an important security + mechanism, and should not be disabled unless absolutely + necessary. + </p> + </li> +<li class="listitem"> + <p> + Two new update policy rule types have been added + <span class="command"><strong>krb5-selfsub</strong></span> and <span class="command"><strong>ms-selfsub</strong></span> + which allow machines with Kerberos principals to update + the name space at or below the machine names identified + in the respective principals. + </p> + </li> +</ul></div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="relnotes_removed"></a>Removed Features</h3></div></div></div> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> + <span class="command"><strong>named</strong></span> will now log a warning if the old + BIND now can be compiled against libidn2 library to add + IDNA2008 support. Previously BIND only supported IDNA2003 + using (now obsolete) idnkit-1 library. + </p> + </li></ul></div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="relnotes_changes"></a>Feature Changes</h3></div></div></div> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <p> + <span class="command"><strong>dig +noidnin</strong></span> can be used to disable IDN + processing on the input domain name, when BIND is compiled + with IDN support. + </p> + </li> +<li class="listitem"> + <p> + Multiple <span class="command"><strong>cookie-secret</strong></span> clause are now + supported. The first <span class="command"><strong>cookie-secret</strong></span> in + <code class="filename">named.conf</code> is used to generate new + server cookies. Any others are used to accept old server + cookies or those generated by other servers using the + matching <span class="command"><strong>cookie-secret</strong></span>. + </p> + </li> +<li class="listitem"> + <p> + The <span class="command"><strong>rndc nta</strong></span> command could not differentiate + between views of the same name but different class; this + has been corrected with the addition of a <span class="command"><strong>-class</strong></span> + option. [GL #105] + </p> + </li> +</ul></div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="relnotes_bugs"></a>Bug Fixes</h3></div></div></div> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <p> + When a negative trust anchor was added to multiple views + using <span class="command"><strong>rndc nta</strong></span>, the text returned via + <span class="command"><strong>rndc</strong></span> was incorrectly truncated after the + first line, making it appear that only one NTA had been + added. This has been fixed. [GL #105] + </p> + </li> +<li class="listitem"> + <p> + <span class="command"><strong>named</strong></span> now rejects excessively large + incremental (IXFR) zone transfers in order to prevent + possible corruption of journal files which could cause + <span class="command"><strong>named</strong></span> to abort when loading zones. [GL #339] + </p> + </li> +<li class="listitem"> + <p> + <span class="command"><strong>rndc reload</strong></span> could cause <span class="command"><strong>named</strong></span> + to leak memory if it was invoked before the zone loading actions + from a previous <span class="command"><strong>rndc reload</strong></span> command were + completed. [RT #47076] + </p> + </li> +</ul></div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="end_of_life"></a>End of Life</h3></div></div></div> + <p> + BIND 9.11 (Extended Support Version) will be supported until at + least December, 2021. + See <a class="link" href="https://www.isc.org/downloads/software-support-policy/" target="_top">https://www.isc.org/downloads/software-support-policy/</a> for details of ISC's software support policy. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="relnotes_thanks"></a>Thank You</h3></div></div></div> + + <p> + Thank you to everyone who assisted us in making this release possible. + If you would like to contribute to ISC to assist us in continuing to + make quality open source software, please visit our donations page at + <a class="link" href="http://www.isc.org/donate/" target="_top">http://www.isc.org/donate/</a>. + </p> + </div> +</div> + </div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="Bv9ARM.ch08.html">Prev</a> </td> +<td width="20%" align="center"> </td> +<td width="40%" align="right"> <a accesskey="n" href="Bv9ARM.ch10.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top">Chapter 8. Troubleshooting </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> Appendix B. A Brief History of the <acronym class="acronym">DNS</acronym> and <acronym class="acronym">BIND</acronym> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/Bv9ARM.ch10.html b/doc/arm/Bv9ARM.ch10.html new file mode 100644 index 0000000..45ffcf8 --- /dev/null +++ b/doc/arm/Bv9ARM.ch10.html @@ -0,0 +1,153 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Appendix B. A Brief History of the DNS and BIND</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="prev" href="Bv9ARM.ch09.html" title="Appendix A. Release Notes"> +<link rel="next" href="Bv9ARM.ch11.html" title="Appendix C. General DNS Reference Information"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center">Appendix B. A Brief History of the <acronym class="acronym">DNS</acronym> and <acronym class="acronym">BIND</acronym> +</th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="Bv9ARM.ch09.html">Prev</a> </td> +<th width="60%" align="center"> </th> +<td width="20%" align="right"> <a accesskey="n" href="Bv9ARM.ch11.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="appendix"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="Bv9ARM.ch10"></a>A Brief History of the <acronym class="acronym">DNS</acronym> and <acronym class="acronym">BIND</acronym> +</h1></div></div></div> + <p><a name="historical_dns_information"></a> + Although the "official" beginning of the Domain Name + System occurred in 1984 with the publication of RFC 920, the + core of the new system was described in 1983 in RFCs 882 and + 883. From 1984 to 1987, the ARPAnet (the precursor to today's + Internet) became a testbed of experimentation for developing the + new naming/addressing scheme in a rapidly expanding, + operational network environment. New RFCs were written and + published in 1987 that modified the original documents to + incorporate improvements based on the working model. RFC 1034, + "Domain Names-Concepts and Facilities", and RFC 1035, "Domain + Names-Implementation and Specification" were published and + became the standards upon which all <acronym class="acronym">DNS</acronym> implementations are + built. + </p> + + <p> + The first working domain name server, called "Jeeves", was + written in 1983-84 by Paul Mockapetris for operation on DEC + Tops-20 + machines located at the University of Southern California's + Information + Sciences Institute (USC-ISI) and SRI International's Network + Information + Center (SRI-NIC). A <acronym class="acronym">DNS</acronym> server for + Unix machines, the Berkeley Internet + Name Domain (<acronym class="acronym">BIND</acronym>) package, was + written soon after by a group of + graduate students at the University of California at Berkeley + under + a grant from the US Defense Advanced Research Projects + Administration + (DARPA). + </p> + <p> + Versions of <acronym class="acronym">BIND</acronym> through + 4.8.3 were maintained by the Computer + Systems Research Group (CSRG) at UC Berkeley. Douglas Terry, Mark + Painter, David Riggle and Songnian Zhou made up the initial <acronym class="acronym">BIND</acronym> + project team. After that, additional work on the software package + was done by Ralph Campbell. Kevin Dunlap, a Digital Equipment + Corporation + employee on loan to the CSRG, worked on <acronym class="acronym">BIND</acronym> for 2 years, from 1985 + to 1987. Many other people also contributed to <acronym class="acronym">BIND</acronym> development + during that time: Doug Kingston, Craig Partridge, Smoot + Carl-Mitchell, + Mike Muuss, Jim Bloom and Mike Schwartz. <acronym class="acronym">BIND</acronym> maintenance was subsequently + handled by Mike Karels and Øivind Kure. + </p> + <p> + <acronym class="acronym">BIND</acronym> versions 4.9 and 4.9.1 were + released by Digital Equipment + Corporation (now Compaq Computer Corporation). Paul Vixie, then + a DEC employee, became <acronym class="acronym">BIND</acronym>'s + primary caretaker. He was assisted + by Phil Almquist, Robert Elz, Alan Barrett, Paul Albitz, Bryan + Beecher, Andrew + Partan, Andy Cherenson, Tom Limoncelli, Berthold Paffrath, Fuat + Baran, Anant Kumar, Art Harkin, Win Treese, Don Lewis, Christophe + Wolfhugel, and others. + </p> + <p> + In 1994, <acronym class="acronym">BIND</acronym> version 4.9.2 was sponsored by + Vixie Enterprises. Paul + Vixie became <acronym class="acronym">BIND</acronym>'s principal + architect/programmer. + </p> + <p> + <acronym class="acronym">BIND</acronym> versions from 4.9.3 onward + have been developed and maintained + by the Internet Systems Consortium and its predecessor, + the Internet Software Consortium, with support being provided + by ISC's sponsors. + </p> + <p> + As co-architects/programmers, Bob Halley and + Paul Vixie released the first production-ready version of + <acronym class="acronym">BIND</acronym> version 8 in May 1997. + </p> + <p> + BIND version 9 was released in September 2000 and is a + major rewrite of nearly all aspects of the underlying + BIND architecture. + </p> + <p> + BIND versions 4 and 8 are officially deprecated. + No additional development is done + on BIND version 4 or BIND version 8. + </p> + <p> + <acronym class="acronym">BIND</acronym> development work is made + possible today by the sponsorship + of several corporations, and by the tireless work efforts of + numerous individuals. + </p> + </div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="Bv9ARM.ch09.html">Prev</a> </td> +<td width="20%" align="center"> </td> +<td width="40%" align="right"> <a accesskey="n" href="Bv9ARM.ch11.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top">Appendix A. Release Notes </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> Appendix C. General <acronym class="acronym">DNS</acronym> Reference Information</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/Bv9ARM.ch11.html b/doc/arm/Bv9ARM.ch11.html new file mode 100644 index 0000000..3215910 --- /dev/null +++ b/doc/arm/Bv9ARM.ch11.html @@ -0,0 +1,919 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Appendix C. General DNS Reference Information</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="prev" href="Bv9ARM.ch10.html" title="Appendix B. A Brief History of the DNS and BIND"> +<link rel="next" href="Bv9ARM.ch12.html" title="Appendix D. BIND 9 DNS Library Support"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center">Appendix C. General <acronym class="acronym">DNS</acronym> Reference Information</th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="Bv9ARM.ch10.html">Prev</a> </td> +<th width="60%" align="center"> </th> +<td width="20%" align="right"> <a accesskey="n" href="Bv9ARM.ch12.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="appendix"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="Bv9ARM.ch11"></a>General <acronym class="acronym">DNS</acronym> Reference Information</h1></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="Bv9ARM.ch11.html#ipv6addresses">IPv6 addresses (AAAA)</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch11.html#bibliography">Bibliography (and Suggested Reading)</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch11.html#rfcs">Request for Comments (RFCs)</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch11.html#internet_drafts">Internet Drafts</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch11.html#more_about_bind">Other Documents About <acronym class="acronym">BIND</acronym></a></span></dt> +</dl></dd> +</dl> +</div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ipv6addresses"></a>IPv6 addresses (AAAA)</h2></div></div></div> + + <p> + IPv6 addresses are 128-bit identifiers for interfaces and + sets of interfaces which were introduced in the <acronym class="acronym">DNS</acronym> to facilitate + scalable Internet routing. There are three types of addresses: <span class="emphasis"><em>Unicast</em></span>, + an identifier for a single interface; + <span class="emphasis"><em>Anycast</em></span>, + an identifier for a set of interfaces; and <span class="emphasis"><em>Multicast</em></span>, + an identifier for a set of interfaces. Here we describe the global + Unicast address scheme. For more information, see RFC 3587, + "Global Unicast Address Format." + </p> + <p> + IPv6 unicast addresses consist of a + <span class="emphasis"><em>global routing prefix</em></span>, a + <span class="emphasis"><em>subnet identifier</em></span>, and an + <span class="emphasis"><em>interface identifier</em></span>. + </p> + <p> + The global routing prefix is provided by the + upstream provider or ISP, and (roughly) corresponds to the + IPv4 <span class="emphasis"><em>network</em></span> section + of the address range. + + The subnet identifier is for local subnetting, much the + same as subnetting an + IPv4 /16 network into /24 subnets. + + The interface identifier is the address of an individual + interface on a given network; in IPv6, addresses belong to + interfaces rather than to machines. + </p> + <p> + The subnetting capability of IPv6 is much more flexible than + that of IPv4: subnetting can be carried out on bit boundaries, + in much the same way as Classless InterDomain Routing + (CIDR), and the DNS PTR representation ("nibble" format) + makes setting up reverse zones easier. + </p> + <p> + The Interface Identifier must be unique on the local link, + and is usually generated automatically by the IPv6 + implementation, although it is usually possible to + override the default setting if necessary. A typical IPv6 + address might look like: + <span class="command"><strong>2001:db8:201:9:a00:20ff:fe81:2b32</strong></span> + </p> + <p> + IPv6 address specifications often contain long strings + of zeros, so the architects have included a shorthand for + specifying + them. The double colon (`::') indicates the longest possible + string + of zeros that can fit, and can be used only once in an address. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="bibliography"></a>Bibliography (and Suggested Reading)</h2></div></div></div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="rfcs"></a>Request for Comments (RFCs)</h3></div></div></div> + + <p> + Specification documents for the Internet protocol suite, including + the <acronym class="acronym">DNS</acronym>, are published as part of + the Request for Comments (RFCs) + series of technical notes. The standards themselves are defined + by the Internet Engineering Task Force (IETF) and the Internet + Engineering Steering Group (IESG). RFCs can be obtained online via FTP at: + </p> + <p> + <a class="link" href="ftp://www.isi.edu/in-notes/" target="_top"> + ftp://www.isi.edu/in-notes/RFC<em class="replaceable"><code>xxxx</code></em>.txt + </a> + </p> + <p> + (where <em class="replaceable"><code>xxxx</code></em> is + the number of the RFC). RFCs are also available via the Web at: + </p> + <p> + <a class="link" href="http://www.ietf.org/rfc/" target="_top">http://www.ietf.org/rfc/</a>. + </p> + <div class="bibliography"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.12.3.2.6"></a>Bibliography</h4></div></div></div> + <div class="bibliodiv"> + + + <div class="biblioentry"> +<a name="id-1.12.3.2.6.1.2"></a><p>[<abbr class="abbrev">RFC974</abbr>] + + <span class="author"><span class="firstname">C.</span> <span class="surname">Partridge</span>. </span> + <span class="citetitle"><em class="citetitle">Mail Routing and the Domain System</em>. </span> + <span class="pubdate">January 1986. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.1.3"></a><p>[<abbr class="abbrev">RFC1034</abbr>] + + <span class="author"><span class="firstname">P.V.</span> <span class="surname">Mockapetris</span>. </span> + <span class="citetitle"><em class="citetitle">Domain Names — Concepts and Facilities</em>. </span> + <span class="pubdate">November 1987. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.1.4"></a><p>[<abbr class="abbrev">RFC1035</abbr>] + + <span class="author"><span class="firstname">P. V.</span> <span class="surname">Mockapetris</span>. </span> <span class="citetitle"><em class="citetitle">Domain Names — Implementation and + Specification</em>. </span> + <span class="pubdate">November 1987. </span> + </p> +</div> + </div> + <div class="bibliodiv"> + + + <div class="biblioentry"> +<a name="id-1.12.3.2.6.2.2"></a><p>[<abbr class="abbrev">RFC2181</abbr>] + + <span class="author"><span class="firstname">R., R. Bush</span> <span class="surname">Elz</span>. </span> + <span class="citetitle"><em class="citetitle">Clarifications to the <acronym class="acronym">DNS</acronym> + Specification</em>. </span> + <span class="pubdate">July 1997. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.2.3"></a><p>[<abbr class="abbrev">RFC2308</abbr>] + + <span class="author"><span class="firstname">M.</span> <span class="surname">Andrews</span>. </span> + <span class="citetitle"><em class="citetitle">Negative Caching of <acronym class="acronym">DNS</acronym> + Queries</em>. </span> + <span class="pubdate">March 1998. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.2.4"></a><p>[<abbr class="abbrev">RFC1995</abbr>] + + <span class="author"><span class="firstname">M.</span> <span class="surname">Ohta</span>. </span> + <span class="citetitle"><em class="citetitle">Incremental Zone Transfer in <acronym class="acronym">DNS</acronym></em>. </span> + <span class="pubdate">August 1996. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.2.5"></a><p>[<abbr class="abbrev">RFC1996</abbr>] + + <span class="author"><span class="firstname">P.</span> <span class="surname">Vixie</span>. </span> + <span class="citetitle"><em class="citetitle">A Mechanism for Prompt Notification of Zone Changes</em>. </span> + <span class="pubdate">August 1996. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.2.6"></a><p>[<abbr class="abbrev">RFC2136</abbr>] + + <span class="authorgroup"><span class="firstname">P.</span> <span class="surname">Vixie</span>, <span class="firstname">S.</span> <span class="surname">Thomson</span>, <span class="firstname">Y.</span> <span class="surname">Rekhter</span>, and <span class="firstname">J.</span> <span class="surname">Bound</span>. </span> + <span class="citetitle"><em class="citetitle">Dynamic Updates in the Domain Name System</em>. </span> + <span class="pubdate">April 1997. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.2.7"></a><p>[<abbr class="abbrev">RFC2671</abbr>] + + <span class="authorgroup"><span class="firstname">P.</span> <span class="surname">Vixie</span>. </span> + <span class="citetitle"><em class="citetitle">Extension Mechanisms for DNS (EDNS0)</em>. </span> + <span class="pubdate">August 1997. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.2.8"></a><p>[<abbr class="abbrev">RFC2672</abbr>] + + <span class="authorgroup"><span class="firstname">M.</span> <span class="surname">Crawford</span>. </span> + <span class="citetitle"><em class="citetitle">Non-Terminal DNS Name Redirection</em>. </span> + <span class="pubdate">August 1999. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.2.9"></a><p>[<abbr class="abbrev">RFC2845</abbr>] + + <span class="authorgroup"><span class="firstname">P.</span> <span class="surname">Vixie</span>, <span class="firstname">O.</span> <span class="surname">Gudmundsson</span>, <span class="firstname">D.</span> <span class="surname">Eastlake</span>, <span class="lineage">3rd</span>, and <span class="firstname">B.</span> <span class="surname">Wellington</span>. </span> + <span class="citetitle"><em class="citetitle">Secret Key Transaction Authentication for <acronym class="acronym">DNS</acronym> (TSIG)</em>. </span> + <span class="pubdate">May 2000. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.2.10"></a><p>[<abbr class="abbrev">RFC2930</abbr>] + + <span class="authorgroup"><span class="firstname">D.</span> <span class="surname">Eastlake</span>, <span class="lineage">3rd</span>. </span> + <span class="citetitle"><em class="citetitle">Secret Key Establishment for DNS (TKEY RR)</em>. </span> + <span class="pubdate">September 2000. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.2.11"></a><p>[<abbr class="abbrev">RFC2931</abbr>] + + <span class="authorgroup"><span class="firstname">D.</span> <span class="surname">Eastlake</span>, <span class="lineage">3rd</span>. </span> + <span class="citetitle"><em class="citetitle">DNS Request and Transaction Signatures (SIG(0)s)</em>. </span> + <span class="pubdate">September 2000. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.2.12"></a><p>[<abbr class="abbrev">RFC3007</abbr>] + + <span class="authorgroup"><span class="firstname">B.</span> <span class="surname">Wellington</span>. </span> + <span class="citetitle"><em class="citetitle">Secure Domain Name System (DNS) Dynamic Update</em>. </span> + <span class="pubdate">November 2000. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.2.13"></a><p>[<abbr class="abbrev">RFC3645</abbr>] + + <span class="authorgroup"><span class="firstname">S.</span> <span class="surname">Kwan</span>, <span class="firstname">P.</span> <span class="surname">Garg</span>, <span class="firstname">J.</span> <span class="surname">Gilroy</span>, <span class="firstname">L.</span> <span class="surname">Esibov</span>, <span class="firstname">J.</span> <span class="surname">Westhead</span>, and <span class="firstname">R.</span> <span class="surname">Hall</span>. </span> + <span class="citetitle"><em class="citetitle">Generic Security Service Algorithm for Secret + Key Transaction Authentication for DNS + (GSS-TSIG)</em>. </span> + <span class="pubdate">October 2003. </span> + </p> +</div> + </div> + <div class="bibliodiv"> + + <div class="biblioentry"> +<a name="id-1.12.3.2.6.3.2"></a><p>[<abbr class="abbrev">RFC3225</abbr>] + + <span class="authorgroup"><span class="firstname">D.</span> <span class="surname">Conrad</span>. </span> + <span class="citetitle"><em class="citetitle">Indicating Resolver Support of DNSSEC</em>. </span> + <span class="pubdate">December 2001. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.3.3"></a><p>[<abbr class="abbrev">RFC3833</abbr>] + + <span class="authorgroup"><span class="firstname">D.</span> <span class="surname">Atkins</span> and <span class="firstname">R.</span> <span class="surname">Austein</span>. </span> + <span class="citetitle"><em class="citetitle">Threat Analysis of the Domain Name System (DNS)</em>. </span> + <span class="pubdate">August 2004. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.3.4"></a><p>[<abbr class="abbrev">RFC4033</abbr>] + + <span class="authorgroup"><span class="firstname">R.</span> <span class="surname">Arends</span>, <span class="firstname">R.</span> <span class="surname">Austein</span>, <span class="firstname">M.</span> <span class="surname">Larson</span>, <span class="firstname">D.</span> <span class="surname">Massey</span>, and <span class="firstname">S.</span> <span class="surname">Rose</span>. </span> + <span class="citetitle"><em class="citetitle">DNS Security Introduction and Requirements</em>. </span> + <span class="pubdate">March 2005. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.3.5"></a><p>[<abbr class="abbrev">RFC4034</abbr>] + + <span class="authorgroup"><span class="firstname">R.</span> <span class="surname">Arends</span>, <span class="firstname">R.</span> <span class="surname">Austein</span>, <span class="firstname">M.</span> <span class="surname">Larson</span>, <span class="firstname">D.</span> <span class="surname">Massey</span>, and <span class="firstname">S.</span> <span class="surname">Rose</span>. </span> + <span class="citetitle"><em class="citetitle">Resource Records for the DNS Security Extensions</em>. </span> + <span class="pubdate">March 2005. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.3.6"></a><p>[<abbr class="abbrev">RFC4035</abbr>] + + <span class="authorgroup"><span class="firstname">R.</span> <span class="surname">Arends</span>, <span class="firstname">R.</span> <span class="surname">Austein</span>, <span class="firstname">M.</span> <span class="surname">Larson</span>, <span class="firstname">D.</span> <span class="surname">Massey</span>, and <span class="firstname">S.</span> <span class="surname">Rose</span>. </span> + <span class="citetitle"><em class="citetitle">Protocol Modifications for the DNS + Security Extensions</em>. </span> + <span class="pubdate">March 2005. </span> + </p> +</div> + </div> + <div class="bibliodiv"> + + <div class="biblioentry"> +<a name="id-1.12.3.2.6.4.2"></a><p>[<abbr class="abbrev">RFC1535</abbr>] + + <span class="author"><span class="firstname">E.</span> <span class="surname">Gavron</span>. </span> + <span class="citetitle"><em class="citetitle">A Security Problem and Proposed Correction With Widely + Deployed <acronym class="acronym">DNS</acronym> Software</em>. </span> + <span class="pubdate">October 1993. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.4.3"></a><p>[<abbr class="abbrev">RFC1536</abbr>] + + <span class="authorgroup"><span class="firstname">A.</span> <span class="surname">Kumar</span>, <span class="firstname">J.</span> <span class="surname">Postel</span>, <span class="firstname">C.</span> <span class="surname">Neuman</span>, <span class="firstname">P.</span> <span class="surname">Danzig</span>, and <span class="firstname">S.</span> <span class="surname">Miller</span>. </span> + <span class="citetitle"><em class="citetitle">Common <acronym class="acronym">DNS</acronym> Implementation + Errors and Suggested Fixes</em>. </span> + <span class="pubdate">October 1993. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.4.4"></a><p>[<abbr class="abbrev">RFC1982</abbr>] + + <span class="authorgroup"><span class="firstname">R.</span> <span class="surname">Elz</span> and <span class="firstname">R.</span> <span class="surname">Bush</span>. </span> + <span class="citetitle"><em class="citetitle">Serial Number Arithmetic</em>. </span> + <span class="pubdate">August 1996. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.4.5"></a><p>[<abbr class="abbrev">RFC4074</abbr>] + + <span class="authorgroup"><span class="firstname">Y.</span> <span class="surname">Morishita</span> and <span class="firstname">T.</span> <span class="surname">Jinmei</span>. </span> + <span class="citetitle"><em class="citetitle">Common Misbehaviour Against <acronym class="acronym">DNS</acronym> + Queries for IPv6 Addresses</em>. </span> + <span class="pubdate">May 2005. </span> + </p> +</div> + </div> + <div class="bibliodiv"> + + <div class="biblioentry"> +<a name="id-1.12.3.2.6.5.2"></a><p>[<abbr class="abbrev">RFC1183</abbr>] + + <span class="authorgroup"><span class="firstname">C.F.</span> <span class="surname">Everhart</span>, <span class="firstname">L. A.</span> <span class="surname">Mamakos</span>, <span class="firstname">R.</span> <span class="surname">Ullmann</span>, and <span class="firstname">P.</span> <span class="surname">Mockapetris</span>. </span> + <span class="citetitle"><em class="citetitle">New <acronym class="acronym">DNS</acronym> RR Definitions</em>. </span> + <span class="pubdate">October 1990. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.5.3"></a><p>[<abbr class="abbrev">RFC1706</abbr>] + + <span class="authorgroup"><span class="firstname">B.</span> <span class="surname">Manning</span> and <span class="firstname">R.</span> <span class="surname">Colella</span>. </span> + <span class="citetitle"><em class="citetitle"><acronym class="acronym">DNS</acronym> NSAP Resource Records</em>. </span> + <span class="pubdate">October 1994. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.5.4"></a><p>[<abbr class="abbrev">RFC2168</abbr>] + + <span class="authorgroup"><span class="firstname">R.</span> <span class="surname">Daniel</span> and <span class="firstname">M.</span> <span class="surname">Mealling</span>. </span> + <span class="citetitle"><em class="citetitle">Resolution of Uniform Resource Identifiers using + the Domain Name System</em>. </span> + <span class="pubdate">June 1997. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.5.5"></a><p>[<abbr class="abbrev">RFC1876</abbr>] + + <span class="authorgroup"><span class="firstname">C.</span> <span class="surname">Davis</span>, <span class="firstname">P.</span> <span class="surname">Vixie</span>, <span class="firstname">T.</span>, and <span class="firstname">I.</span> <span class="surname">Dickinson</span>. </span> + <span class="citetitle"><em class="citetitle">A Means for Expressing Location Information in the + Domain + Name System</em>. </span> + <span class="pubdate">January 1996. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.5.6"></a><p>[<abbr class="abbrev">RFC2052</abbr>] + + <span class="authorgroup"><span class="firstname">A.</span> <span class="surname">Gulbrandsen</span> and <span class="firstname">P.</span> <span class="surname">Vixie</span>. </span> + <span class="citetitle"><em class="citetitle">A <acronym class="acronym">DNS</acronym> RR for Specifying the + Location of + Services</em>. </span> + <span class="pubdate">October 1996. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.5.7"></a><p>[<abbr class="abbrev">RFC2163</abbr>] + + <span class="author"><span class="firstname">A.</span> <span class="surname">Allocchio</span>. </span> + <span class="citetitle"><em class="citetitle">Using the Internet <acronym class="acronym">DNS</acronym> to + Distribute MIXER + Conformant Global Address Mapping</em>. </span> + <span class="pubdate">January 1998. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.5.8"></a><p>[<abbr class="abbrev">RFC2230</abbr>] + + <span class="author"><span class="firstname">R.</span> <span class="surname">Atkinson</span>. </span> + <span class="citetitle"><em class="citetitle">Key Exchange Delegation Record for the <acronym class="acronym">DNS</acronym></em>. </span> + <span class="pubdate">October 1997. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.5.9"></a><p>[<abbr class="abbrev">RFC2536</abbr>] + + <span class="author"><span class="firstname">D.</span> <span class="surname">Eastlake</span>, <span class="lineage">3rd</span>. </span> + <span class="citetitle"><em class="citetitle">DSA KEYs and SIGs in the Domain Name System (DNS)</em>. </span> + <span class="pubdate">March 1999. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.5.10"></a><p>[<abbr class="abbrev">RFC2537</abbr>] + + <span class="author"><span class="firstname">D.</span> <span class="surname">Eastlake</span>, <span class="lineage">3rd</span>. </span> + <span class="citetitle"><em class="citetitle">RSA/MD5 KEYs and SIGs in the Domain Name System (DNS)</em>. </span> + <span class="pubdate">March 1999. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.5.11"></a><p>[<abbr class="abbrev">RFC2538</abbr>] + + <span class="authorgroup"><span class="firstname">D.</span> <span class="surname">Eastlake</span>, <span class="lineage">3rd</span> and <span class="firstname">O.</span> <span class="surname">Gudmundsson</span>. </span> + <span class="citetitle"><em class="citetitle">Storing Certificates in the Domain Name System (DNS)</em>. </span> + <span class="pubdate">March 1999. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.5.12"></a><p>[<abbr class="abbrev">RFC2539</abbr>] + + <span class="authorgroup"><span class="firstname">D.</span> <span class="surname">Eastlake</span>, <span class="lineage">3rd</span>. </span> + <span class="citetitle"><em class="citetitle">Storage of Diffie-Hellman Keys in the Domain Name System (DNS)</em>. </span> + <span class="pubdate">March 1999. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.5.13"></a><p>[<abbr class="abbrev">RFC2540</abbr>] + + <span class="authorgroup"><span class="firstname">D.</span> <span class="surname">Eastlake</span>, <span class="lineage">3rd</span>. </span> + <span class="citetitle"><em class="citetitle">Detached Domain Name System (DNS) Information</em>. </span> + <span class="pubdate">March 1999. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.5.14"></a><p>[<abbr class="abbrev">RFC2782</abbr>] + + <span class="author"><span class="firstname">A.</span> <span class="surname">Gulbrandsen</span>. </span> + <span class="author"><span class="firstname">P.</span> <span class="surname">Vixie</span>. </span> + <span class="author"><span class="firstname">L.</span> <span class="surname">Esibov</span>. </span> + <span class="citetitle"><em class="citetitle">A DNS RR for specifying the location of services (DNS SRV)</em>. </span> + <span class="pubdate">February 2000. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.5.15"></a><p>[<abbr class="abbrev">RFC2915</abbr>] + + <span class="author"><span class="firstname">M.</span> <span class="surname">Mealling</span>. </span> + <span class="author"><span class="firstname">R.</span> <span class="surname">Daniel</span>. </span> + <span class="citetitle"><em class="citetitle">The Naming Authority Pointer (NAPTR) DNS Resource Record</em>. </span> + <span class="pubdate">September 2000. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.5.16"></a><p>[<abbr class="abbrev">RFC3110</abbr>] + + <span class="author"><span class="firstname">D.</span> <span class="surname">Eastlake</span>, <span class="lineage">3rd</span>. </span> + <span class="citetitle"><em class="citetitle">RSA/SHA-1 SIGs and RSA KEYs in the Domain Name System (DNS)</em>. </span> + <span class="pubdate">May 2001. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.5.17"></a><p>[<abbr class="abbrev">RFC3123</abbr>] + + <span class="author"><span class="firstname">P.</span> <span class="surname">Koch</span>. </span> + <span class="citetitle"><em class="citetitle">A DNS RR Type for Lists of Address Prefixes (APL RR)</em>. </span> + <span class="pubdate">June 2001. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.5.18"></a><p>[<abbr class="abbrev">RFC3596</abbr>] + + <span class="authorgroup"><span class="firstname">S.</span> <span class="surname">Thomson</span>, <span class="firstname">C.</span> <span class="surname">Huitema</span>, <span class="firstname">V.</span> <span class="surname">Ksinant</span>, and <span class="firstname">M.</span> <span class="surname">Souissi</span>. </span> + <span class="citetitle"><em class="citetitle"><acronym class="acronym">DNS</acronym> Extensions to support IP + version 6</em>. </span> + <span class="pubdate">October 2003. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.5.19"></a><p>[<abbr class="abbrev">RFC3597</abbr>] + + <span class="author"><span class="firstname">A.</span> <span class="surname">Gustafsson</span>. </span> + <span class="citetitle"><em class="citetitle">Handling of Unknown DNS Resource Record (RR) Types</em>. </span> + <span class="pubdate">September 2003. </span> + </p> +</div> + </div> + <div class="bibliodiv"> + + <div class="biblioentry"> +<a name="id-1.12.3.2.6.6.2"></a><p>[<abbr class="abbrev">RFC1101</abbr>] + + <span class="author"><span class="firstname">P. V.</span> <span class="surname">Mockapetris</span>. </span> + <span class="citetitle"><em class="citetitle"><acronym class="acronym">DNS</acronym> Encoding of Network Names + and Other Types</em>. </span> + <span class="pubdate">April 1989. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.6.3"></a><p>[<abbr class="abbrev">RFC1123</abbr>] + + <span class="author"><span class="surname">Braden</span>. </span> + <span class="citetitle"><em class="citetitle">Requirements for Internet Hosts - Application and + Support</em>. </span> + <span class="pubdate">October 1989. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.6.4"></a><p>[<abbr class="abbrev">RFC1591</abbr>] + + <span class="author"><span class="firstname">J.</span> <span class="surname">Postel</span>. </span> + <span class="citetitle"><em class="citetitle">Domain Name System Structure and Delegation</em>. </span> + <span class="pubdate">March 1994. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.6.5"></a><p>[<abbr class="abbrev">RFC2317</abbr>] + + <span class="authorgroup"><span class="firstname">H.</span> <span class="surname">Eidnes</span>, <span class="firstname">G.</span> <span class="surname">de Groot</span>, and <span class="firstname">P.</span> <span class="surname">Vixie</span>. </span> + <span class="citetitle"><em class="citetitle">Classless IN-ADDR.ARPA Delegation</em>. </span> + <span class="pubdate">March 1998. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.6.6"></a><p>[<abbr class="abbrev">RFC2826</abbr>] + + <span class="authorgroup"><span class="surname">Internet Architecture Board</span>. </span> + <span class="citetitle"><em class="citetitle">IAB Technical Comment on the Unique DNS Root</em>. </span> + <span class="pubdate">May 2000. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.6.7"></a><p>[<abbr class="abbrev">RFC2929</abbr>] + + <span class="authorgroup"><span class="firstname">D.</span> <span class="surname">Eastlake</span>, <span class="lineage">3rd</span>, <span class="firstname">E.</span> <span class="surname">Brunner-Williams</span>, and <span class="firstname">B.</span> <span class="surname">Manning</span>. </span> + <span class="citetitle"><em class="citetitle">Domain Name System (DNS) IANA Considerations</em>. </span> + <span class="pubdate">September 2000. </span> + </p> +</div> + </div> + <div class="bibliodiv"> + + <div class="biblioentry"> +<a name="id-1.12.3.2.6.7.2"></a><p>[<abbr class="abbrev">RFC1033</abbr>] + + <span class="author"><span class="firstname">M.</span> <span class="surname">Lottor</span>. </span> + <span class="citetitle"><em class="citetitle">Domain administrators operations guide</em>. </span> + <span class="pubdate">November 1987. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.7.3"></a><p>[<abbr class="abbrev">RFC1537</abbr>] + + <span class="author"><span class="firstname">P.</span> <span class="surname">Beertema</span>. </span> + <span class="citetitle"><em class="citetitle">Common <acronym class="acronym">DNS</acronym> Data File + Configuration Errors</em>. </span> + <span class="pubdate">October 1993. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.7.4"></a><p>[<abbr class="abbrev">RFC1912</abbr>] + + <span class="author"><span class="firstname">D.</span> <span class="surname">Barr</span>. </span> + <span class="citetitle"><em class="citetitle">Common <acronym class="acronym">DNS</acronym> Operational and + Configuration Errors</em>. </span> + <span class="pubdate">February 1996. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.7.5"></a><p>[<abbr class="abbrev">RFC2010</abbr>] + + <span class="authorgroup"><span class="firstname">B.</span> <span class="surname">Manning</span> and <span class="firstname">P.</span> <span class="surname">Vixie</span>. </span> + <span class="citetitle"><em class="citetitle">Operational Criteria for Root Name Servers</em>. </span> + <span class="pubdate">October 1996. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.7.6"></a><p>[<abbr class="abbrev">RFC2219</abbr>] + + <span class="authorgroup"><span class="firstname">M.</span> <span class="surname">Hamilton</span> and <span class="firstname">R.</span> <span class="surname">Wright</span>. </span> + <span class="citetitle"><em class="citetitle">Use of <acronym class="acronym">DNS</acronym> Aliases for + Network Services</em>. </span> + <span class="pubdate">October 1997. </span> + </p> +</div> + </div> + <div class="bibliodiv"> + + <div class="biblioentry"> +<a name="id-1.12.3.2.6.8.2"></a><p>[<abbr class="abbrev">RFC2825</abbr>] + + <span class="authorgroup"><span class="surname">IAB</span> and <span class="firstname">R.</span> <span class="surname">Daigle</span>. </span> + <span class="citetitle"><em class="citetitle">A Tangled Web: Issues of I18N, Domain Names, + and the Other Internet protocols</em>. </span> + <span class="pubdate">May 2000. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.8.3"></a><p>[<abbr class="abbrev">RFC3490</abbr>] + + <span class="authorgroup"><span class="firstname">P.</span> <span class="surname">Faltstrom</span>, <span class="firstname">P.</span> <span class="surname">Hoffman</span>, and <span class="firstname">A.</span> <span class="surname">Costello</span>. </span> + <span class="citetitle"><em class="citetitle">Internationalizing Domain Names in Applications (IDNA)</em>. </span> + <span class="pubdate">March 2003. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.8.4"></a><p>[<abbr class="abbrev">RFC3491</abbr>] + + <span class="authorgroup"><span class="firstname">P.</span> <span class="surname">Hoffman</span> and <span class="firstname">M.</span> <span class="surname">Blanchet</span>. </span> + <span class="citetitle"><em class="citetitle">Nameprep: A Stringprep Profile for Internationalized Domain Names</em>. </span> + <span class="pubdate">March 2003. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.8.5"></a><p>[<abbr class="abbrev">RFC3492</abbr>] + + <span class="authorgroup"><span class="firstname">A.</span> <span class="surname">Costello</span>. </span> + <span class="citetitle"><em class="citetitle">Punycode: A Bootstring encoding of Unicode + for Internationalized Domain Names in + Applications (IDNA)</em>. </span> + <span class="pubdate">March 2003. </span> + </p> +</div> + </div> + <div class="bibliodiv"> + + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + Note: the following list of RFCs, although + <acronym class="acronym">DNS</acronym>-related, are not + concerned with implementing software. + </p> + </div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.9.3"></a><p>[<abbr class="abbrev">RFC1464</abbr>] + + <span class="author"><span class="firstname">R.</span> <span class="surname">Rosenbaum</span>. </span> + <span class="citetitle"><em class="citetitle">Using the Domain Name System To Store Arbitrary String + Attributes</em>. </span> + <span class="pubdate">May 1993. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.9.4"></a><p>[<abbr class="abbrev">RFC1713</abbr>] + + <span class="author"><span class="firstname">A.</span> <span class="surname">Romao</span>. </span> + <span class="citetitle"><em class="citetitle">Tools for <acronym class="acronym">DNS</acronym> Debugging</em>. </span> + <span class="pubdate">November 1994. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.9.5"></a><p>[<abbr class="abbrev">RFC1794</abbr>] + + <span class="author"><span class="firstname">T.</span> <span class="surname">Brisco</span>. </span> + <span class="citetitle"><em class="citetitle"><acronym class="acronym">DNS</acronym> Support for Load + Balancing</em>. </span> + <span class="pubdate">April 1995. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.9.6"></a><p>[<abbr class="abbrev">RFC2240</abbr>] + + <span class="author"><span class="firstname">O.</span> <span class="surname">Vaughan</span>. </span> + <span class="citetitle"><em class="citetitle">A Legal Basis for Domain Name Allocation</em>. </span> + <span class="pubdate">November 1997. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.9.7"></a><p>[<abbr class="abbrev">RFC2345</abbr>] + + <span class="authorgroup"><span class="firstname">J.</span> <span class="surname">Klensin</span>, <span class="firstname">T.</span> <span class="surname">Wolf</span>, and <span class="firstname">G.</span> <span class="surname">Oglesby</span>. </span> + <span class="citetitle"><em class="citetitle">Domain Names and Company Name Retrieval</em>. </span> + <span class="pubdate">May 1998. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.9.8"></a><p>[<abbr class="abbrev">RFC2352</abbr>] + + <span class="author"><span class="firstname">O.</span> <span class="surname">Vaughan</span>. </span> + <span class="citetitle"><em class="citetitle">A Convention For Using Legal Names as Domain Names</em>. </span> + <span class="pubdate">May 1998. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.9.9"></a><p>[<abbr class="abbrev">RFC3071</abbr>] + + <span class="authorgroup"><span class="firstname">J.</span> <span class="surname">Klensin</span>. </span> + <span class="citetitle"><em class="citetitle">Reflections on the DNS, RFC 1591, and Categories of Domains</em>. </span> + <span class="pubdate">February 2001. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.9.10"></a><p>[<abbr class="abbrev">RFC3258</abbr>] + + <span class="authorgroup"><span class="firstname">T.</span> <span class="surname">Hardie</span>. </span> + <span class="citetitle"><em class="citetitle">Distributing Authoritative Name Servers via + Shared Unicast Addresses</em>. </span> + <span class="pubdate">April 2002. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.9.11"></a><p>[<abbr class="abbrev">RFC3901</abbr>] + + <span class="authorgroup"><span class="firstname">A.</span> <span class="surname">Durand</span> and <span class="firstname">J.</span> <span class="surname">Ihren</span>. </span> + <span class="citetitle"><em class="citetitle">DNS IPv6 Transport Operational Guidelines</em>. </span> + <span class="pubdate">September 2004. </span> + </p> +</div> + </div> + <div class="bibliodiv"> + + <div class="biblioentry"> +<a name="id-1.12.3.2.6.10.2"></a><p>[<abbr class="abbrev">RFC1712</abbr>] + + <span class="authorgroup"><span class="firstname">C.</span> <span class="surname">Farrell</span>, <span class="firstname">M.</span> <span class="surname">Schulze</span>, <span class="firstname">S.</span> <span class="surname">Pleitner</span>, and <span class="firstname">D.</span> <span class="surname">Baldoni</span>. </span> + <span class="citetitle"><em class="citetitle"><acronym class="acronym">DNS</acronym> Encoding of Geographical + Location</em>. </span> + <span class="pubdate">November 1994. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.10.3"></a><p>[<abbr class="abbrev">RFC2673</abbr>] + + <span class="authorgroup"><span class="firstname">M.</span> <span class="surname">Crawford</span>. </span> + <span class="citetitle"><em class="citetitle">Binary Labels in the Domain Name System</em>. </span> + <span class="pubdate">August 1999. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.10.4"></a><p>[<abbr class="abbrev">RFC2874</abbr>] + + <span class="authorgroup"><span class="firstname">M.</span> <span class="surname">Crawford</span> and <span class="firstname">C.</span> <span class="surname">Huitema</span>. </span> + <span class="citetitle"><em class="citetitle">DNS Extensions to Support IPv6 Address Aggregation + and Renumbering</em>. </span> + <span class="pubdate">July 2000. </span> + </p> +</div> + </div> + <div class="bibliodiv"> + + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + Most of these have been consolidated into RFC4033, + RFC4034 and RFC4035 which collectively describe DNSSECbis. + </p> + </div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.11.3"></a><p>[<abbr class="abbrev">RFC2065</abbr>] + + <span class="authorgroup"><span class="firstname">D.</span> <span class="surname">Eastlake</span>, <span class="lineage">3rd</span> and <span class="firstname">C.</span> <span class="surname">Kaufman</span>. </span> + <span class="citetitle"><em class="citetitle">Domain Name System Security Extensions</em>. </span> + <span class="pubdate">January 1997. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.11.4"></a><p>[<abbr class="abbrev">RFC2137</abbr>] + + <span class="author"><span class="firstname">D.</span> <span class="surname">Eastlake</span>, <span class="lineage">3rd</span>. </span> + <span class="citetitle"><em class="citetitle">Secure Domain Name System Dynamic Update</em>. </span> + <span class="pubdate">April 1997. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.11.5"></a><p>[<abbr class="abbrev">RFC2535</abbr>] + + <span class="authorgroup"><span class="firstname">D.</span> <span class="surname">Eastlake</span>, <span class="lineage">3rd</span>. </span> + <span class="citetitle"><em class="citetitle">Domain Name System Security Extensions</em>. </span> + <span class="pubdate">March 1999. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.11.6"></a><p>[<abbr class="abbrev">RFC3008</abbr>] + + <span class="authorgroup"><span class="firstname">B.</span> <span class="surname">Wellington</span>. </span> + <span class="citetitle"><em class="citetitle">Domain Name System Security (DNSSEC) + Signing Authority</em>. </span> + <span class="pubdate">November 2000. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.11.7"></a><p>[<abbr class="abbrev">RFC3090</abbr>] + + <span class="authorgroup"><span class="firstname">E.</span> <span class="surname">Lewis</span>. </span> + <span class="citetitle"><em class="citetitle">DNS Security Extension Clarification on Zone Status</em>. </span> + <span class="pubdate">March 2001. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.11.8"></a><p>[<abbr class="abbrev">RFC3445</abbr>] + + <span class="authorgroup"><span class="firstname">D.</span> <span class="surname">Massey</span> and <span class="firstname">S.</span> <span class="surname">Rose</span>. </span> + <span class="citetitle"><em class="citetitle">Limiting the Scope of the KEY Resource Record (RR)</em>. </span> + <span class="pubdate">December 2002. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.11.9"></a><p>[<abbr class="abbrev">RFC3655</abbr>] + + <span class="authorgroup"><span class="firstname">B.</span> <span class="surname">Wellington</span> and <span class="firstname">O.</span> <span class="surname">Gudmundsson</span>. </span> + <span class="citetitle"><em class="citetitle">Redefinition of DNS Authenticated Data (AD) bit</em>. </span> + <span class="pubdate">November 2003. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.11.10"></a><p>[<abbr class="abbrev">RFC3658</abbr>] + + <span class="authorgroup"><span class="firstname">O.</span> <span class="surname">Gudmundsson</span>. </span> + <span class="citetitle"><em class="citetitle">Delegation Signer (DS) Resource Record (RR)</em>. </span> + <span class="pubdate">December 2003. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.11.11"></a><p>[<abbr class="abbrev">RFC3755</abbr>] + + <span class="authorgroup"><span class="firstname">S.</span> <span class="surname">Weiler</span>. </span> + <span class="citetitle"><em class="citetitle">Legacy Resolver Compatibility for Delegation Signer (DS)</em>. </span> + <span class="pubdate">May 2004. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.11.12"></a><p>[<abbr class="abbrev">RFC3757</abbr>] + + <span class="authorgroup"><span class="firstname">O.</span> <span class="surname">Kolkman</span>, <span class="firstname">J.</span> <span class="surname">Schlyter</span>, and <span class="firstname">E.</span> <span class="surname">Lewis</span>. </span> + <span class="citetitle"><em class="citetitle">Domain Name System KEY (DNSKEY) Resource Record + (RR) Secure Entry Point (SEP) Flag</em>. </span> + <span class="pubdate">April 2004. </span> + </p> +</div> + <div class="biblioentry"> +<a name="id-1.12.3.2.6.11.13"></a><p>[<abbr class="abbrev">RFC3845</abbr>] + + <span class="authorgroup"><span class="firstname">J.</span> <span class="surname">Schlyter</span>. </span> + <span class="citetitle"><em class="citetitle">DNS Security (DNSSEC) NextSECure (NSEC) RDATA Format</em>. </span> + <span class="pubdate">August 2004. </span> + </p> +</div> + </div> + </div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="internet_drafts"></a>Internet Drafts</h3></div></div></div> + + <p> + Internet Drafts (IDs) are rough-draft working documents of + the Internet Engineering Task Force. They are, in essence, RFCs + in the preliminary stages of development. Implementors are + cautioned not + to regard IDs as archival, and they should not be quoted or cited + in any formal documents unless accompanied by the disclaimer that + they are "works in progress." IDs have a lifespan of six months + after which they are deleted unless updated by their authors. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="more_about_bind"></a>Other Documents About <acronym class="acronym">BIND</acronym> +</h3></div></div></div> + + <p></p> + <div class="bibliography"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.12.3.4.3"></a>Bibliography</h4></div></div></div> + <div class="biblioentry"> +<a name="id-1.12.3.4.3.1"></a><p> + <span class="authorgroup"><span class="firstname">Paul</span> <span class="surname">Albitz</span> and <span class="firstname">Cricket</span> <span class="surname">Liu</span>. </span> + <span class="citetitle"><em class="citetitle"><acronym class="acronym">DNS</acronym> and <acronym class="acronym">BIND</acronym></em>. </span> + <span class="copyright">Copyright © 1998 Sebastopol, CA: O'Reilly and Associates. </span> + </p> +</div> + </div> + </div> + </div> + </div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="Bv9ARM.ch10.html">Prev</a> </td> +<td width="20%" align="center"> </td> +<td width="40%" align="right"> <a accesskey="n" href="Bv9ARM.ch12.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top">Appendix B. A Brief History of the <acronym class="acronym">DNS</acronym> and <acronym class="acronym">BIND</acronym> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> Appendix D. BIND 9 DNS Library Support</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/Bv9ARM.ch12.html b/doc/arm/Bv9ARM.ch12.html new file mode 100644 index 0000000..a527131 --- /dev/null +++ b/doc/arm/Bv9ARM.ch12.html @@ -0,0 +1,538 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Appendix D. BIND 9 DNS Library Support</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="prev" href="Bv9ARM.ch11.html" title="Appendix C. General DNS Reference Information"> +<link rel="next" href="Bv9ARM.ch13.html" title="Manual pages"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center">Appendix D. BIND 9 DNS Library Support</th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="Bv9ARM.ch11.html">Prev</a> </td> +<th width="60%" align="center"> </th> +<td width="20%" align="right"> <a accesskey="n" href="Bv9ARM.ch13.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="appendix"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="Bv9ARM.ch12"></a>BIND 9 DNS Library Support</h1></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="Bv9ARM.ch12.html#bind9.library">BIND 9 DNS Library Support</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.5">Installation</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.6">Known Defects/Restrictions</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.7">The dns.conf File</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.8">Sample Applications</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.9">Library References</a></span></dt> +</dl></dd> +</dl> +</div> + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="bind9.library"></a>BIND 9 DNS Library Support</h2></div></div></div> + + <p> + This version of BIND 9 "exports" its internal libraries so + that they can be used by third-party applications more easily (we + call them "export" libraries in this document). Certain library + functions are altered from specific BIND-only behavior to more generic + behavior when used by other applications; to enable this generic behavior, + the calling program initializes the libraries by calling + <span class="command"><strong>isc_lib_register()</strong></span>. + </p> + <p> + In addition to DNS-related APIs that are used within BIND 9, the + libraries provide the following features: + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <p> + The "DNS client" module. This is a higher level API that + provides an interface to name resolution, single DNS transaction + with a particular server, and dynamic update. Regarding name + resolution, it supports advanced features such as DNSSEC validation + and caching. This module supports both synchronous and asynchronous + mode. + </p> + </li> +<li class="listitem"> + <p> + The "IRS" (Information Retrieval System) library. It provides an + interface to parse the traditional <code class="filename">resolv.conf</code> + file and more advanced, DNS-specific configuration file for the + rest of this package (see the description for the + <code class="filename">dns.conf</code> file below). + </p> + </li> +<li class="listitem"> + <p> + As part of the IRS library, the standard address-name + mapping functions, <span class="command"><strong>getaddrinfo()</strong></span> and + <span class="command"><strong>getnameinfo()</strong></span>, are provided. They use the + DNSSEC-aware validating resolver backend, and could use other + advanced features of the BIND 9 libraries such as caching. The + <span class="command"><strong>getaddrinfo()</strong></span> function resolves both A + and AAAA RRs concurrently when the address family is + unspecified. + </p> + </li> +<li class="listitem"> + <p> + An experimental framework to support other event + libraries than BIND 9's internal event task system. + </p> + </li> +</ul></div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.13.2.5"></a>Installation</h3></div></div></div> + + <pre class="screen"> +$ <strong class="userinput"><code>make install</code></strong> + </pre> + <p> + Normal installation of BIND will also install library object + and header files. Root privilege is normally required. + </p> + <p> + To see how to build your own application after the installation, see + <code class="filename">lib/samples/Makefile-postinstall.in</code>. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.13.2.6"></a>Known Defects/Restrictions</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <p> + The "fixed" RRset order is not (currently) supported in the export + library. If you want to use "fixed" RRset order for, e.g. + <span class="command"><strong>named</strong></span> while still building the export library + even without the fixed order support, build them separately: + </p> +<pre class="screen"> +$ <strong class="userinput"><code>./configure --enable-fixed-rrset <em class="replaceable"><code>[other flags, but not --enable-exportlib]</code></em></code></strong> +$ <strong class="userinput"><code>make</code></strong> +$ <strong class="userinput"><code>./configure --enable-exportlib <em class="replaceable"><code>[other flags, but not --enable-fixed-rrset]</code></em></code></strong> +$ <strong class="userinput"><code>cd lib/export</code></strong> +$ <strong class="userinput"><code>make</code></strong> +</pre> +<p> + </p> + </li> +<li class="listitem"> + <p> + RFC 5011 is not supported in the validating stub resolver of the + export library. In fact, it is not clear whether it should: trust + anchors would be a system-wide configuration which would be managed + by an administrator, while the stub resolver will be used by + ordinary applications run by a normal user. + </p> + </li> +<li class="listitem"> + <p> + Not all common <code class="filename">/etc/resolv.conf</code> options are + supported in the IRS library. The only available options in this + version are <span class="command"><strong>debug</strong></span> and <span class="command"><strong>ndots</strong></span>. + </p> + </li> +</ul></div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.13.2.7"></a>The dns.conf File</h3></div></div></div> + + <p> + The IRS library supports an "advanced" configuration file related to + the DNS library for configuration parameters that would be beyond the + capability of the <code class="filename">resolv.conf</code> file. + Specifically, it is intended to provide DNSSEC related configuration + parameters. By default the path to this configuration file is + <code class="filename">/etc/dns.conf</code>. This module is very experimental + and the configuration syntax or library interfaces may change in + future versions. Currently, only the <span class="command"><strong>trusted-keys</strong></span> + statement is supported, whose syntax is the same as the same + statement in <code class="filename">named.conf</code>. (See + <a class="xref" href="Bv9ARM.ch06.html#trusted-keys" title="trusted-keys Statement Grammar">the section called “<span class="command"><strong>trusted-keys</strong></span> Statement Grammar”</a> for details.) + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.13.2.8"></a>Sample Applications</h3></div></div></div> + + <p> + Some sample application programs using this API are provided for + reference. The following is a brief description of these + applications. + </p> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.13.2.8.3"></a>sample: a simple stub resolver utility</h4></div></div></div> + + <p> + Sends a query of a given name (of a given optional RR type) to a + specified recursive server and prints the result as a list of RRs. + It can also act as a validating stub resolver if a trust anchor is + given via a set of command line options. + </p> + <p> + Usage: sample [options] server_address hostname + </p> + <p> + Options and Arguments: + </p> + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-t RRtype</span></dt> +<dd> + <p> + specify the RR type of the query. The default is the A RR. + </p> + </dd> +<dt><span class="term">[-a algorithm] [-e] -k keyname -K keystring</span></dt> +<dd> + <p> + specify a command-line DNS key to validate the answer. For + example, to specify the following DNSKEY of example.com: + </p> +<div class="literallayout"><p><br> + example.com. 3600 IN DNSKEY 257 3 5 xxx<br> + </p></div> +<p> + specify the options as follows: + </p> +<pre class="screen"> +<strong class="userinput"><code>-e -k example.com -K "xxx"</code></strong> + </pre> +<p> + -e means that this key is a zone's "key signing key" (also known + as "secure entry point"). + When -a is omitted rsasha1 will be used by default. + </p> + </dd> +<dt><span class="term">-s domain:alt_server_address</span></dt> +<dd> + <p> + specify a separate recursive server address for the specific + "domain". Example: -s example.com:2001:db8::1234 + </p> + </dd> +<dt><span class="term">server_address</span></dt> +<dd> + <p> + an IP(v4/v6) address of the recursive server to which queries + are sent. + </p> + </dd> +<dt><span class="term">hostname</span></dt> +<dd> + <p> + the domain name for the query + </p> + </dd> +</dl></div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.13.2.8.4"></a>sample-async: a simple stub resolver, working asynchronously</h4></div></div></div> + + <p> + Similar to "sample", but accepts a list + of (query) domain names as a separate file and resolves the names + asynchronously.</p> + <p> + Usage: sample-async [-s server_address] [-t RR_type] input_file</p> + <p> + Options and Arguments: + </p> + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-s server_address</span></dt> +<dd> + an IPv4 address of the recursive server to which queries are sent. + (IPv6 addresses are not supported in this implementation) + </dd> +<dt><span class="term">-t RR_type</span></dt> +<dd> + specify the RR type of the queries. The default is the A + RR. + </dd> +<dt><span class="term">input_file</span></dt> +<dd> + a list of domain names to be resolved. each line consists of a + single domain name. Example: + <div class="literallayout"><p><br> + www.example.com<br> + mx.example.net<br> + ns.xxx.example<br> + </p></div> + </dd> +</dl></div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.13.2.8.5"></a>sample-request: a simple DNS transaction client</h4></div></div></div> + + <p> + Sends a query to a specified server, and prints the response with + minimal processing. It doesn't act as a "stub resolver": it stops + the processing once it gets any response from the server, whether + it's a referral or an alias (CNAME or DNAME) that would require + further queries to get the ultimate answer. In other words, this + utility acts as a very simplified <span class="command"><strong>dig</strong></span>. + </p> + <p> + Usage: sample-request [-t RRtype] server_address hostname + </p> + <p> + Options and Arguments: + </p> + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-t RRtype</span></dt> +<dd> + <p> + specify the RR type of the queries. The default is the A RR. + </p> + </dd> +<dt><span class="term">server_address</span></dt> +<dd> + <p> + an IP(v4/v6) address of the recursive server to which + the query is sent. + </p> + </dd> +<dt><span class="term">hostname</span></dt> +<dd> + <p> + the domain name for the query + </p> + </dd> +</dl></div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.13.2.8.6"></a>sample-gai: getaddrinfo() and getnameinfo() test code</h4></div></div></div> + + <p> + This is a test program to check <span class="command"><strong>getaddrinfo()</strong></span> and + <span class="command"><strong>getnameinfo()</strong></span> behavior. It takes a host name as an + argument, calls <span class="command"><strong>getaddrinfo()</strong></span> with the given host + name, and calls <span class="command"><strong>getnameinfo()</strong></span> with the resulting + IP addresses returned by <span class="command"><strong>getaddrinfo()</strong></span>. If the + dns.conf file exists and defines a trust anchor, the underlying + resolver will act as a validating resolver, and + <span class="command"><strong>getaddrinfo()</strong></span>/<span class="command"><strong>getnameinfo()</strong></span> + will fail with an EAI_INSECUREDATA error when DNSSEC validation + fails. + </p> + <p> + Usage: sample-gai hostname + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.13.2.8.7"></a>sample-update: a simple dynamic update client program</h4></div></div></div> + + <p> + Accepts a single update command as a command-line argument, sends + an update request message to the authoritative server, and shows + the response from the server. In other words, this is a simplified + <span class="command"><strong>nsupdate</strong></span>. + </p> + <p> + Usage: sample-update [options] (add|delete) "update data" + </p> + <p> + Options and Arguments: + </p> + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-a auth_server</span></dt> +<dd> + <p> + An IP address of the authoritative server that has authority + for the zone containing the update name. This should + normally be the primary authoritative server that accepts + dynamic updates. It can also be a secondary server that is + configured to forward update requests to the primary server. + </p> + </dd> +<dt><span class="term">-k keyfile</span></dt> +<dd> + <p> + A TSIG key file to secure the update transaction. The + keyfile format is the same as that for the nsupdate utility. + </p> + </dd> +<dt><span class="term">-p prerequisite</span></dt> +<dd> + <p> + A prerequisite for the update (only one prerequisite can be + specified). The prerequisite format is the same as that is + accepted by the nsupdate utility. + </p> + </dd> +<dt><span class="term">-r recursive_server</span></dt> +<dd> + <p> + An IP address of a recursive server that this utility will + use. A recursive server may be necessary to identify the + authoritative server address to which the update request is + sent. + </p> + </dd> +<dt><span class="term">-z zonename</span></dt> +<dd> + <p> + The domain name of the zone that contains + </p> + </dd> +<dt><span class="term">(add|delete)</span></dt> +<dd> + <p> + Specify the type of update operation. Either "add" or + "delete" must be specified. + </p> + </dd> +<dt><span class="term">"update data"</span></dt> +<dd> + <p> + Specify the data to be updated. A typical example of the + data would look like "name TTL RRtype RDATA". + </p> + </dd> +</dl></div> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + In practice, either -a or -r must be specified. Others can be + optional; the underlying library routine tries to identify the + appropriate server and the zone name for the update. + </p> + </div> + <p> + Examples: assuming the primary authoritative server of the + dynamic.example.com zone has an IPv6 address 2001:db8::1234, + </p> + <pre class="screen"> +$ <strong class="userinput"><code>sample-update -a sample-update -k Kxxx.+nnn+mmmm.key add "foo.dynamic.example.com 30 IN A 192.168.2.1"</code></strong></pre> + <p> + adds an A RR for foo.dynamic.example.com using the given key. + </p> + <pre class="screen"> +$ <strong class="userinput"><code>sample-update -a sample-update -k Kxxx.+nnn+mmmm.key delete "foo.dynamic.example.com 30 IN A"</code></strong></pre> + <p> + removes all A RRs for foo.dynamic.example.com using the given key. + </p> + <pre class="screen"> +$ <strong class="userinput"><code>sample-update -a sample-update -k Kxxx.+nnn+mmmm.key delete "foo.dynamic.example.com"</code></strong></pre> + <p> + removes all RRs for foo.dynamic.example.com using the given key. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.13.2.8.8"></a>nsprobe: domain/name server checker in terms of RFC 4074</h4></div></div></div> + + <p> + Checks a set of domains to see the name servers of the domains + behave correctly in terms of RFC 4074. This is included in the set + of sample programs to show how the export library can be used in a + DNS-related application. + </p> + <p> + Usage: nsprobe [-d] [-v [-v...]] [-c cache_address] [input_file] + </p> + <p> + Options + </p> + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-d</span></dt> +<dd> + <p> + Run in "debug" mode. With this option nsprobe will dump + every RRs it receives. + </p> + </dd> +<dt><span class="term">-v</span></dt> +<dd> + <p> + Increase verbosity of other normal log messages. This can be + specified multiple times. + </p> + </dd> +<dt><span class="term">-c cache_address</span></dt> +<dd> + <p> + Specify an IP address of a recursive (caching) name server. + nsprobe uses this server to get the NS RRset of each domain + and the A and/or AAAA RRsets for the name servers. The + default value is 127.0.0.1. + </p> + </dd> +<dt><span class="term">input_file</span></dt> +<dd> + <p> + A file name containing a list of domain (zone) names to be + probed. when omitted the standard input will be used. Each + line of the input file specifies a single domain name such as + "example.com". In general this domain name must be the apex + name of some DNS zone (unlike normal "host names" such as + "www.example.com"). nsprobe first identifies the NS RRsets + for the given domain name, and sends A and AAAA queries to + these servers for some "widely used" names under the zone; + specifically, adding "www" and "ftp" to the zone name. + </p> + </dd> +</dl></div> + </div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.13.2.9"></a>Library References</h3></div></div></div> + + <p> + As of this writing, there is no formal "manual" for the libraries, + except this document, header files (some of which provide pretty + detailed explanations), and sample application programs. + </p> + </div> +</div> + </div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="Bv9ARM.ch11.html">Prev</a> </td> +<td width="20%" align="center"> </td> +<td width="40%" align="right"> <a accesskey="n" href="Bv9ARM.ch13.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top">Appendix C. General <acronym class="acronym">DNS</acronym> Reference Information </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> Manual pages</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/Bv9ARM.ch13.html b/doc/arm/Bv9ARM.ch13.html new file mode 100644 index 0000000..a544fff --- /dev/null +++ b/doc/arm/Bv9ARM.ch13.html @@ -0,0 +1,218 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Manual pages</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="prev" href="Bv9ARM.ch12.html" title="Appendix D. BIND 9 DNS Library Support"> +<link rel="next" href="man.dig.html" title="dig"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center">Manual pages</th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="Bv9ARM.ch12.html">Prev</a> </td> +<th width="60%" align="center"> </th> +<td width="20%" align="right"> <a accesskey="n" href="man.dig.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="reference"> +<div class="titlepage"> +<div><div><h1 class="title"> +<a name="Bv9ARM.ch13"></a>Manual pages</h1></div></div> +<hr> +</div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt> +<span class="refentrytitle"><a href="man.dig.html">dig</a></span><span class="refpurpose"> — DNS lookup utility</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.mdig.html"><span class="application">mdig</span></a></span><span class="refpurpose"> — DNS pipelined lookup utility</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.host.html">host</a></span><span class="refpurpose"> — DNS lookup utility</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.delv.html">delv</a></span><span class="refpurpose"> — DNS lookup and validation utility</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.nslookup.html">nslookup</a></span><span class="refpurpose"> — query Internet name servers interactively</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.dnssec-checkds.html"><span class="application">dnssec-checkds</span></a></span><span class="refpurpose"> — DNSSEC delegation consistency checking tool</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.dnssec-coverage.html"><span class="application">dnssec-coverage</span></a></span><span class="refpurpose"> — checks future DNSKEY coverage for a zone</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.dnssec-dsfromkey.html"><span class="application">dnssec-dsfromkey</span></a></span><span class="refpurpose"> — DNSSEC DS RR generation tool</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.dnssec-importkey.html"><span class="application">dnssec-importkey</span></a></span><span class="refpurpose"> — import DNSKEY records from external systems so they can be managed</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.dnssec-keyfromlabel.html"><span class="application">dnssec-keyfromlabel</span></a></span><span class="refpurpose"> — DNSSEC key generation tool</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.dnssec-keygen.html"><span class="application">dnssec-keygen</span></a></span><span class="refpurpose"> — DNSSEC key generation tool</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.dnssec-keymgr.html"><span class="application">dnssec-keymgr</span></a></span><span class="refpurpose"> — Ensures correct DNSKEY coverage for a zone based on a defined policy</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.dnssec-revoke.html"><span class="application">dnssec-revoke</span></a></span><span class="refpurpose"> — set the REVOKED bit on a DNSSEC key</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.dnssec-settime.html"><span class="application">dnssec-settime</span></a></span><span class="refpurpose"> — set the key timing metadata for a DNSSEC key</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.dnssec-signzone.html"><span class="application">dnssec-signzone</span></a></span><span class="refpurpose"> — DNSSEC zone signing tool</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.dnssec-verify.html"><span class="application">dnssec-verify</span></a></span><span class="refpurpose"> — DNSSEC zone verification tool</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.lwresd.html"><span class="application">lwresd</span></a></span><span class="refpurpose"> — lightweight resolver daemon</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.named.html"><span class="application">named</span></a></span><span class="refpurpose"> — Internet domain name server</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.named.conf.html"><code class="filename">named.conf</code></a></span><span class="refpurpose"> — configuration file for <span class="command"><strong>named</strong></span></span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.named-checkconf.html"><span class="application">named-checkconf</span></a></span><span class="refpurpose"> — named configuration file syntax checking tool</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.named-checkzone.html"><span class="application">named-checkzone</span></a></span><span class="refpurpose"> — zone file validity checking or converting tool</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.named-journalprint.html"><span class="application">named-journalprint</span></a></span><span class="refpurpose"> — print zone journal in human-readable form</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.named-nzd2nzf.html"><span class="application">named-nzd2nzf</span></a></span><span class="refpurpose"> — + Convert an NZD database to NZF text format + </span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.named-rrchecker.html"><span class="application">named-rrchecker</span></a></span><span class="refpurpose"> — syntax checker for individual DNS resource records</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.nsupdate.html"><span class="application">nsupdate</span></a></span><span class="refpurpose"> — Dynamic DNS update utility</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.rndc.html"><span class="application">rndc</span></a></span><span class="refpurpose"> — name server control utility</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.rndc.conf.html"><code class="filename">rndc.conf</code></a></span><span class="refpurpose"> — rndc configuration file</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.rndc-confgen.html"><span class="application">rndc-confgen</span></a></span><span class="refpurpose"> — rndc key generation tool</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.ddns-confgen.html"><span class="application">ddns-confgen</span></a></span><span class="refpurpose"> — ddns key generation tool</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.arpaname.html"><span class="application">arpaname</span></a></span><span class="refpurpose"> — translate IP addresses to the corresponding ARPA names</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.dnstap-read.html"><span class="application">dnstap-read</span></a></span><span class="refpurpose"> — print dnstap data in human-readable form</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.genrandom.html"><span class="application">genrandom</span></a></span><span class="refpurpose"> — generate a file containing random data</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.isc-hmac-fixup.html"><span class="application">isc-hmac-fixup</span></a></span><span class="refpurpose"> — fixes HMAC keys generated by older versions of BIND</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.nsec3hash.html"><span class="application">nsec3hash</span></a></span><span class="refpurpose"> — generate NSEC3 hash</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.pkcs11-destroy.html"><span class="application">pkcs11-destroy</span></a></span><span class="refpurpose"> — destroy PKCS#11 objects</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.pkcs11-list.html"><span class="application">pkcs11-list</span></a></span><span class="refpurpose"> — list PKCS#11 objects</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.pkcs11-keygen.html"><span class="application">pkcs11-keygen</span></a></span><span class="refpurpose"> — generate keys on a PKCS#11 device</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.pkcs11-tokens.html"><span class="application">pkcs11-tokens</span></a></span><span class="refpurpose"> — list PKCS#11 available tokens</span> +</dt> +</dl> +</div> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + </div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="Bv9ARM.ch12.html">Prev</a> </td> +<td width="20%" align="center"> </td> +<td width="40%" align="right"> <a accesskey="n" href="man.dig.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top">Appendix D. BIND 9 DNS Library Support </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> dig</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/Bv9ARM.conf b/doc/arm/Bv9ARM.conf new file mode 100644 index 0000000..cf095ca --- /dev/null +++ b/doc/arm/Bv9ARM.conf @@ -0,0 +1,3 @@ +TexInputs: ../tex// +TexStyle: armstyle +XslParam: ../xsl/arm-param.xsl diff --git a/doc/arm/Bv9ARM.html b/doc/arm/Bv9ARM.html new file mode 100644 index 0000000..f8df3c9 --- /dev/null +++ b/doc/arm/Bv9ARM.html @@ -0,0 +1,448 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>BIND 9 Administrator Reference Manual</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="next" href="Bv9ARM.ch01.html" title="Chapter 1. Introduction"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center">BIND 9 Administrator Reference Manual</th></tr> +<tr> +<td width="20%" align="left"> </td> +<th width="60%" align="center"> </th> +<td width="20%" align="right"> <a accesskey="n" href="Bv9ARM.ch01.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="book"> +<div class="titlepage"> +<div> +<div><h1 class="title"> +<a name="id-1"></a>BIND 9 Administrator Reference Manual</h1></div> +<div><p class="releaseinfo">BIND Version 9.11.5-P4</p></div> +<div><p class="copyright">Copyright © 2000-2019 Internet Systems Consortium, Inc. ("ISC")</p></div> +</div> +<hr> +</div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="chapter"><a href="Bv9ARM.ch01.html">1. Introduction</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch01.html#doc_scope">Scope of Document</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch01.html#organization">Organization of This Document</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch01.html#conventions">Conventions Used in This Document</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch01.html#dns_overview">The Domain Name System (<acronym class="acronym">DNS</acronym>)</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch01.html#dns_fundamentals">DNS Fundamentals</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch01.html#domain_names">Domains and Domain Names</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch01.html#zones">Zones</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch01.html#auth_servers">Authoritative Name Servers</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch01.html#cache_servers">Caching Name Servers</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch01.html#multi_role">Name Servers in Multiple Roles</a></span></dt> +</dl></dd> +</dl></dd> +<dt><span class="chapter"><a href="Bv9ARM.ch02.html">2. <acronym class="acronym">BIND</acronym> Resource Requirements</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch02.html#hw_req">Hardware requirements</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch02.html#cpu_req">CPU Requirements</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch02.html#mem_req">Memory Requirements</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch02.html#intensive_env">Name Server Intensive Environment Issues</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch02.html#supported_os">Supported Operating Systems</a></span></dt> +</dl></dd> +<dt><span class="chapter"><a href="Bv9ARM.ch03.html">3. Name Server Configuration</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch03.html#sample_configuration">Sample Configurations</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch03.html#cache_only_sample">A Caching-only Name Server</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch03.html#auth_only_sample">An Authoritative-only Name Server</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch03.html#load_balancing">Load Balancing</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch03.html#ns_operations">Name Server Operations</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch03.html#tools">Tools for Use With the Name Server Daemon</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch03.html#signals">Signals</a></span></dt> +</dl></dd> +</dl></dd> +<dt><span class="chapter"><a href="Bv9ARM.ch04.html">4. Advanced DNS Features</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch04.html#notify">Notify</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#dynamic_update">Dynamic Update</a></span></dt> +<dd><dl><dt><span class="section"><a href="Bv9ARM.ch04.html#journal">The journal file</a></span></dt></dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch04.html#incremental_zone_transfers">Incremental Zone Transfers (IXFR)</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#split_dns">Split DNS</a></span></dt> +<dd><dl><dt><span class="section"><a href="Bv9ARM.ch04.html#split_dns_sample">Example split DNS setup</a></span></dt></dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch04.html#tsig">TSIG</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.6.5">Generating a Shared Key</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.6.6">Loading A New Key</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.6.7">Instructing the Server to Use a Key</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.6.8">TSIG-Based Access Control</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.6.9">Errors</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch04.html#tkey">TKEY</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#sig0">SIG(0)</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#DNSSEC">DNSSEC</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch04.html#dnssec_keys">Generating Keys</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#dnssec_signing">Signing the Zone</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#dnssec_config">Configuring Servers</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch04.html#dnssec.dynamic.zones">DNSSEC, Dynamic Zones, and Automatic Signing</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.2">Converting from insecure to secure</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.7">Dynamic DNS update method</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.15">Fully automatic zone signing</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.24">Private-type records</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.31">DNSKEY rollovers</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.33">Dynamic DNS update method</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.38">Automatic key rollovers</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.40">NSEC3PARAM rollovers via UPDATE</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.42">Converting from NSEC to NSEC3</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.44">Converting from NSEC3 to NSEC</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.46">Converting from secure to insecure</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.50">Periodic re-signing</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.52">NSEC3 and OPTOUT</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch04.html#rfc5011.support">Dynamic Trust Anchor Management</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.11.3">Validating Resolver</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.11.4">Authoritative Server</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch04.html#pkcs11">PKCS#11 (Cryptoki) support</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.12.6">Prerequisites</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.12.7">Native PKCS#11</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.12.8">OpenSSL-based PKCS#11</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.12.9">PKCS#11 Tools</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.12.10">Using the HSM</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.12.11">Specifying the engine on the command line</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.12.12">Running named with automatic zone re-signing</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch04.html#dlz-info">DLZ (Dynamically Loadable Zones)</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.13.6">Configuring DLZ</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.13.7">Sample DLZ Driver</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch04.html#dyndb-info">DynDB (Dynamic Database)</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.14.5">Configuring DynDB</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.14.6">Sample DynDB Module</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch04.html#catz-info">Catalog Zones</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.15.4">Principle of Operation</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.15.5">Configuring Catalog Zones</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.15.6">Catalog Zone format</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch04.html#ipv6">IPv6 Support in <acronym class="acronym">BIND</acronym> 9</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.16.6">Address Lookups Using AAAA Records</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.16.7">Address to Name Lookups Using Nibble Format</a></span></dt> +</dl></dd> +</dl></dd> +<dt><span class="chapter"><a href="Bv9ARM.ch05.html">5. The <acronym class="acronym">BIND</acronym> 9 Lightweight Resolver</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch05.html#lightweight_resolver">The Lightweight Resolver Library</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch05.html#lwresd">Running a Resolver Daemon</a></span></dt> +</dl></dd> +<dt><span class="chapter"><a href="Bv9ARM.ch06.html">6. <acronym class="acronym">BIND</acronym> 9 Configuration Reference</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch06.html#configuration_file_elements">Configuration File Elements</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch06.html#address_match_lists">Address Match Lists</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#comment_syntax">Comment Syntax</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch06.html#Configuration_File_Grammar">Configuration File Grammar</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch06.html#acl_grammar"><span class="command"><strong>acl</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#acl"><span class="command"><strong>acl</strong></span> Statement Definition and + Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#controls_grammar"><span class="command"><strong>controls</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#controls_statement_definition_and_usage"><span class="command"><strong>controls</strong></span> Statement Definition and + Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#include_grammar"><span class="command"><strong>include</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#include_statement"><span class="command"><strong>include</strong></span> Statement Definition and Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#key_grammar"><span class="command"><strong>key</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#key_statement"><span class="command"><strong>key</strong></span> Statement Definition and Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#logging_grammar"><span class="command"><strong>logging</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#logging_statement"><span class="command"><strong>logging</strong></span> Statement Definition and Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#lwres_grammar"><span class="command"><strong>lwres</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#lwres_statement"><span class="command"><strong>lwres</strong></span> Statement Definition and Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#masters_grammar"><span class="command"><strong>masters</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#masters_statement"><span class="command"><strong>masters</strong></span> Statement Definition and + Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#options_grammar"><span class="command"><strong>options</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#options"><span class="command"><strong>options</strong></span> Statement Definition and + Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#server_statement_grammar"><span class="command"><strong>server</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#server_statement_definition_and_usage"><span class="command"><strong>server</strong></span> Statement Definition and + Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#statschannels"><span class="command"><strong>statistics-channels</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#statistics_channels"><span class="command"><strong>statistics-channels</strong></span> Statement Definition and + Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#trusted-keys"><span class="command"><strong>trusted-keys</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#trusted_keys"><span class="command"><strong>trusted-keys</strong></span> Statement Definition + and Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#managed_keys"><span class="command"><strong>managed-keys</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#managed-keys"><span class="command"><strong>managed-keys</strong></span> Statement Definition + and Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#view_statement_grammar"><span class="command"><strong>view</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#view_statement"><span class="command"><strong>view</strong></span> Statement Definition and Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#zone_statement_grammar"><span class="command"><strong>zone</strong></span> + Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#zone_statement"><span class="command"><strong>zone</strong></span> Statement Definition and Usage</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch06.html#zone_file">Zone File</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch06.html#types_of_resource_records_and_when_to_use_them">Types of Resource Records and When to Use Them</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#mx_records">Discussion of MX Records</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#Setting_TTLs">Setting TTLs</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#ipv4_reverse">Inverse Mapping in IPv4</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#zone_directives">Other Zone File Directives</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#generate_directive"><acronym class="acronym">BIND</acronym> Master File Extension: the <span class="command"><strong>$GENERATE</strong></span> Directive</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#zonefile_format">Additional File Formats</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch06.html#statistics">BIND9 Statistics</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch06.html#statsfile">The Statistics File</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#statistics_counters">Statistics Counters</a></span></dt> +</dl></dd> +</dl></dd> +<dt><span class="chapter"><a href="Bv9ARM.ch07.html">7. <acronym class="acronym">BIND</acronym> 9 Security Considerations</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch07.html#Access_Control_Lists">Access Control Lists</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch07.html#chroot_and_setuid"><span class="command"><strong>Chroot</strong></span> and <span class="command"><strong>Setuid</strong></span></a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch07.html#chroot">The <span class="command"><strong>chroot</strong></span> Environment</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch07.html#setuid">Using the <span class="command"><strong>setuid</strong></span> Function</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch07.html#dynamic_update_security">Dynamic Update Security</a></span></dt> +</dl></dd> +<dt><span class="chapter"><a href="Bv9ARM.ch08.html">8. Troubleshooting</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch08.html#common_problems">Common Problems</a></span></dt> +<dd><dl><dt><span class="section"><a href="Bv9ARM.ch08.html#id-1.9.2.2">It's not working; how can I figure out what's wrong?</a></span></dt></dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch08.html#id-1.9.3">Incrementing and Changing the Serial Number</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch08.html#more_help">Where Can I Get Help?</a></span></dt> +</dl></dd> +<dt><span class="appendix"><a href="Bv9ARM.ch09.html">A. Release Notes</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch09.html#id-1.10.2">Release Notes for BIND Version 9.11.5-P4</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch09.html#relnotes_intro">Introduction</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch09.html#relnotes_download">Download</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch09.html#relnotes_license">License Change</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch09.html#win_support">Legacy Windows No Longer Supported</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch09.html#relnotes_security">Security Fixes</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch09.html#relnotes_features">New Features</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch09.html#relnotes_removed">Removed Features</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch09.html#relnotes_changes">Feature Changes</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch09.html#relnotes_bugs">Bug Fixes</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch09.html#end_of_life">End of Life</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch09.html#relnotes_thanks">Thank You</a></span></dt> +</dl></dd> +</dl></dd> +<dt><span class="appendix"><a href="Bv9ARM.ch10.html">B. A Brief History of the <acronym class="acronym">DNS</acronym> and <acronym class="acronym">BIND</acronym></a></span></dt> +<dt><span class="appendix"><a href="Bv9ARM.ch11.html">C. General <acronym class="acronym">DNS</acronym> Reference Information</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch11.html#ipv6addresses">IPv6 addresses (AAAA)</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch11.html#bibliography">Bibliography (and Suggested Reading)</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch11.html#rfcs">Request for Comments (RFCs)</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch11.html#internet_drafts">Internet Drafts</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch11.html#more_about_bind">Other Documents About <acronym class="acronym">BIND</acronym></a></span></dt> +</dl></dd> +</dl></dd> +<dt><span class="appendix"><a href="Bv9ARM.ch12.html">D. BIND 9 DNS Library Support</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch12.html#bind9.library">BIND 9 DNS Library Support</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.5">Installation</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.6">Known Defects/Restrictions</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.7">The dns.conf File</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.8">Sample Applications</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.9">Library References</a></span></dt> +</dl></dd> +</dl></dd> +<dt><span class="reference"><a href="Bv9ARM.ch13.html">I. Manual pages</a></span></dt> +<dd><dl> +<dt> +<span class="refentrytitle"><a href="man.dig.html">dig</a></span><span class="refpurpose"> — DNS lookup utility</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.mdig.html"><span class="application">mdig</span></a></span><span class="refpurpose"> — DNS pipelined lookup utility</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.host.html">host</a></span><span class="refpurpose"> — DNS lookup utility</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.delv.html">delv</a></span><span class="refpurpose"> — DNS lookup and validation utility</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.nslookup.html">nslookup</a></span><span class="refpurpose"> — query Internet name servers interactively</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.dnssec-checkds.html"><span class="application">dnssec-checkds</span></a></span><span class="refpurpose"> — DNSSEC delegation consistency checking tool</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.dnssec-coverage.html"><span class="application">dnssec-coverage</span></a></span><span class="refpurpose"> — checks future DNSKEY coverage for a zone</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.dnssec-dsfromkey.html"><span class="application">dnssec-dsfromkey</span></a></span><span class="refpurpose"> — DNSSEC DS RR generation tool</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.dnssec-importkey.html"><span class="application">dnssec-importkey</span></a></span><span class="refpurpose"> — import DNSKEY records from external systems so they can be managed</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.dnssec-keyfromlabel.html"><span class="application">dnssec-keyfromlabel</span></a></span><span class="refpurpose"> — DNSSEC key generation tool</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.dnssec-keygen.html"><span class="application">dnssec-keygen</span></a></span><span class="refpurpose"> — DNSSEC key generation tool</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.dnssec-keymgr.html"><span class="application">dnssec-keymgr</span></a></span><span class="refpurpose"> — Ensures correct DNSKEY coverage for a zone based on a defined policy</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.dnssec-revoke.html"><span class="application">dnssec-revoke</span></a></span><span class="refpurpose"> — set the REVOKED bit on a DNSSEC key</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.dnssec-settime.html"><span class="application">dnssec-settime</span></a></span><span class="refpurpose"> — set the key timing metadata for a DNSSEC key</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.dnssec-signzone.html"><span class="application">dnssec-signzone</span></a></span><span class="refpurpose"> — DNSSEC zone signing tool</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.dnssec-verify.html"><span class="application">dnssec-verify</span></a></span><span class="refpurpose"> — DNSSEC zone verification tool</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.lwresd.html"><span class="application">lwresd</span></a></span><span class="refpurpose"> — lightweight resolver daemon</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.named.html"><span class="application">named</span></a></span><span class="refpurpose"> — Internet domain name server</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.named.conf.html"><code class="filename">named.conf</code></a></span><span class="refpurpose"> — configuration file for <span class="command"><strong>named</strong></span></span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.named-checkconf.html"><span class="application">named-checkconf</span></a></span><span class="refpurpose"> — named configuration file syntax checking tool</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.named-checkzone.html"><span class="application">named-checkzone</span></a></span><span class="refpurpose"> — zone file validity checking or converting tool</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.named-journalprint.html"><span class="application">named-journalprint</span></a></span><span class="refpurpose"> — print zone journal in human-readable form</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.named-nzd2nzf.html"><span class="application">named-nzd2nzf</span></a></span><span class="refpurpose"> — + Convert an NZD database to NZF text format + </span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.named-rrchecker.html"><span class="application">named-rrchecker</span></a></span><span class="refpurpose"> — syntax checker for individual DNS resource records</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.nsupdate.html"><span class="application">nsupdate</span></a></span><span class="refpurpose"> — Dynamic DNS update utility</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.rndc.html"><span class="application">rndc</span></a></span><span class="refpurpose"> — name server control utility</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.rndc.conf.html"><code class="filename">rndc.conf</code></a></span><span class="refpurpose"> — rndc configuration file</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.rndc-confgen.html"><span class="application">rndc-confgen</span></a></span><span class="refpurpose"> — rndc key generation tool</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.ddns-confgen.html"><span class="application">ddns-confgen</span></a></span><span class="refpurpose"> — ddns key generation tool</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.arpaname.html"><span class="application">arpaname</span></a></span><span class="refpurpose"> — translate IP addresses to the corresponding ARPA names</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.dnstap-read.html"><span class="application">dnstap-read</span></a></span><span class="refpurpose"> — print dnstap data in human-readable form</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.genrandom.html"><span class="application">genrandom</span></a></span><span class="refpurpose"> — generate a file containing random data</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.isc-hmac-fixup.html"><span class="application">isc-hmac-fixup</span></a></span><span class="refpurpose"> — fixes HMAC keys generated by older versions of BIND</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.nsec3hash.html"><span class="application">nsec3hash</span></a></span><span class="refpurpose"> — generate NSEC3 hash</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.pkcs11-destroy.html"><span class="application">pkcs11-destroy</span></a></span><span class="refpurpose"> — destroy PKCS#11 objects</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.pkcs11-list.html"><span class="application">pkcs11-list</span></a></span><span class="refpurpose"> — list PKCS#11 objects</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.pkcs11-keygen.html"><span class="application">pkcs11-keygen</span></a></span><span class="refpurpose"> — generate keys on a PKCS#11 device</span> +</dt> +<dt> +<span class="refentrytitle"><a href="man.pkcs11-tokens.html"><span class="application">pkcs11-tokens</span></a></span><span class="refpurpose"> — list PKCS#11 available tokens</span> +</dt> +</dl></dd> +</dl> +</div> + + + + + + + + + + + + + + + + + + + + + + + + + + + + </div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> </td> +<td width="20%" align="center"> </td> +<td width="40%" align="right"> <a accesskey="n" href="Bv9ARM.ch01.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> </td> +<td width="20%" align="center"> </td> +<td width="40%" align="right" valign="top"> Chapter 1. Introduction</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/Makefile.in b/doc/arm/Makefile.in new file mode 100644 index 0000000..c79f5ab --- /dev/null +++ b/doc/arm/Makefile.in @@ -0,0 +1,66 @@ +# Copyright (C) Internet Systems Consortium, Inc. ("ISC") +# +# This Source Code Form is subject to the terms of the Mozilla Public +# License, v. 2.0. If a copy of the MPL was not distributed with this +# file, You can obtain one at http://mozilla.org/MPL/2.0/. +# +# See the COPYRIGHT file distributed with this work for additional +# information regarding copyright ownership. + +srcdir = @srcdir@ +VPATH = @srcdir@ +top_srcdir = @top_srcdir@ + +@BIND9_MAKE_RULES@ + +MANOBJS = Bv9ARM.html notes.html + +TXTOBJS = notes.txt + +PDFOBJS = Bv9ARM.pdf notes.pdf + +doc man:: ${MANOBJS} ${TXTOBJS} ${PDFOBJS} + +clean:: + rm -f Bv9ARM.aux Bv9ARM.brf Bv9ARM.glo Bv9ARM.idx Bv9ARM.toc + rm -f Bv9ARM.log Bv9ARM.out + rm -f notes.aux notes.brf notes.glo notes.idx notes.toc + rm -f notes.log notes.out + +docclean manclean maintainer-clean:: clean + rm -f *.html ${PDFOBJS} + +maintainer-clean distclean:: + rm -f releaseinfo.xml + rm -f pkgversion.xml + rm -f noteversion.xml + +# use xmllint to process include +notes.html: notes-wrapper.xml notes.xml releaseinfo.xml pkgversion.xml noteversion.xml + expand notes-wrapper.xml | ${XMLLINT} --xinclude - | \ + ${XSLTPROC} --stringparam generate.toc "" ../xsl/isc-notes-html.xsl - > notes.html + +notes.pdf: notes-wrapper.xml notes.xml releaseinfo.xml pkgversion.xml noteversion.xml + ${XSLTPROC} ${top_srcdir}/doc/xsl/pre-latex.xsl notes-wrapper.xml | \ + ${DBLATEX} -c notes.conf -Pdoc.layout="mainmatter" -o notes.pdf - + +notes.txt: notes.html + ${W3M} -dump -cols 75 -O ascii -T text/html < notes.html | \ + sed 's/ *$$//' | \ + sed -e :a -e '/^\n*$$/{$$d;N;};/\n$$/ba' > notes.txt + +# use xmllint to process include +Bv9ARM.html: Bv9ARM-book.xml releaseinfo.xml pkgversion.xml noteversion.xml + expand Bv9ARM-book.xml | ${XMLLINT} --xinclude - | \ + ${XSLTPROC} --stringparam root.filename Bv9ARM \ + ${top_srcdir}/doc/xsl/isc-docbook-chunk.xsl - + +# use xmllint to process include +Bv9ARM-all.html: Bv9ARM-book.xml releaseinfo.xml pkgversion.xml noteversion.xml + expand Bv9ARM-book.xml | ${XMLLINT} --xinclude - |\ + ${XSLTPROC} -o Bv9ARM-all.html ../xsl/isc-docbook-html.xsl - + +Bv9ARM.pdf: Bv9ARM-book.xml releaseinfo.xml pkgversion.xml noteversion.xml + expand Bv9ARM-book.xml | \ + ${XSLTPROC} ${top_srcdir}/doc/xsl/pre-latex.xsl - | \ + ${DBLATEX} -c Bv9ARM.conf -o Bv9ARM.pdf - diff --git a/doc/arm/README-SGML b/doc/arm/README-SGML new file mode 100644 index 0000000..1f2a965 --- /dev/null +++ b/doc/arm/README-SGML @@ -0,0 +1,55 @@ +Copyright (C) Internet Systems Consortium, Inc. ("ISC") + +See COPYRIGHT in the source root or http://isc.org/copyright.html for terms. + +The BIND v9 ARM master document is now kept in DocBook 5 XML format. + +Most of the ARM is in the single file "Bv9ARM-book.xml", with certain +other files included into it: + + - dlz.xml + - dnssec.xml + - libdns.xml + - logging-categories.xml + - managed-keys.xml + - notes.xml + - pkcs11.xml + - BIND man pages + +All of the published ARM formats - HTML, PDF, etc - are generated from +this master source. + +The file "notes.xml" contains the release notes for the current release. In +addition to being included in the ARM as an appendix, it is also built into +a stand-alone document: "notes.pdf" and "notes.html". + +Building these these files requires DocBook 5 and dblatex. These are +available as packages in many OS distributes; in debian, for example: + + $ sudo apt-get install docbook5-xml docbook-xml docbook-xsl-ns \ + docbook-utils dblatex + +To build all documentation, run "make doc". + +When committing changes or submitting patches, it is only necessary to +edit the XML source (i.e., the files with ".docbook" or ".xml" suffixes); +the files in HTML and man page format are built from the XML source by a +cron job. + +If you are familiar with SGML or HTML, editing the DocBook XML is quite +straightforward. You only need to know what the tags are and how to use +them. You can find a good resource either for this either online or in +printed form: + + DocBook: The Definitive Guide + By Norman Walsh and Leonard Muellner + ISBN: 156592-580-7 + 1st Edition, October 1999 + Copyright (C) 1999 by O'Reilly & Associates, Inc. All rights reserved. + +The book is available online in HTML format: + + http://docbook.org/ + +After editing documentation, it is useful to check the correctness of the +XML; this can be done using the "xmllint" utility. diff --git a/doc/arm/acl.grammar.xml b/doc/arm/acl.grammar.xml new file mode 100644 index 0000000..3d838b1 --- /dev/null +++ b/doc/arm/acl.grammar.xml @@ -0,0 +1,16 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Generated by doc/misc/docbook-options.pl --> + +<programlisting> +<command>acl</command> <replaceable>string</replaceable> { <replaceable>address_match_element</replaceable>; ... }; +</programlisting> diff --git a/doc/arm/catz.xml b/doc/arm/catz.xml new file mode 100644 index 0000000..f314b44 --- /dev/null +++ b/doc/arm/catz.xml @@ -0,0 +1,277 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<section xmlns:db="http://docbook.org/ns/docbook" version="5.0" xml:id="catz-info"><info><title>Catalog Zones</title></info> + + <para> + A "catalog zone" is a special DNS zone that contains a list of + other zones to be served, along with their configuration parameters. + Zones listed in a catalog zone are called "member zones". + When a catalog zone is loaded or transferred to a slave server + which supports this functionality, the slave server will create + the member zones automatically. When the catalog zone is updated + (for example, to add or delete member zones, or change + their configuration parameters) those changes are immediately put + into effect. Because the catalog zone is a normal DNS zone, these + configuration changes can be propagated using the standard AXFR/IXFR + zone transfer mechanism. + </para> + <para> + Catalog zones' format and behavior are specified as an internet draft + for interoperability among DNS implementations. As of this release, the + latest revision of the DNS catalog zones draft can be found here: + https://datatracker.ietf.org/doc/draft-muks-dnsop-dns-catalog-zones/ + </para> + + <section><info><title>Principle of Operation</title></info> + <para> + Normally, if a zone is to be served by a slave server, the + <filename>named.conf</filename> file on the server must list the + zone, or the zone must be added using <command>rndc addzone</command>. + In environments with a large number of slave servers and/or where + the zones being served are changing frequently, the overhead involved + in maintaining consistent zone configuration on all the slave + servers can be significant. + </para> + <para> + A catalog zone is a way to ease this administrative burden. It is a + DNS zone that lists member zones that should be served by slave servers. + When a slave server receives an update to the catalog zone, it adds, + removes, or reconfigures member zones based on the data received. + </para> + <para> + To use a catalog zone, it must first be set up as a normal zone on + the master and the on slave servers that will be configured to use + it. It must also be added to a <option>catalog-zones</option> list + in the <option>options</option> or <option>view</option> statement + in <filename>named.conf</filename>. (This is comparable to the way + a policy zone is configured as a normal zone and also listed in + a <option>response-policy</option> statement.) + </para> + <para> + To use the catalog zone feature to serve a new member zone: + <itemizedlist> + <listitem> + <para> + Set up the the member zone to be served on the master as normal. + This could be done by editing <filename>named.conf</filename>, + or by running <command>rndc addzone</command>. + </para> + </listitem> + <listitem> + <para> + Add an entry to the catalog zone for the new member zone. + This could be done by editing the catalog zone's master file + and running <command>rndc reload</command>, or by updating + the zone using <command>nsupdate</command>. + </para> + </listitem> + </itemizedlist> + The change to the catalog zone will be propagated from the master to all + slaves using the normal AXFR/IXFR mechanism. When the slave receives the + update to the catalog zone, it will detect the entry for the new member + zone, create an instance of of that zone on the slave server, and point + that instance to the <option>masters</option> specified in the catalog + zone data. The newly created member zone is a normal slave zone, so + BIND will immediately initiate a transfer of zone contents from the + master. Once complete, the slave will start serving the member zone. + </para> + <para> + Removing a member zone from a slave server requires nothing more than + deleting the member zone's entry in the catalog zone. The change to the + catalog zone is propagated to the slave server using the normal AXFR/IXFR + transfer mechanism. The slave server, on processing the update, will + notice that the member zone has been removed. It will stop serving the + zone and remove it from its list of configured zones. (Removing the + member zone from the master server has to be done in the normal way, + by editing the configuration file or running + <command>rndc delzone</command>.) + </para> + </section> + + <section><info><title>Configuring Catalog Zones</title></info> + <para> + Catalog zones are configured with a <command>catalog-zones</command> + statement in the <literal>options</literal> or <literal>view</literal> + section of <filename>named.conf</filename>. For example, + </para> +<screen> +catalog-zones { + zone "catalog.example" + default-masters { 10.53.0.1; } + in-memory no + zone-directory "catzones" + min-update-interval 10; +}; +</screen> + <para> + This statement specifies that the zone + <literal>catalog.example</literal> is a catalog zone. This zone must be + properly configured in the same view. In most configurations, it would + be a slave zone. + </para> + <para> + The options following the zone name are not required, and may be + specified in any order: + </para> + <para> + The <option>default-masters</option> option defines the default masters + for member zones listed in a catalog zone. This can be overridden by + options within a catalog zone. If no such options are included, then + member zones will transfer their contents from the servers listed in + this option. + </para> + <para> + The <option>in-memory</option> option, if set to <literal>yes</literal>, + causes member zones to be stored only in memory. This is functionally + equivalent to configuring a slave zone without a <option>file</option>. + option. The default is <literal>no</literal>; member zones' content + will be stored locally in a file whose name is automatically generated + from the view name, catalog zone name, and member zone name. + </para> + <para> + The <option>zone-directory</option> option causes local copies of + member zones' master files (if <option>in-memory</option> is not set + to <literal>yes</literal>) to be stored in the specified directory. + The default is to store zone files in the server's working directory. + A non-absolute pathname in <option>zone-directory</option> is + assumed to be relative to the working directory. + </para> + <para> + The <option>min-update-interval</option> option sets the minimum + interval between processing of updates to catalog zones, in seconds. + If an update to a catalog zone (for example, via IXFR) happens less + than <option>min-update-interval</option> seconds after the most + recent update, then the changes will not be carried out until this + interval has elapsed. The default is <literal>5</literal> seconds. + </para> + <para> + Catalog zones are defined on a per-view basis. Configuring a non-empty + <option>catalog-zones</option> statement in a view will automatically + turn on <option>allow-new-zones</option> for that view. (Note: this + means <command>rndc addzone</command> and <command>rndc delzone</command> + will also work in any view that supports catalog zones.) + </para> + </section> + + <section><info><title>Catalog Zone format</title></info> + <para> + A catalog zone is a regular DNS zone; therefore, it has to have a + single <literal>SOA</literal> and at least one <literal>NS</literal> + record. + </para> + <para> + A record stating the version of the catalog zone format is + also required. If the version number listed is not supported by + the server, then a catalog zone may not be used by that server. + </para> +<screen> +catalog.example. IN SOA . . 2016022901 900 600 86400 1 +catalog.example. IN NS nsexample. +version.catalog.example. IN TXT "1" +</screen> + <para> + Note that this record must have the domain name + version.<replaceable>catalog-zone-name</replaceable>. This illustrates + how the meaning of data stored in a catalog zone is indicated by the + the domain name label immediately before the catalog zone domain. + </para> + <para> + Catalog zone options can be set either globally for the whole catalog + zone or for a single member zone. Global options override the settings + in the configuration file and member zone options override global + options. + </para> + <para> + Global options are set at the apex of the catalog zone, e.g.: +</para> +<screen> + masters.catalog.example. IN AAAA 2001:db8::1 +</screen> + <para>BIND currently supports the following options:</para> + <itemizedlist> + <listitem> + <para>A simple <option>masters</option> definition:</para> + <screen> + masters.catalog.example. IN A 192.0.2.1 + </screen> + <para> + This option defines a master server for the member zones - it + can be either an A or AAAA record. If multiple masters are set the + order in which they are used is random. + </para> + </listitem> + <listitem> + <para>A <option>masters</option> with a TSIG key defined:</para> + <screen> + label.masters.catalog.example. IN A 192.0.2.2 + label.masters.catalog.example. IN TXT "tsig_key_name" + </screen> + <para> + This option defines a master server for the member zone with a TSIG + key set. The TSIG key must be configured in the configuration file. + <option>label</option> can be any valid DNS label. + </para> + </listitem> + <listitem> + <para><option>allow-query</option> and + <option>allow-transfer</option> ACLs:</para> + <screen> + allow-query.catalog.example. IN APL 1:10.0.0.1/24 + allow-transfer.catalog.example. IN APL !1:10.0.0.1/32 1:10.0.0.0/24 + </screen> + <para> + These options are the equivalents of <option>allow-query</option> + and <option>allow-transfer</option> in a zone declaration in the + <filename>named.conf</filename> configuration file. The ACL is + processed in order - if there's no match to any rule the default + policy is to deny access. For the syntax of the APL RR see RFC + 3123 + </para> + </listitem> + </itemizedlist> + <para> + A member zone is added by including a <literal>PTR</literal> + resource record in the <literal>zones</literal> sub-domain of the + catalog zone. The record label is a <literal>SHA-1</literal> hash + of the member zone name in wire format. The target of the PTR + record is the member zone name. For example, to add the member + zone <literal>domain.example</literal>: + </para> +<screen> +5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN PTR domain.example. +</screen> + <para> + The hash is necessary to identify options for a specific member + zone. The member zone-specific options are defined the same way as + global options, but in the member zone subdomain: + </para> +<screen> +masters.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN A 192.0.2.2 +label.masters.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN AAAA 2001:db8::2 +label.masters.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN TXT "tsig_key" +allow-query.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN APL 1:10.0.0.0/24 +</screen> + <para> + As would be expected, options defined for a specific zone override + the global options defined in the catalog zone. These in turn override + the global options defined in the <literal>catalog-zones</literal> + statement in the configuration file. + </para> + <para> + (Note that none of the global records an option will be inherited if + any records are defined for that option for the specific zone. For + example, if the zone had a <literal>masters</literal> record of type + A but not AAAA, then it would <emphasis>not</emphasis> inherit the + type AAAA record from the global option.) + </para> + </section> +</section> diff --git a/doc/arm/controls.grammar.xml b/doc/arm/controls.grammar.xml new file mode 100644 index 0000000..df4accf --- /dev/null +++ b/doc/arm/controls.grammar.xml @@ -0,0 +1,26 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Generated by doc/misc/docbook-options.pl --> + +<programlisting> +<command>controls</command> { + <command>inet</command> ( <replaceable>ipv4_address</replaceable> | <replaceable>ipv6_address</replaceable> | + * ) [ port ( <replaceable>integer</replaceable> | * ) ] allow + { <replaceable>address_match_element</replaceable>; ... } [ + <command>keys</command> { <replaceable>string</replaceable>; ... } ] [ read-only + <replaceable>boolean</replaceable> ]; + <command>unix</command> <replaceable>quoted_string</replaceable> perm <replaceable>integer</replaceable> + <command>owner</command> <replaceable>integer</replaceable> group <replaceable>integer</replaceable> [ + <command>keys</command> { <replaceable>string</replaceable>; ... } ] [ read-only + <replaceable>boolean</replaceable> ]; +}; +</programlisting> diff --git a/doc/arm/delegation-only.zoneopt.xml b/doc/arm/delegation-only.zoneopt.xml new file mode 100644 index 0000000..a26ce24 --- /dev/null +++ b/doc/arm/delegation-only.zoneopt.xml @@ -0,0 +1,17 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Generated by doc/misc/docbook-zoneopt.pl --> +<programlisting> +<command>zone</command> <replaceable>string</replaceable> [ <replaceable>class</replaceable> ] { + <command>type</command> delegation-only; +}; +</programlisting> diff --git a/doc/arm/dlz.xml b/doc/arm/dlz.xml new file mode 100644 index 0000000..93ee5db --- /dev/null +++ b/doc/arm/dlz.xml @@ -0,0 +1,148 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Converted by db4-upgrade version 1.0 --> +<section xmlns:db="http://docbook.org/ns/docbook" version="5.0" xml:id="dlz-info"><info><title>DLZ (Dynamically Loadable Zones)</title></info> + + <para> + DLZ (Dynamically Loadable Zones) is an extension to BIND 9 that allows + zone data to be retrieved directly from an external database. There is + no required format or schema. DLZ drivers exist for several different + database backends including PostgreSQL, MySQL, and LDAP and can be + written for any other. + </para> + <para> + Historically, DLZ drivers had to be statically linked with the <command>named</command> + binary and were turned on via a configure option at compile time (for + example, <userinput>"configure --with-dlz-ldap"</userinput>). + Currently, the drivers provided in the BIND 9 tarball in + <filename>contrib/dlz/drivers</filename> are still linked this + way. + </para> + <para> + In BIND 9.8 and higher, it is possible to link some DLZ modules + dynamically at runtime, via the DLZ "dlopen" driver, which acts as a + generic wrapper around a shared object implementing the DLZ API. The + "dlopen" driver is linked into <command>named</command> by default, so configure options + are no longer necessary when using these dynamically linkable drivers, + but are still needed for the older drivers in + <filename>contrib/dlz/drivers</filename>. + </para> + + <para> + When the DLZ module provides data to <command>named</command>, it does so in text format. + The response is converted to DNS wire format by <command>named</command>. This + conversion, and the lack of any internal caching, places significant + limits on the query performance of DLZ modules. Consequently, DLZ is + not recommended for use on high-volume servers. However, it can be + used in a hidden master configuration, with slaves retrieving zone + updates via AXFR. (Note, however, that DLZ has no built-in support for + DNS notify; slaves are not automatically informed of changes to the + zones in the database.) + </para> + + <section><info><title>Configuring DLZ</title></info> + + <para> + A DLZ database is configured with a <command>dlz</command> + statement in <filename>named.conf</filename>: + </para> + <screen> + dlz example { + database "dlopen driver.so <option>args</option>"; + search yes; + }; + </screen> + <para> + This specifies a DLZ module to search when answering queries; the + module is implemented in <filename>driver.so</filename> and is + loaded at runtime by the dlopen DLZ driver. Multiple + <command>dlz</command> statements can be specified; when + answering a query, all DLZ modules with <option>search</option> + set to <literal>yes</literal> will be queried to find out if + they contain an answer for the query name; the best available + answer will be returned to the client. + </para> + <para> + The <option>search</option> option in the above example can be + omitted, because <literal>yes</literal> is the default value. + </para> + <para> + If <option>search</option> is set to <literal>no</literal>, then + this DLZ module is <emphasis>not</emphasis> searched for the best + match when a query is received. Instead, zones in this DLZ must be + separately specified in a zone statement. This allows you to + configure a zone normally using standard zone option semantics, + but specify a different database back-end for storage of the + zone's data. For example, to implement NXDOMAIN redirection using + a DLZ module for back-end storage of redirection rules: + </para> + <screen> + dlz other { + database "dlopen driver.so <option>args</option>"; + search no; + }; + + zone "." { + type redirect; + dlz other; + }; + </screen> + </section> + <section><info><title>Sample DLZ Driver</title></info> + + <para> + For guidance in implementation of DLZ modules, the directory + <filename>contrib/dlz/example</filename> contains a basic + dynamically-linkable DLZ module--i.e., one which can be + loaded at runtime by the "dlopen" DLZ driver. + The example sets up a single zone, whose name is passed + to the module as an argument in the <command>dlz</command> + statement: + </para> + <screen> + dlz other { + database "dlopen driver.so example.nil"; + }; + </screen> + <para> + In the above example, the module is configured to create a zone + "example.nil", which can answer queries and AXFR requests, and + accept DDNS updates. At runtime, prior to any updates, the zone + contains an SOA, NS, and a single A record at the apex: + </para> + <screen> + example.nil. 3600 IN SOA example.nil. hostmaster.example.nil. ( + 123 900 600 86400 3600 + ) + example.nil. 3600 IN NS example.nil. + example.nil. 1800 IN A 10.53.0.1 + </screen> + <para> + The sample driver is capable of retrieving information about the + querying client, and altering its response on the basis of this + information. To demonstrate this feature, the example driver + responds to queries for "source-addr.<option>zonename</option>>/TXT" + with the source address of the query. Note, however, that this + record will *not* be included in AXFR or ANY responses. Normally, + this feature would be used to alter responses in some other fashion, + e.g., by providing different address records for a particular name + depending on the network from which the query arrived. + </para> + <para> + Documentation of the DLZ module API can be found in + <filename>contrib/dlz/example/README</filename>. This directory also + contains the header file <filename>dlz_minimal.h</filename>, which + defines the API and should be included by any dynamically-linkable + DLZ module. + </para> + </section> +</section> diff --git a/doc/arm/dnssec.xml b/doc/arm/dnssec.xml new file mode 100644 index 0000000..de922dc --- /dev/null +++ b/doc/arm/dnssec.xml @@ -0,0 +1,286 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Converted by db4-upgrade version 1.0 --> +<section xmlns:db="http://docbook.org/ns/docbook" version="5.0" xml:id="dnssec.dynamic.zones"><info><title>DNSSEC, Dynamic Zones, and Automatic Signing</title></info> + + <section><info><title>Converting from insecure to secure</title></info> + + </section> + <para>Changing a zone from insecure to secure can be done in two + ways: using a dynamic DNS update, or the + <command>auto-dnssec</command> zone option.</para> + <para>For either method, you need to configure + <command>named</command> so that it can see the + <filename>K*</filename> files which contain the public and private + parts of the keys that will be used to sign the zone. These files + will have been generated by + <command>dnssec-keygen</command>. You can do this by placing them + in the key-directory, as specified in + <filename>named.conf</filename>:</para> + <programlisting> + zone example.net { + type master; + update-policy local; + file "dynamic/example.net/example.net"; + key-directory "dynamic/example.net"; + }; +</programlisting> + <para>If one KSK and one ZSK DNSKEY key have been generated, this + configuration will cause all records in the zone to be signed + with the ZSK, and the DNSKEY RRset to be signed with the KSK as + well. An NSEC chain will be generated as part of the initial + signing process.</para> + <section><info><title>Dynamic DNS update method</title></info> + + </section> + <para>To insert the keys via dynamic update:</para> + <screen> + % nsupdate + > ttl 3600 + > update add example.net DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8= + > update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk= + > send +</screen> + <para>While the update request will complete almost immediately, + the zone will not be completely signed until + <command>named</command> has had time to walk the zone and + generate the NSEC and RRSIG records. The NSEC record at the apex + will be added last, to signal that there is a complete NSEC + chain.</para> + <para>If you wish to sign using NSEC3 instead of NSEC, you should + add an NSEC3PARAM record to the initial update request. If you + wish the NSEC3 chain to have the OPTOUT bit set, set it in the + flags field of the NSEC3PARAM record.</para> + <screen> + % nsupdate + > ttl 3600 + > update add example.net DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8= + > update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk= + > update add example.net NSEC3PARAM 1 1 100 1234567890 + > send +</screen> + <para>Again, this update request will complete almost + immediately; however, the record won't show up until + <command>named</command> has had a chance to build/remove the + relevant chain. A private type record will be created to record + the state of the operation (see below for more details), and will + be removed once the operation completes.</para> + <para>While the initial signing and NSEC/NSEC3 chain generation + is happening, other updates are possible as well.</para> + <section><info><title>Fully automatic zone signing</title></info> + + </section> + <para>To enable automatic signing, add the + <command>auto-dnssec</command> option to the zone statement in + <filename>named.conf</filename>. + <command>auto-dnssec</command> has two possible arguments: + <constant>allow</constant> or + <constant>maintain</constant>.</para> + <para>With + <command>auto-dnssec allow</command>, + <command>named</command> can search the key directory for keys + matching the zone, insert them into the zone, and use them to + sign the zone. It will do so only when it receives an + <command>rndc sign <zonename></command>.</para> + <para> + <!-- TODO: this is repeated in the ARM --> + <command>auto-dnssec maintain</command> includes the above + functionality, but will also automatically adjust the zone's + DNSKEY records on schedule according to the keys' timing metadata. + (See <xref linkend="man.dnssec-keygen"/> and + <xref linkend="man.dnssec-settime"/> for more information.) + </para> + <para> + <command>named</command> will periodically search the key directory + for keys matching the zone, and if the keys' metadata indicates + that any change should be made the zone, such as adding, removing, + or revoking a key, then that action will be carried out. By default, + the key directory is checked for changes every 60 minutes; this period + can be adjusted with the <option>dnssec-loadkeys-interval</option>, up + to a maximum of 24 hours. The <command>rndc loadkeys</command> forces + <command>named</command> to check for key updates immediately. + </para> + <para> + If keys are present in the key directory the first time the zone + is loaded, the zone will be signed immediately, without waiting for an + <command>rndc sign</command> or <command>rndc loadkeys</command> + command. (Those commands can still be used when there are unscheduled + key changes, however.) + </para> + <para> + When new keys are added to a zone, the TTL is set to match that + of any existing DNSKEY RRset. If there is no existing DNSKEY RRset, + then the TTL will be set to the TTL specified when the key was + created (using the <command>dnssec-keygen -L</command> option), if + any, or to the SOA TTL. + </para> + <para> + If you wish the zone to be signed using NSEC3 instead of NSEC, + submit an NSEC3PARAM record via dynamic update prior to the + scheduled publication and activation of the keys. If you wish the + NSEC3 chain to have the OPTOUT bit set, set it in the flags field + of the NSEC3PARAM record. The NSEC3PARAM record will not appear in + the zone immediately, but it will be stored for later reference. When + the zone is signed and the NSEC3 chain is completed, the NSEC3PARAM + record will appear in the zone. + </para> + <para>Using the + <command>auto-dnssec</command> option requires the zone to be + configured to allow dynamic updates, by adding an + <command>allow-update</command> or + <command>update-policy</command> statement to the zone + configuration. If this has not been done, the configuration will + fail.</para> + <section><info><title>Private-type records</title></info> + + </section> + <para>The state of the signing process is signaled by + private-type records (with a default type value of 65534). When + signing is complete, these records will have a nonzero value for + the final octet (for those records which have a nonzero initial + octet).</para> + <para>The private type record format: If the first octet is + non-zero then the record indicates that the zone needs to be + signed with the key matching the record, or that all signatures + that match the record should be removed.</para> + <para> + <literallayout> +<!-- TODO: how to format this? --> + algorithm (octet 1) + key id in network order (octet 2 and 3) + removal flag (octet 4) + complete flag (octet 5) +</literallayout> + </para> + <para>Only records flagged as "complete" can be removed via + dynamic update. Attempts to remove other private type records + will be silently ignored.</para> + <para>If the first octet is zero (this is a reserved algorithm + number that should never appear in a DNSKEY record) then the + record indicates changes to the NSEC3 chains are in progress. The + rest of the record contains an NSEC3PARAM record. The flag field + tells what operation to perform based on the flag bits.</para> + <para> + <literallayout> +<!-- TODO: how to format this? --> + 0x01 OPTOUT + 0x80 CREATE + 0x40 REMOVE + 0x20 NONSEC +</literallayout> + </para> + <section><info><title>DNSKEY rollovers</title></info> + + </section> + <para>As with insecure-to-secure conversions, rolling DNSSEC + keys can be done in two ways: using a dynamic DNS update, or the + <command>auto-dnssec</command> zone option.</para> + <section><info><title>Dynamic DNS update method</title></info> + + </section> + <para> To perform key rollovers via dynamic update, you need to add + the <filename>K*</filename> files for the new keys so that + <command>named</command> can find them. You can then add the new + DNSKEY RRs via dynamic update. + <command>named</command> will then cause the zone to be signed + with the new keys. When the signing is complete the private type + records will be updated so that the last octet is non + zero.</para> + <para>If this is for a KSK you need to inform the parent and any + trust anchor repositories of the new KSK.</para> + <para>You should then wait for the maximum TTL in the zone before + removing the old DNSKEY. If it is a KSK that is being updated, + you also need to wait for the DS RRset in the parent to be + updated and its TTL to expire. This ensures that all clients will + be able to verify at least one signature when you remove the old + DNSKEY.</para> + <para>The old DNSKEY can be removed via UPDATE. Take care to + specify the correct key. + <command>named</command> will clean out any signatures generated + by the old key after the update completes.</para> + <section><info><title>Automatic key rollovers</title></info> + + </section> + <para>When a new key reaches its activation date (as set by + <command>dnssec-keygen</command> or <command>dnssec-settime</command>), + if the <command>auto-dnssec</command> zone option is set to + <constant>maintain</constant>, <command>named</command> will + automatically carry out the key rollover. If the key's algorithm + has not previously been used to sign the zone, then the zone will + be fully signed as quickly as possible. However, if the new key + is replacing an existing key of the same algorithm, then the + zone will be re-signed incrementally, with signatures from the + old key being replaced with signatures from the new key as their + signature validity periods expire. By default, this rollover + completes in 30 days, after which it will be safe to remove the + old key from the DNSKEY RRset.</para> + <section><info><title>NSEC3PARAM rollovers via UPDATE</title></info> + + </section> + <para>Add the new NSEC3PARAM record via dynamic update. When the + new NSEC3 chain has been generated, the NSEC3PARAM flag field + will be zero. At this point you can remove the old NSEC3PARAM + record. The old chain will be removed after the update request + completes.</para> + <section><info><title>Converting from NSEC to NSEC3</title></info> + + </section> + <para>To do this, you just need to add an NSEC3PARAM record. When + the conversion is complete, the NSEC chain will have been removed + and the NSEC3PARAM record will have a zero flag field. The NSEC3 + chain will be generated before the NSEC chain is + destroyed.</para> + <section><info><title>Converting from NSEC3 to NSEC</title></info> + + </section> + <para>To do this, use <command>nsupdate</command> to + remove all NSEC3PARAM records with a zero flag + field. The NSEC chain will be generated before the NSEC3 chain is + removed.</para> + <section><info><title>Converting from secure to insecure</title></info> + + </section> + <para>To convert a signed zone to unsigned using dynamic DNS, + delete all the DNSKEY records from the zone apex using + <command>nsupdate</command>. All signatures, NSEC or NSEC3 chains, + and associated NSEC3PARAM records will be removed automatically. + This will take place after the update request completes.</para> + <para> This requires the + <command>dnssec-secure-to-insecure</command> option to be set to + <userinput>yes</userinput> in + <filename>named.conf</filename>.</para> + <para>In addition, if the <command>auto-dnssec maintain</command> + zone statement is used, it should be removed or changed to + <command>allow</command> instead (or it will re-sign). + </para> + <section><info><title>Periodic re-signing</title></info> + + </section> + <para>In any secure zone which supports dynamic updates, <command>named</command> + will periodically re-sign RRsets which have not been re-signed as + a result of some update action. The signature lifetimes will be + adjusted so as to spread the re-sign load over time rather than + all at once.</para> + <section><info><title>NSEC3 and OPTOUT</title></info> + + </section> + <para> + <command>named</command> only supports creating new NSEC3 chains + where all the NSEC3 records in the zone have the same OPTOUT + state. + <command>named</command> supports UPDATES to zones where the NSEC3 + records in the chain have mixed OPTOUT state. + <command>named</command> does not support changing the OPTOUT + state of an individual NSEC3 record, the entire chain needs to be + changed if the OPTOUT state of an individual NSEC3 needs to be + changed.</para> +</section> diff --git a/doc/arm/dyndb.xml b/doc/arm/dyndb.xml new file mode 100644 index 0000000..a9c5b49 --- /dev/null +++ b/doc/arm/dyndb.xml @@ -0,0 +1,99 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Converted by db4-upgrade version 1.0 --> +<section xmlns:db="http://docbook.org/ns/docbook" version="5.0" xml:id="dyndb-info"><info><title>DynDB (Dynamic Database)</title></info> + + <para> + DynDB is an extension to BIND 9 which, like DLZ + (see <xref linkend="dlz-info"/>), allows zone data to be + retrieved from an external database. Unlike DLZ, a DynDB module + provides a full-featured BIND zone database interface. Where + DLZ translates DNS queries into real-time database lookups, + resulting in relatively poor query performance, and is unable + to handle DNSSEC-signed data due to its limited API, a DynDB + module can pre-load an in-memory database from the external + data source, providing the same performance and functionality + as zones served natively by BIND. + </para> + <para> + A DynDB module supporting LDAP has been created by Red Hat + and is available from + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://fedorahosted.org/bind-dyndb-ldap/">https://fedorahosted.org/bind-dyndb-ldap/</link>. + </para> + <para> + A sample DynDB module for testing and developer guidance + is included with the BIND source code, in the directory + <filename>bin/tests/system/dyndb/driver</filename>. + </para> + + <section><info><title>Configuring DynDB</title></info> + + <para> + A DynDB database is configured with a <command>dyndb</command> + statement in <filename>named.conf</filename>: + </para> + <screen> + dyndb example "driver.so" { + <replaceable>parameters</replaceable> + }; + </screen> + <para> + The file <filename>driver.so</filename> is a DynDB module which + implements the full DNS database API. Multiple + <command>dyndb</command> statements can be specified, to load + different drivers or multiple instances of the same driver. + Zones provided by a DynDB module are added to the view's zone + table, and are treated as normal authoritative zones when BIND + is responding to queries. Zone configuration is handled internally + by the DynDB module. + </para> + <para> + The <replaceable>parameters</replaceable> are passed as an opaque + string to the DynDB module's initialization routine. Configuration + syntax will differ depending on the driver. + </para> + </section> + <section><info><title>Sample DynDB Module</title></info> + + <para> + For guidance in implementation of DynDB modules, the directory + <filename>bin/tests/system/dyndb/driver</filename>. + contains a basic DynDB module. + The example sets up two zones, whose names are passed + to the module as arguments in the <command>dyndb</command> + statement: + </para> + <screen> + dyndb sample "sample.so" { example.nil. arpa. }; + </screen> + <para> + In the above example, the module is configured to create a zone + "example.nil", which can answer queries and AXFR requests, and + accept DDNS updates. At runtime, prior to any updates, the zone + contains an SOA, NS, and a single A record at the apex: + </para> + <screen> + example.nil. 86400 IN SOA example.nil. example.nil. ( + 0 28800 7200 604800 86400 + ) + example.nil. 86400 IN NS example.nil. + example.nil. 86400 IN A 127.0.0.1 + </screen> + <para> + When the zone is updated dynamically, the DynDB module will determine + whether the updated RR is an address (i.e., type A or AAAA) and if + so, it will automatically update the corresponding PTR record in a + reverse zone. (Updates are not stored permanently; all updates are + lost when the server is restarted.) + </para> + </section> +</section> diff --git a/doc/arm/forward.zoneopt.xml b/doc/arm/forward.zoneopt.xml new file mode 100644 index 0000000..429bbca --- /dev/null +++ b/doc/arm/forward.zoneopt.xml @@ -0,0 +1,20 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Generated by doc/misc/docbook-zoneopt.pl --> +<programlisting> +<command>zone</command> <replaceable>string</replaceable> [ <replaceable>class</replaceable> ] { + <command>type</command> forward; + <command>delegation-only</command> <replaceable>boolean</replaceable>; + <command>forward</command> ( first | only ); + <command>forwarders</command> [ port <replaceable>integer</replaceable> ] [ dscp <replaceable>integer</replaceable> ] { ( <replaceable>ipv4_address</replaceable> | <replaceable>ipv6_address</replaceable> ) [ port <replaceable>integer</replaceable> ] [ dscp <replaceable>integer</replaceable> ]; ... }; +}; +</programlisting> diff --git a/doc/arm/hint.zoneopt.xml b/doc/arm/hint.zoneopt.xml new file mode 100644 index 0000000..c1b4fad --- /dev/null +++ b/doc/arm/hint.zoneopt.xml @@ -0,0 +1,20 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Generated by doc/misc/docbook-zoneopt.pl --> +<programlisting> +<command>zone</command> <replaceable>string</replaceable> [ <replaceable>class</replaceable> ] { + <command>type</command> hint; + <command>check-names</command> ( fail | warn | ignore ); + <command>delegation-only</command> <replaceable>boolean</replaceable>; + <command>file</command> <replaceable>quoted_string</replaceable>; +}; +</programlisting> diff --git a/doc/arm/in-view.zoneopt.xml b/doc/arm/in-view.zoneopt.xml new file mode 100644 index 0000000..a91b6f3 --- /dev/null +++ b/doc/arm/in-view.zoneopt.xml @@ -0,0 +1,17 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Generated by doc/misc/docbook-zoneopt.pl --> +<programlisting> +<command>zone</command> <replaceable>string</replaceable> [ <replaceable>class</replaceable> ] { + <command>in-view</command> <replaceable>string</replaceable>; +}; +</programlisting> diff --git a/doc/arm/isc-logo.pdf b/doc/arm/isc-logo.pdf Binary files differnew file mode 100644 index 0000000..17d38a8 --- /dev/null +++ b/doc/arm/isc-logo.pdf diff --git a/doc/arm/key.grammar.xml b/doc/arm/key.grammar.xml new file mode 100644 index 0000000..33cc23a --- /dev/null +++ b/doc/arm/key.grammar.xml @@ -0,0 +1,19 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Generated by doc/misc/docbook-options.pl --> + +<programlisting> +<command>key</command> <replaceable>string</replaceable> { + <command>algorithm</command> <replaceable>string</replaceable>; + <command>secret</command> <replaceable>string</replaceable>; +}; +</programlisting> diff --git a/doc/arm/libdns.xml b/doc/arm/libdns.xml new file mode 100644 index 0000000..4562f6a --- /dev/null +++ b/doc/arm/libdns.xml @@ -0,0 +1,518 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Converted by db4-upgrade version 1.0 --> +<section xmlns:db="http://docbook.org/ns/docbook" version="5.0" xml:id="bind9.library"> + <info> + <title>BIND 9 DNS Library Support</title> + </info> + <para> + This version of BIND 9 "exports" its internal libraries so + that they can be used by third-party applications more easily (we + call them "export" libraries in this document). Certain library + functions are altered from specific BIND-only behavior to more generic + behavior when used by other applications; to enable this generic behavior, + the calling program initializes the libraries by calling + <command>isc_lib_register()</command>. + </para> + <para> + In addition to DNS-related APIs that are used within BIND 9, the + libraries provide the following features: + </para> + <itemizedlist> + <listitem> + <para> + The "DNS client" module. This is a higher level API that + provides an interface to name resolution, single DNS transaction + with a particular server, and dynamic update. Regarding name + resolution, it supports advanced features such as DNSSEC validation + and caching. This module supports both synchronous and asynchronous + mode. + </para> + </listitem> + <listitem> + <para> + The "IRS" (Information Retrieval System) library. It provides an + interface to parse the traditional <filename>resolv.conf</filename> + file and more advanced, DNS-specific configuration file for the + rest of this package (see the description for the + <filename>dns.conf</filename> file below). + </para> + </listitem> + <listitem> + <para> + As part of the IRS library, the standard address-name + mapping functions, <command>getaddrinfo()</command> and + <command>getnameinfo()</command>, are provided. They use the + DNSSEC-aware validating resolver backend, and could use other + advanced features of the BIND 9 libraries such as caching. The + <command>getaddrinfo()</command> function resolves both A + and AAAA RRs concurrently when the address family is + unspecified. + </para> + </listitem> + <listitem> + <para> + An experimental framework to support other event + libraries than BIND 9's internal event task system. + </para> + </listitem> + </itemizedlist> + <section> + <info> + <title>Installation</title> + </info> + <screen> +$ <userinput>make install</userinput> + </screen> + <para> + Normal installation of BIND will also install library object + and header files. Root privilege is normally required. + </para> + <para> + To see how to build your own application after the installation, see + <filename>lib/samples/Makefile-postinstall.in</filename>. + </para> + </section> + <section> + <info> + <title>Known Defects/Restrictions</title> + </info> + <itemizedlist> + <listitem> + <para> + The "fixed" RRset order is not (currently) supported in the export + library. If you want to use "fixed" RRset order for, e.g. + <command>named</command> while still building the export library + even without the fixed order support, build them separately: + <screen> +$ <userinput>./configure --enable-fixed-rrset <replaceable>[other flags, but not --enable-exportlib]</replaceable></userinput> +$ <userinput>make</userinput> +$ <userinput>./configure --enable-exportlib <replaceable>[other flags, but not --enable-fixed-rrset]</replaceable></userinput> +$ <userinput>cd lib/export</userinput> +$ <userinput>make</userinput> +</screen> + </para> + </listitem> + <listitem> + <para> + RFC 5011 is not supported in the validating stub resolver of the + export library. In fact, it is not clear whether it should: trust + anchors would be a system-wide configuration which would be managed + by an administrator, while the stub resolver will be used by + ordinary applications run by a normal user. + </para> + </listitem> + <listitem> + <para> + Not all common <filename>/etc/resolv.conf</filename> options are + supported in the IRS library. The only available options in this + version are <command>debug</command> and <command>ndots</command>. + </para> + </listitem> + </itemizedlist> + </section> + <section> + <info> + <title>The dns.conf File</title> + </info> + <para> + The IRS library supports an "advanced" configuration file related to + the DNS library for configuration parameters that would be beyond the + capability of the <filename>resolv.conf</filename> file. + Specifically, it is intended to provide DNSSEC related configuration + parameters. By default the path to this configuration file is + <filename>/etc/dns.conf</filename>. This module is very experimental + and the configuration syntax or library interfaces may change in + future versions. Currently, only the <command>trusted-keys</command> + statement is supported, whose syntax is the same as the same + statement in <filename>named.conf</filename>. (See + <xref linkend="trusted-keys"/> for details.) + </para> + </section> + <section> + <info> + <title>Sample Applications</title> + </info> + <para> + Some sample application programs using this API are provided for + reference. The following is a brief description of these + applications. + </para> + <section> + <info> + <title>sample: a simple stub resolver utility</title> + </info> + <para> + Sends a query of a given name (of a given optional RR type) to a + specified recursive server and prints the result as a list of RRs. + It can also act as a validating stub resolver if a trust anchor is + given via a set of command line options. + </para> + <para> + Usage: sample [options] server_address hostname + </para> + <para> + Options and Arguments: + </para> + <variablelist> + <varlistentry> + <term>-t RRtype</term> + <listitem> + <para> + specify the RR type of the query. The default is the A RR. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>[-a algorithm] [-e] -k keyname -K keystring</term> + <listitem> + <para> + specify a command-line DNS key to validate the answer. For + example, to specify the following DNSKEY of example.com: + <literallayout> + example.com. 3600 IN DNSKEY 257 3 5 xxx + </literallayout> + specify the options as follows: + <screen> +<userinput>-e -k example.com -K "xxx"</userinput> + </screen> + -e means that this key is a zone's "key signing key" (also known + as "secure entry point"). + When -a is omitted rsasha1 will be used by default. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-s domain:alt_server_address</term> + <listitem> + <para> + specify a separate recursive server address for the specific + "domain". Example: -s example.com:2001:db8::1234 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>server_address</term> + <listitem> + <para> + an IP(v4/v6) address of the recursive server to which queries + are sent. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>hostname</term> + <listitem> + <para> + the domain name for the query + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section> + <info> + <title>sample-async: a simple stub resolver, working asynchronously</title> + </info> + <para> + Similar to "sample", but accepts a list + of (query) domain names as a separate file and resolves the names + asynchronously.</para> + <para> + Usage: sample-async [-s server_address] [-t RR_type] input_file</para> + <para> + Options and Arguments: + </para> + <variablelist> + <varlistentry> + <term>-s server_address</term> + <listitem> + an IPv4 address of the recursive server to which queries are sent. + (IPv6 addresses are not supported in this implementation) + </listitem> + </varlistentry> + <varlistentry> + <term>-t RR_type</term> + <listitem> + specify the RR type of the queries. The default is the A + RR. + </listitem> + </varlistentry> + <varlistentry> + <term>input_file</term> + <listitem> + a list of domain names to be resolved. each line consists of a + single domain name. Example: + <literallayout> + www.example.com + mx.example.net + ns.xxx.example + </literallayout> + </listitem> + </varlistentry> + </variablelist> + </section> + <section> + <info> + <title>sample-request: a simple DNS transaction client</title> + </info> + <para> + Sends a query to a specified server, and prints the response with + minimal processing. It doesn't act as a "stub resolver": it stops + the processing once it gets any response from the server, whether + it's a referral or an alias (CNAME or DNAME) that would require + further queries to get the ultimate answer. In other words, this + utility acts as a very simplified <command>dig</command>. + </para> + <para> + Usage: sample-request [-t RRtype] server_address hostname + </para> + <para> + Options and Arguments: + </para> + <variablelist> + <varlistentry> + <term>-t RRtype</term> + <listitem> + <para> + specify the RR type of the queries. The default is the A RR. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>server_address</term> + <listitem> + <para> + an IP(v4/v6) address of the recursive server to which + the query is sent. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>hostname</term> + <listitem> + <para> + the domain name for the query + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section> + <info> + <title>sample-gai: getaddrinfo() and getnameinfo() test code</title> + </info> + <para> + This is a test program to check <command>getaddrinfo()</command> and + <command>getnameinfo()</command> behavior. It takes a host name as an + argument, calls <command>getaddrinfo()</command> with the given host + name, and calls <command>getnameinfo()</command> with the resulting + IP addresses returned by <command>getaddrinfo()</command>. If the + dns.conf file exists and defines a trust anchor, the underlying + resolver will act as a validating resolver, and + <command>getaddrinfo()</command>/<command>getnameinfo()</command> + will fail with an EAI_INSECUREDATA error when DNSSEC validation + fails. + </para> + <para> + Usage: sample-gai hostname + </para> + </section> + <section> + <info> + <title>sample-update: a simple dynamic update client program</title> + </info> + <para> + Accepts a single update command as a command-line argument, sends + an update request message to the authoritative server, and shows + the response from the server. In other words, this is a simplified + <command>nsupdate</command>. + </para> + <para> + Usage: sample-update [options] (add|delete) "update data" + </para> + <para> + Options and Arguments: + </para> + <variablelist> + <varlistentry> + <term>-a auth_server</term> + <listitem> + <para> + An IP address of the authoritative server that has authority + for the zone containing the update name. This should + normally be the primary authoritative server that accepts + dynamic updates. It can also be a secondary server that is + configured to forward update requests to the primary server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-k keyfile</term> + <listitem> + <para> + A TSIG key file to secure the update transaction. The + keyfile format is the same as that for the nsupdate utility. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-p prerequisite</term> + <listitem> + <para> + A prerequisite for the update (only one prerequisite can be + specified). The prerequisite format is the same as that is + accepted by the nsupdate utility. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-r recursive_server</term> + <listitem> + <para> + An IP address of a recursive server that this utility will + use. A recursive server may be necessary to identify the + authoritative server address to which the update request is + sent. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-z zonename</term> + <listitem> + <para> + The domain name of the zone that contains + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>(add|delete)</term> + <listitem> + <para> + Specify the type of update operation. Either "add" or + "delete" must be specified. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>"update data"</term> + <listitem> + <para> + Specify the data to be updated. A typical example of the + data would look like "name TTL RRtype RDATA". + </para> + </listitem> + </varlistentry> + </variablelist> + <note> + <simpara> + In practice, either -a or -r must be specified. Others can be + optional; the underlying library routine tries to identify the + appropriate server and the zone name for the update. + </simpara> + </note> + <para> + Examples: assuming the primary authoritative server of the + dynamic.example.com zone has an IPv6 address 2001:db8::1234, + </para> + <screen> +$ <userinput>sample-update -a sample-update -k Kxxx.+nnn+mmmm.key add "foo.dynamic.example.com 30 IN A 192.168.2.1"</userinput></screen> + <para> + adds an A RR for foo.dynamic.example.com using the given key. + </para> + <screen> +$ <userinput>sample-update -a sample-update -k Kxxx.+nnn+mmmm.key delete "foo.dynamic.example.com 30 IN A"</userinput></screen> + <para> + removes all A RRs for foo.dynamic.example.com using the given key. + </para> + <screen> +$ <userinput>sample-update -a sample-update -k Kxxx.+nnn+mmmm.key delete "foo.dynamic.example.com"</userinput></screen> + <para> + removes all RRs for foo.dynamic.example.com using the given key. + </para> + </section> + <section> + <info> + <title>nsprobe: domain/name server checker in terms of RFC 4074</title> + </info> + <para> + Checks a set of domains to see the name servers of the domains + behave correctly in terms of RFC 4074. This is included in the set + of sample programs to show how the export library can be used in a + DNS-related application. + </para> + <para> + Usage: nsprobe [-d] [-v [-v...]] [-c cache_address] [input_file] + </para> + <para> + Options + </para> + <variablelist> + <varlistentry> + <term>-d</term> + <listitem> + <para> + Run in "debug" mode. With this option nsprobe will dump + every RRs it receives. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-v</term> + <listitem> + <para> + Increase verbosity of other normal log messages. This can be + specified multiple times. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-c cache_address</term> + <listitem> + <para> + Specify an IP address of a recursive (caching) name server. + nsprobe uses this server to get the NS RRset of each domain + and the A and/or AAAA RRsets for the name servers. The + default value is 127.0.0.1. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>input_file</term> + <listitem> + <para> + A file name containing a list of domain (zone) names to be + probed. when omitted the standard input will be used. Each + line of the input file specifies a single domain name such as + "example.com". In general this domain name must be the apex + name of some DNS zone (unlike normal "host names" such as + "www.example.com"). nsprobe first identifies the NS RRsets + for the given domain name, and sends A and AAAA queries to + these servers for some "widely used" names under the zone; + specifically, adding "www" and "ftp" to the zone name. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + </section> + <section> + <info> + <title>Library References</title> + </info> + <para> + As of this writing, there is no formal "manual" for the libraries, + except this document, header files (some of which provide pretty + detailed explanations), and sample application programs. + </para> + </section> +</section> diff --git a/doc/arm/logging-categories.xml b/doc/arm/logging-categories.xml new file mode 100644 index 0000000..181def7 --- /dev/null +++ b/doc/arm/logging-categories.xml @@ -0,0 +1,393 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Converted by db4-upgrade version 1.0 --> +<informaltable xmlns:db="http://docbook.org/ns/docbook" version="5.0" colsep="0" rowsep="0"> + <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="4Level-table"> + <colspec colname="1" colnum="1" colsep="0" colwidth="1.150in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="3.350in"/> + <tbody> + <row rowsep="0"> + <entry colname="1"> + <para><command>client</command></para> + </entry> + <entry colname="2"> + <para> + Processing of client requests. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>cname</command></para> + </entry> + <entry colname="2"> + <para> + Logs nameservers that are skipped due to them being + a CNAME rather than A / AAAA records. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>config</command></para> + </entry> + <entry colname="2"> + <para> + Configuration file parsing and processing. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>database</command></para> + </entry> + <entry colname="2"> + <para> + Messages relating to the databases used + internally by the name server to store zone and cache + data. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>default</command></para> + </entry> + <entry colname="2"> + <para> + The default category defines the logging + options for those categories where no specific + configuration has been + defined. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>delegation-only</command></para> + </entry> + <entry colname="2"> + <para> + Delegation only. Logs queries that have been + forced to NXDOMAIN as the result of a + delegation-only zone or a + <command>delegation-only</command> in a + forward, hint or stub zone declaration. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>dispatch</command></para> + </entry> + <entry colname="2"> + <para> + Dispatching of incoming packets to the + server modules where they are to be processed. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>dnssec</command></para> + </entry> + <entry colname="2"> + <para> + DNSSEC and TSIG protocol processing. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>dnstap</command></para> + </entry> + <entry colname="2"> + <para> + The "dnstap" DNS traffic capture system. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>edns-disabled</command></para> + </entry> + <entry colname="2"> + <para> + Log queries that have been forced to use plain + DNS due to timeouts. This is often due to + the remote servers not being RFC 1034 compliant + (not always returning FORMERR or similar to + EDNS queries and other extensions to the DNS + when they are not understood). In other words, this is + targeted at servers that fail to respond to + DNS queries that they don't understand. + </para> + <para> + Note: the log message can also be due to + packet loss. Before reporting servers for + non-RFC 1034 compliance they should be re-tested + to determine the nature of the non-compliance. + This testing should prevent or reduce the + number of false-positive reports. + </para> + <para> + Note: eventually <command>named</command> will have to stop + treating such timeouts as due to RFC 1034 non + compliance and start treating it as plain + packet loss. Falsely classifying packet + loss as due to RFC 1034 non compliance impacts + on DNSSEC validation which requires EDNS for + the DNSSEC records to be returned. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>general</command></para> + </entry> + <entry colname="2"> + <para> + The catch-all. Many things still aren't + classified into categories, and they all end up here. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>lame-servers</command></para> + </entry> + <entry colname="2"> + <para> + Lame servers. These are misconfigurations + in remote servers, discovered by BIND 9 when trying to + query those servers during resolution. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>network</command></para> + </entry> + <entry colname="2"> + <para> + Network operations. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>notify</command></para> + </entry> + <entry colname="2"> + <para> + The NOTIFY protocol. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>queries</command></para> + </entry> + <entry colname="2"> + <para> + Specify where queries should be logged to. + </para> + <para> + At startup, specifying the category <command>queries</command> will also + enable query logging unless <command>querylog</command> option has been + specified. + </para> + + <para> + The query log entry first reports a client object + identifier in @0x<hexadecimal-number> + format. Next, it reports the client's IP + address and port number, and the query name, + class and type. Next, it reports whether the + Recursion Desired flag was set (+ if set, - + if not set), if the query was signed (S), + EDNS was in used along with the EDNS version + number (E(#)), if TCP was used (T), if DO + (DNSSEC Ok) was set (D), if CD (Checking + Disabled) was set (C), if a valid DNS Server + COOKIE was received (V), or if a DNS COOKIE + option without a valid Server COOKIE was + present (K). After this the destination + address the query was sent to is reported. + </para> + + <para> + <computeroutput>client 127.0.0.1#62536 (www.example.com): query: www.example.com IN AAAA +SE</computeroutput> + </para> + <para> + <computeroutput>client ::1#62537 (www.example.net): query: www.example.net IN AAAA -SE</computeroutput> + </para> + <para> + (The first part of this log message, showing the + client address/port number and query name, is + repeated in all subsequent log messages related + to the same query.) + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>query-errors</command></para> + </entry> + <entry colname="2"> + <para> + Information about queries that resulted in some + failure. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>rate-limit</command></para> + </entry> + <entry colname="2"> + <para> + The start, periodic, and final notices of the + rate limiting of a stream of responses are logged at + <command>info</command> severity in this category. + These messages include a hash value of the domain name + of the response and the name itself, + except when there is insufficient memory to record + the name for the final notice + The final notice is normally delayed until about one + minute after rate limit stops. + A lack of memory can hurry the final notice, + in which case it starts with an asterisk (*). + Various internal events are logged at debug 1 level + and higher. + </para> + <para> + Rate limiting of individual requests + is logged in the <command>query-errors</command> category. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>resolver</command></para> + </entry> + <entry colname="2"> + <para> + DNS resolution, such as the recursive + lookups performed on behalf of clients by a caching name + server. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>rpz</command></para> + </entry> + <entry colname="2"> + <para> + Information about errors in response policy zone files, + rewritten responses, and at the highest + <command>debug</command> levels, mere rewriting + attempts. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>security</command></para> + </entry> + <entry colname="2"> + <para> + Approval and denial of requests. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>spill</command></para> + </entry> + <entry colname="2"> + <para> + Logs queries that have been terminated, either by dropping + or responding with SERVFAIL, as a result of a fetchlimit + quota being exceeded. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>trust-anchor-telemetry</command></para> + </entry> + <entry colname="2"> + <para> + Logs trust-anchor-telemetry requests received by named. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>unmatched</command></para> + </entry> + <entry colname="2"> + <para> + Messages that <command>named</command> was unable to determine the + class of or for which there was no matching <command>view</command>. + A one line summary is also logged to the <command>client</command> category. + This category is best sent to a file or stderr, by + default it is sent to + the <command>null</command> channel. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>update</command></para> + </entry> + <entry colname="2"> + <para> + Dynamic updates. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>update-security</command></para> + </entry> + <entry colname="2"> + <para> + Approval and denial of update requests. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>xfer-in</command></para> + </entry> + <entry colname="2"> + <para> + Zone transfers the server is receiving. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para><command>xfer-out</command></para> + </entry> + <entry colname="2"> + <para> + Zone transfers the server is sending. + </para> + </entry> + </row> + </tbody> + </tgroup> +</informaltable> diff --git a/doc/arm/logging.grammar.xml b/doc/arm/logging.grammar.xml new file mode 100644 index 0000000..dd14d70 --- /dev/null +++ b/doc/arm/logging.grammar.xml @@ -0,0 +1,30 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Generated by doc/misc/docbook-options.pl --> + +<programlisting> +<command>logging</command> { + <command>category</command> <replaceable>string</replaceable> { <replaceable>string</replaceable>; ... }; + <command>channel</command> <replaceable>string</replaceable> { + <command>buffered</command> <replaceable>boolean</replaceable>; + <command>file</command> <replaceable>quoted_string</replaceable> [ versions ( "unlimited" | <replaceable>integer</replaceable> ) + ] [ size <replaceable>size</replaceable> ]; + <command>null</command>; + <command>print-category</command> <replaceable>boolean</replaceable>; + <command>print-severity</command> <replaceable>boolean</replaceable>; + <command>print-time</command> <replaceable>boolean</replaceable>; + <command>severity</command> <replaceable>log_severity</replaceable>; + <command>stderr</command>; + <command>syslog</command> [ <replaceable>syslog_facility</replaceable> ]; + }; +}; +</programlisting> diff --git a/doc/arm/man.arpaname.html b/doc/arm/man.arpaname.html new file mode 100644 index 0000000..2b1ba77 --- /dev/null +++ b/doc/arm/man.arpaname.html @@ -0,0 +1,96 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>arpaname</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.ddns-confgen.html" title="ddns-confgen"> +<link rel="next" href="man.dnstap-read.html" title="dnstap-read"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">arpaname</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.ddns-confgen.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.dnstap-read.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.arpaname"></a><div class="titlepage"></div> + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">arpaname</span> + — translate IP addresses to the corresponding ARPA names + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">arpaname</code> + {<em class="replaceable"><code>ipaddress </code></em>...} + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.31.7"></a><h2>DESCRIPTION</h2> + + <p> + <span class="command"><strong>arpaname</strong></span> translates IP addresses (IPv4 and + IPv6) to the corresponding IN-ADDR.ARPA or IP6.ARPA names. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.31.8"></a><h2>SEE ALSO</h2> + + <p> + <em class="citetitle">BIND 9 Administrator Reference Manual</em>. + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.ddns-confgen.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.dnstap-read.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">ddns-confgen</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">dnstap-read</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.ddns-confgen.html b/doc/arm/man.ddns-confgen.html new file mode 100644 index 0000000..eb01f01 --- /dev/null +++ b/doc/arm/man.ddns-confgen.html @@ -0,0 +1,241 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>ddns-confgen</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.rndc-confgen.html" title="rndc-confgen"> +<link rel="next" href="man.arpaname.html" title="arpaname"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">ddns-confgen</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.rndc-confgen.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.arpaname.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.ddns-confgen"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">ddns-confgen</span> + — ddns key generation tool + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">tsig-keygen</code> + [<code class="option">-a <em class="replaceable"><code>algorithm</code></em></code>] + [<code class="option">-h</code>] + [<code class="option">-r <em class="replaceable"><code>randomfile</code></em></code>] + [name] + </p></div> + <div class="cmdsynopsis"><p> + <code class="command">ddns-confgen</code> + [<code class="option">-a <em class="replaceable"><code>algorithm</code></em></code>] + [<code class="option">-h</code>] + [<code class="option">-k <em class="replaceable"><code>keyname</code></em></code>] + [<code class="option">-q</code>] + [<code class="option">-r <em class="replaceable"><code>randomfile</code></em></code>] + [ + -s <em class="replaceable"><code>name</code></em> + | -z <em class="replaceable"><code>zone</code></em> + ] + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.30.7"></a><h2>DESCRIPTION</h2> + + <p> + <span class="command"><strong>tsig-keygen</strong></span> and <span class="command"><strong>ddns-confgen</strong></span> + are invocation methods for a utility that generates keys for use + in TSIG signing. The resulting keys can be used, for example, + to secure dynamic DNS updates to a zone or for the + <span class="command"><strong>rndc</strong></span> command channel. + </p> + + <p> + When run as <span class="command"><strong>tsig-keygen</strong></span>, a domain name + can be specified on the command line which will be used as + the name of the generated key. If no name is specified, + the default is <code class="constant">tsig-key</code>. + </p> + + <p> + When run as <span class="command"><strong>ddns-confgen</strong></span>, the generated + key is accompanied by configuration text and instructions + that can be used with <span class="command"><strong>nsupdate</strong></span> and + <span class="command"><strong>named</strong></span> when setting up dynamic DNS, + including an example <span class="command"><strong>update-policy</strong></span> + statement. (This usage similar to the + <span class="command"><strong>rndc-confgen</strong></span> command for setting + up command channel security.) + </p> + + <p> + Note that <span class="command"><strong>named</strong></span> itself can configure a + local DDNS key for use with <span class="command"><strong>nsupdate -l</strong></span>: + it does this when a zone is configured with + <span class="command"><strong>update-policy local;</strong></span>. + <span class="command"><strong>ddns-confgen</strong></span> is only needed when a + more elaborate configuration is required: for instance, + if <span class="command"><strong>nsupdate</strong></span> is to be used from a remote + system. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.30.8"></a><h2>OPTIONS</h2> + + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-a <em class="replaceable"><code>algorithm</code></em></span></dt> +<dd> + <p> + Specifies the algorithm to use for the TSIG key. Available + choices are: hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256, + hmac-sha384 and hmac-sha512. The default is hmac-sha256. + Options are case-insensitive, and the "hmac-" prefix + may be omitted. + </p> + </dd> +<dt><span class="term">-h</span></dt> +<dd> + <p> + Prints a short summary of options and arguments. + </p> + </dd> +<dt><span class="term">-k <em class="replaceable"><code>keyname</code></em></span></dt> +<dd> + <p> + Specifies the key name of the DDNS authentication key. + The default is <code class="constant">ddns-key</code> when neither + the <code class="option">-s</code> nor <code class="option">-z</code> option is + specified; otherwise, the default + is <code class="constant">ddns-key</code> as a separate label + followed by the argument of the option, e.g., + <code class="constant">ddns-key.example.com.</code> + The key name must have the format of a valid domain name, + consisting of letters, digits, hyphens and periods. + </p> + </dd> +<dt><span class="term">-q</span></dt> +<dd> + <p> + (<span class="command"><strong>ddns-confgen</strong></span> only.) Quiet mode: Print + only the key, with no explanatory text or usage examples; + This is essentially identical to <span class="command"><strong>tsig-keygen</strong></span>. + </p> + </dd> +<dt><span class="term">-r <em class="replaceable"><code>randomfile</code></em></span></dt> +<dd> + <p> + Specifies a source of random data for generating the + authorization. If the operating system does not provide a + <code class="filename">/dev/random</code> or equivalent device, the + default source of randomness is keyboard input. + <code class="filename">randomdev</code> specifies the name of a + character device or file containing random data to be used + instead of the default. The special value + <code class="filename">keyboard</code> indicates that keyboard input + should be used. + </p> + </dd> +<dt><span class="term">-s <em class="replaceable"><code>name</code></em></span></dt> +<dd> + <p> + (<span class="command"><strong>ddns-confgen</strong></span> only.) + Generate configuration example to allow dynamic updates + of a single hostname. The example <span class="command"><strong>named.conf</strong></span> + text shows how to set an update policy for the specified + <em class="replaceable"><code>name</code></em> + using the "name" nametype. The default key name is + ddns-key.<em class="replaceable"><code>name</code></em>. + Note that the "self" nametype cannot be used, since + the name to be updated may differ from the key name. + This option cannot be used with the <code class="option">-z</code> option. + </p> + </dd> +<dt><span class="term">-z <em class="replaceable"><code>zone</code></em></span></dt> +<dd> + <p> + (<span class="command"><strong>ddns-confgen</strong></span> only.) + Generate configuration example to allow dynamic updates + of a zone: The example <span class="command"><strong>named.conf</strong></span> text + shows how to set an update policy for the specified + <em class="replaceable"><code>zone</code></em> + using the "zonesub" nametype, allowing updates to + all subdomain names within that + <em class="replaceable"><code>zone</code></em>. + This option cannot be used with the <code class="option">-s</code> option. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.30.9"></a><h2>SEE ALSO</h2> + + <p><span class="citerefentry"> + <span class="refentrytitle">nsupdate</span>(1) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">named.conf</span>(5) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">named</span>(8) + </span>, + <em class="citetitle">BIND 9 Administrator Reference Manual</em>. + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.rndc-confgen.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.arpaname.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">rndc-confgen</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">arpaname</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.delv.html b/doc/arm/man.delv.html new file mode 100644 index 0000000..f727cae --- /dev/null +++ b/doc/arm/man.delv.html @@ -0,0 +1,629 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>delv</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.host.html" title="host"> +<link rel="next" href="man.nslookup.html" title="nslookup"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center">delv</th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.host.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.nslookup.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.delv"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + delv + — DNS lookup and validation utility + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">delv</code> + [@server] + [ + [<code class="option">-4</code>] + | [<code class="option">-6</code>] + ] + [<code class="option">-a <em class="replaceable"><code>anchor-file</code></em></code>] + [<code class="option">-b <em class="replaceable"><code>address</code></em></code>] + [<code class="option">-c <em class="replaceable"><code>class</code></em></code>] + [<code class="option">-d <em class="replaceable"><code>level</code></em></code>] + [<code class="option">-i</code>] + [<code class="option">-m</code>] + [<code class="option">-p <em class="replaceable"><code>port#</code></em></code>] + [<code class="option">-q <em class="replaceable"><code>name</code></em></code>] + [<code class="option">-t <em class="replaceable"><code>type</code></em></code>] + [<code class="option">-x <em class="replaceable"><code>addr</code></em></code>] + [name] + [type] + [class] + [queryopt...] + </p></div> + + <div class="cmdsynopsis"><p> + <code class="command">delv</code> + [<code class="option">-h</code>] + </p></div> + + <div class="cmdsynopsis"><p> + <code class="command">delv</code> + [<code class="option">-v</code>] + </p></div> + + <div class="cmdsynopsis"><p> + <code class="command">delv</code> + [queryopt...] + [query...] + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.5.7"></a><h2>DESCRIPTION</h2> + + <p><span class="command"><strong>delv</strong></span> + is a tool for sending + DNS queries and validating the results, using the same internal + resolver and validator logic as <span class="command"><strong>named</strong></span>. + </p> + <p> + <span class="command"><strong>delv</strong></span> will send to a specified name server all + queries needed to fetch and validate the requested data; this + includes the original requested query, subsequent queries to follow + CNAME or DNAME chains, and queries for DNSKEY, DS and DLV records + to establish a chain of trust for DNSSEC validation. + It does not perform iterative resolution, but simulates the + behavior of a name server configured for DNSSEC validating and + forwarding. + </p> + <p> + By default, responses are validated using built-in DNSSEC trust + anchor for the root zone ("."). Records returned by + <span class="command"><strong>delv</strong></span> are either fully validated or + were not signed. If validation fails, an explanation of + the failure is included in the output; the validation process + can be traced in detail. Because <span class="command"><strong>delv</strong></span> does + not rely on an external server to carry out validation, it can + be used to check the validity of DNS responses in environments + where local name servers may not be trustworthy. + </p> + <p> + Unless it is told to query a specific name server, + <span class="command"><strong>delv</strong></span> will try each of the servers listed in + <code class="filename">/etc/resolv.conf</code>. If no usable server + addresses are found, <span class="command"><strong>delv</strong></span> will send + queries to the localhost addresses (127.0.0.1 for IPv4, ::1 + for IPv6). + </p> + <p> + When no command line arguments or options are given, + <span class="command"><strong>delv</strong></span> will perform an NS query for "." + (the root zone). + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.5.8"></a><h2>SIMPLE USAGE</h2> + + + <p> + A typical invocation of <span class="command"><strong>delv</strong></span> looks like: + </p> +<pre class="programlisting"> delv @server name type </pre> +<p> + where: + + </p> +<div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><code class="constant">server</code></span></dt> +<dd> + <p> + is the name or IP address of the name server to query. This + can be an IPv4 address in dotted-decimal notation or an IPv6 + address in colon-delimited notation. When the supplied + <em class="parameter"><code>server</code></em> argument is a hostname, + <span class="command"><strong>delv</strong></span> resolves that name before + querying that name server (note, however, that this + initial lookup is <span class="emphasis"><em>not</em></span> validated + by DNSSEC). + </p> + <p> + If no <em class="parameter"><code>server</code></em> argument is + provided, <span class="command"><strong>delv</strong></span> consults + <code class="filename">/etc/resolv.conf</code>; if an + address is found there, it queries the name server at + that address. If either of the <code class="option">-4</code> or + <code class="option">-6</code> options are in use, then + only addresses for the corresponding transport + will be tried. If no usable addresses are found, + <span class="command"><strong>delv</strong></span> will send queries to + the localhost addresses (127.0.0.1 for IPv4, + ::1 for IPv6). + </p> + </dd> +<dt><span class="term"><code class="constant">name</code></span></dt> +<dd> + <p> + is the domain name to be looked up. + </p> + </dd> +<dt><span class="term"><code class="constant">type</code></span></dt> +<dd> + <p> + indicates what type of query is required — + ANY, A, MX, etc. + <em class="parameter"><code>type</code></em> can be any valid query + type. If no + <em class="parameter"><code>type</code></em> argument is supplied, + <span class="command"><strong>delv</strong></span> will perform a lookup for an + A record. + </p> + </dd> +</dl></div> +<p> + </p> + + </div> + + <div class="refsection"> +<a name="id-1.14.5.9"></a><h2>OPTIONS</h2> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-a <em class="replaceable"><code>anchor-file</code></em></span></dt> +<dd> + <p> + Specifies a file from which to read DNSSEC trust anchors. + The default is <code class="filename">/etc/bind.keys</code>, which + is included with <acronym class="acronym">BIND</acronym> 9 and contains + one or more trust anchors for the root zone ("."). + </p> + <p> + Keys that do not match the root zone name are ignored. + An alternate key name can be specified using the + <code class="option">+root=NAME</code> options. DNSSEC Lookaside + Validation can also be turned on by using the + <code class="option">+dlv=NAME</code> to specify the name of a + zone containing DLV records. + </p> + <p> + Note: When reading the trust anchor file, + <span class="command"><strong>delv</strong></span> treats <code class="option">managed-keys</code> + statements and <code class="option">trusted-keys</code> statements + identically. That is, for a managed key, it is the + <span class="emphasis"><em>initial</em></span> key that is trusted; RFC 5011 + key management is not supported. <span class="command"><strong>delv</strong></span> + will not consult the managed-keys database maintained by + <span class="command"><strong>named</strong></span>. This means that if either of the + keys in <code class="filename">/etc/bind.keys</code> is revoked + and rolled over, it will be necessary to update + <code class="filename">/etc/bind.keys</code> to use DNSSEC + validation in <span class="command"><strong>delv</strong></span>. + </p> + </dd> +<dt><span class="term">-b <em class="replaceable"><code>address</code></em></span></dt> +<dd> + <p> + Sets the source IP address of the query to + <em class="parameter"><code>address</code></em>. This must be a valid address + on one of the host's network interfaces or "0.0.0.0" or "::". + An optional source port may be specified by appending + "#<port>" + </p> + </dd> +<dt><span class="term">-c <em class="replaceable"><code>class</code></em></span></dt> +<dd> + <p> + Sets the query class for the requested data. Currently, + only class "IN" is supported in <span class="command"><strong>delv</strong></span> + and any other value is ignored. + </p> + </dd> +<dt><span class="term">-d <em class="replaceable"><code>level</code></em></span></dt> +<dd> + <p> + Set the systemwide debug level to <code class="option">level</code>. + The allowed range is from 0 to 99. + The default is 0 (no debugging). + Debugging traces from <span class="command"><strong>delv</strong></span> become + more verbose as the debug level increases. + See the <code class="option">+mtrace</code>, <code class="option">+rtrace</code>, + and <code class="option">+vtrace</code> options below for additional + debugging details. + </p> + </dd> +<dt><span class="term">-h</span></dt> +<dd> + <p> + Display the <span class="command"><strong>delv</strong></span> help usage output and exit. + </p> + </dd> +<dt><span class="term">-i</span></dt> +<dd> + <p> + Insecure mode. This disables internal DNSSEC validation. + (Note, however, this does not set the CD bit on upstream + queries. If the server being queried is performing DNSSEC + validation, then it will not return invalid data; this + can cause <span class="command"><strong>delv</strong></span> to time out. When it + is necessary to examine invalid data to debug a DNSSEC + problem, use <span class="command"><strong>dig +cd</strong></span>.) + </p> + </dd> +<dt><span class="term">-m</span></dt> +<dd> + <p> + Enables memory usage debugging. + </p> + </dd> +<dt><span class="term">-p <em class="replaceable"><code>port#</code></em></span></dt> +<dd> + <p> + Specifies a destination port to use for queries instead of + the standard DNS port number 53. This option would be used + with a name server that has been configured to listen + for queries on a non-standard port number. + </p> + </dd> +<dt><span class="term">-q <em class="replaceable"><code>name</code></em></span></dt> +<dd> + <p> + Sets the query name to <em class="parameter"><code>name</code></em>. + While the query name can be specified without using the + <code class="option">-q</code>, it is sometimes necessary to disambiguate + names from types or classes (for example, when looking up the + name "ns", which could be misinterpreted as the type NS, + or "ch", which could be misinterpreted as class CH). + </p> + </dd> +<dt><span class="term">-t <em class="replaceable"><code>type</code></em></span></dt> +<dd> + <p> + Sets the query type to <em class="parameter"><code>type</code></em>, which + can be any valid query type supported in BIND 9 except + for zone transfer types AXFR and IXFR. As with + <code class="option">-q</code>, this is useful to distinguish + query name type or class when they are ambiguous. + it is sometimes necessary to disambiguate names from types. + </p> + <p> + The default query type is "A", unless the <code class="option">-x</code> + option is supplied to indicate a reverse lookup, in which case + it is "PTR". + </p> + </dd> +<dt><span class="term">-v</span></dt> +<dd> + <p> + Print the <span class="command"><strong>delv</strong></span> version and exit. + </p> + </dd> +<dt><span class="term">-x <em class="replaceable"><code>addr</code></em></span></dt> +<dd> + <p> + Performs a reverse lookup, mapping an addresses to + a name. <em class="parameter"><code>addr</code></em> is an IPv4 address in + dotted-decimal notation, or a colon-delimited IPv6 address. + When <code class="option">-x</code> is used, there is no need to provide + the <em class="parameter"><code>name</code></em> or <em class="parameter"><code>type</code></em> + arguments. <span class="command"><strong>delv</strong></span> automatically performs a + lookup for a name like <code class="literal">11.12.13.10.in-addr.arpa</code> + and sets the query type to PTR. IPv6 addresses are looked up + using nibble format under the IP6.ARPA domain. + </p> + </dd> +<dt><span class="term">-4</span></dt> +<dd> + <p> + Forces <span class="command"><strong>delv</strong></span> to only use IPv4. + </p> + </dd> +<dt><span class="term">-6</span></dt> +<dd> + <p> + Forces <span class="command"><strong>delv</strong></span> to only use IPv6. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.5.10"></a><h2>QUERY OPTIONS</h2> + + + <p><span class="command"><strong>delv</strong></span> + provides a number of query options which affect the way results are + displayed, and in some cases the way lookups are performed. + </p> + + <p> + Each query option is identified by a keyword preceded by a plus sign + (<code class="literal">+</code>). Some keywords set or reset an + option. These may be preceded by the string + <code class="literal">no</code> to negate the meaning of that keyword. + Other keywords assign values to options like the timeout interval. + They have the form <code class="option">+keyword=value</code>. + The query options are: + + </p> +<div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><code class="option">+[no]cdflag</code></span></dt> +<dd> + <p> + Controls whether to set the CD (checking disabled) bit in + queries sent by <span class="command"><strong>delv</strong></span>. This may be useful + when troubleshooting DNSSEC problems from behind a validating + resolver. A validating resolver will block invalid responses, + making it difficult to retrieve them for analysis. Setting + the CD flag on queries will cause the resolver to return + invalid responses, which <span class="command"><strong>delv</strong></span> can then + validate internally and report the errors in detail. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]class</code></span></dt> +<dd> + <p> + Controls whether to display the CLASS when printing + a record. The default is to display the CLASS. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]ttl</code></span></dt> +<dd> + <p> + Controls whether to display the TTL when printing + a record. The default is to display the TTL. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]rtrace</code></span></dt> +<dd> + <p> + Toggle resolver fetch logging. This reports the + name and type of each query sent by <span class="command"><strong>delv</strong></span> + in the process of carrying out the resolution and validation + process: this includes including the original query and + all subsequent queries to follow CNAMEs and to establish a + chain of trust for DNSSEC validation. + </p> + <p> + This is equivalent to setting the debug level to 1 in + the "resolver" logging category. Setting the systemwide + debug level to 1 using the <code class="option">-d</code> option will + product the same output (but will affect other logging + categories as well). + </p> + </dd> +<dt><span class="term"><code class="option">+[no]mtrace</code></span></dt> +<dd> + <p> + Toggle message logging. This produces a detailed dump of + the responses received by <span class="command"><strong>delv</strong></span> in the + process of carrying out the resolution and validation process. + </p> + <p> + This is equivalent to setting the debug level to 10 + for the "packets" module of the "resolver" logging + category. Setting the systemwide debug level to 10 using + the <code class="option">-d</code> option will produce the same output + (but will affect other logging categories as well). + </p> + </dd> +<dt><span class="term"><code class="option">+[no]vtrace</code></span></dt> +<dd> + <p> + Toggle validation logging. This shows the internal + process of the validator as it determines whether an + answer is validly signed, unsigned, or invalid. + </p> + <p> + This is equivalent to setting the debug level to 3 + for the "validator" module of the "dnssec" logging + category. Setting the systemwide debug level to 3 using + the <code class="option">-d</code> option will produce the same output + (but will affect other logging categories as well). + </p> + </dd> +<dt><span class="term"><code class="option">+[no]short</code></span></dt> +<dd> + <p> + Provide a terse answer. The default is to print the answer in a + verbose form. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]comments</code></span></dt> +<dd> + <p> + Toggle the display of comment lines in the output. The default + is to print comments. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]rrcomments</code></span></dt> +<dd> + <p> + Toggle the display of per-record comments in the output (for + example, human-readable key information about DNSKEY records). + The default is to print per-record comments. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]crypto</code></span></dt> +<dd> + <p> + Toggle the display of cryptographic fields in DNSSEC records. + The contents of these field are unnecessary to debug most DNSSEC + validation failures and removing them makes it easier to see + the common failures. The default is to display the fields. + When omitted they are replaced by the string "[omitted]" or + in the DNSKEY case the key id is displayed as the replacement, + e.g. "[ key id = value ]". + </p> + </dd> +<dt><span class="term"><code class="option">+[no]trust</code></span></dt> +<dd> + <p> + Controls whether to display the trust level when printing + a record. The default is to display the trust level. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]split[=W]</code></span></dt> +<dd> + <p> + Split long hex- or base64-formatted fields in resource + records into chunks of <em class="parameter"><code>W</code></em> characters + (where <em class="parameter"><code>W</code></em> is rounded up to the nearest + multiple of 4). + <em class="parameter"><code>+nosplit</code></em> or + <em class="parameter"><code>+split=0</code></em> causes fields not to be + split at all. The default is 56 characters, or 44 characters + when multiline mode is active. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]all</code></span></dt> +<dd> + <p> + Set or clear the display options + <code class="option">+[no]comments</code>, + <code class="option">+[no]rrcomments</code>, and + <code class="option">+[no]trust</code> as a group. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]multiline</code></span></dt> +<dd> + <p> + Print long records (such as RRSIG, DNSKEY, and SOA records) + in a verbose multi-line format with human-readable comments. + The default is to print each record on a single line, to + facilitate machine parsing of the <span class="command"><strong>delv</strong></span> + output. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]dnssec</code></span></dt> +<dd> + <p> + Indicates whether to display RRSIG records in the + <span class="command"><strong>delv</strong></span> output. The default is to + do so. Note that (unlike in <span class="command"><strong>dig</strong></span>) + this does <span class="emphasis"><em>not</em></span> control whether to + request DNSSEC records or whether to validate them. + DNSSEC records are always requested, and validation + will always occur unless suppressed by the use of + <code class="option">-i</code> or <code class="option">+noroot</code> and + <code class="option">+nodlv</code>. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]root[=ROOT]</code></span></dt> +<dd> + <p> + Indicates whether to perform conventional (non-lookaside) + DNSSEC validation, and if so, specifies the + name of a trust anchor. The default is to validate using + a trust anchor of "." (the root zone), for which there is + a built-in key. If specifying a different trust anchor, + then <code class="option">-a</code> must be used to specify a file + containing the key. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]dlv[=DLV]</code></span></dt> +<dd> + <p> + Indicates whether to perform DNSSEC lookaside validation, + and if so, specifies the name of the DLV trust anchor. + The <code class="option">-a</code> option must also be used to specify + a file containing the DLV key. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]tcp</code></span></dt> +<dd> + <p> + Controls whether to use TCP when sending queries. + The default is to use UDP unless a truncated + response has been received. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]unknownformat</code></span></dt> +<dd> + <p> + Print all RDATA in unknown RR type presentation format + (RFC 3597). The default is to print RDATA for known types + in the type's presentation format. + </p> + </dd> +</dl></div> +<p> + + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.5.11"></a><h2>FILES</h2> + + <p><code class="filename">/etc/bind.keys</code></p> + <p><code class="filename">/etc/resolv.conf</code></p> + </div> + + <div class="refsection"> +<a name="id-1.14.5.12"></a><h2>SEE ALSO</h2> + + <p><span class="citerefentry"> + <span class="refentrytitle">dig</span>(1) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">named</span>(8) + </span>, + <em class="citetitle">RFC4034</em>, + <em class="citetitle">RFC4035</em>, + <em class="citetitle">RFC4431</em>, + <em class="citetitle">RFC5074</em>, + <em class="citetitle">RFC5155</em>. + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.host.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.nslookup.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top">host </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> nslookup</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.dig.html b/doc/arm/man.dig.html new file mode 100644 index 0000000..980c099 --- /dev/null +++ b/doc/arm/man.dig.html @@ -0,0 +1,1113 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>dig</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="next" href="man.mdig.html" title="mdig"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center">dig</th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="Bv9ARM.ch13.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.mdig.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.dig"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + dig + — DNS lookup utility + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">dig</code> + [@server] + [<code class="option">-b <em class="replaceable"><code>address</code></em></code>] + [<code class="option">-c <em class="replaceable"><code>class</code></em></code>] + [<code class="option">-f <em class="replaceable"><code>filename</code></em></code>] + [<code class="option">-k <em class="replaceable"><code>filename</code></em></code>] + [<code class="option">-m</code>] + [<code class="option">-p <em class="replaceable"><code>port#</code></em></code>] + [<code class="option">-q <em class="replaceable"><code>name</code></em></code>] + [<code class="option">-t <em class="replaceable"><code>type</code></em></code>] + [<code class="option">-v</code>] + [<code class="option">-x <em class="replaceable"><code>addr</code></em></code>] + [<code class="option">-y <em class="replaceable"><code>[<span class="optional">hmac:</span>]name:key</code></em></code>] + [ + [<code class="option">-4</code>] + | [<code class="option">-6</code>] + ] + [name] + [type] + [class] + [queryopt...] + </p></div> + + <div class="cmdsynopsis"><p> + <code class="command">dig</code> + [<code class="option">-h</code>] + </p></div> + + <div class="cmdsynopsis"><p> + <code class="command">dig</code> + [global-queryopt...] + [query...] + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.2.7"></a><h2>DESCRIPTION</h2> + + <p><span class="command"><strong>dig</strong></span> is a flexible tool + for interrogating DNS name servers. It performs DNS lookups and + displays the answers that are returned from the name server(s) that + were queried. Most DNS administrators use <span class="command"><strong>dig</strong></span> to + troubleshoot DNS problems because of its flexibility, ease of use and + clarity of output. Other lookup tools tend to have less functionality + than <span class="command"><strong>dig</strong></span>. + </p> + + <p> + Although <span class="command"><strong>dig</strong></span> is normally used with + command-line + arguments, it also has a batch mode of operation for reading lookup + requests from a file. A brief summary of its command-line arguments + and options is printed when the <code class="option">-h</code> option is given. + Unlike earlier versions, the BIND 9 implementation of + <span class="command"><strong>dig</strong></span> allows multiple lookups to be issued + from the + command line. + </p> + + <p> + Unless it is told to query a specific name server, + <span class="command"><strong>dig</strong></span> will try each of the servers listed in + <code class="filename">/etc/resolv.conf</code>. If no usable server addresses + are found, <span class="command"><strong>dig</strong></span> will send the query to the local + host. + </p> + + <p> + When no command line arguments or options are given, + <span class="command"><strong>dig</strong></span> will perform an NS query for "." (the root). + </p> + + <p> + It is possible to set per-user defaults for <span class="command"><strong>dig</strong></span> via + <code class="filename">${HOME}/.digrc</code>. This file is read and + any options in it + are applied before the command line arguments. + </p> + + <p> + The IN and CH class names overlap with the IN and CH top level + domain names. Either use the <code class="option">-t</code> and + <code class="option">-c</code> options to specify the type and class, + use the <code class="option">-q</code> the specify the domain name, or + use "IN." and "CH." when looking up these top level domains. + </p> + + </div> + + <div class="refsection"> +<a name="id-1.14.2.8"></a><h2>SIMPLE USAGE</h2> + + + <p> + A typical invocation of <span class="command"><strong>dig</strong></span> looks like: + </p> +<pre class="programlisting"> dig @server name type </pre> +<p> + where: + + </p> +<div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><code class="constant">server</code></span></dt> +<dd> + <p> + is the name or IP address of the name server to query. This + can be an IPv4 address in dotted-decimal notation or an IPv6 + address in colon-delimited notation. When the supplied + <em class="parameter"><code>server</code></em> argument is a hostname, + <span class="command"><strong>dig</strong></span> resolves that name before querying + that name server. + </p> + <p> + If no <em class="parameter"><code>server</code></em> argument is + provided, <span class="command"><strong>dig</strong></span> consults + <code class="filename">/etc/resolv.conf</code>; if an + address is found there, it queries the name server at + that address. If either of the <code class="option">-4</code> or + <code class="option">-6</code> options are in use, then + only addresses for the corresponding transport + will be tried. If no usable addresses are found, + <span class="command"><strong>dig</strong></span> will send the query to the + local host. The reply from the name server that + responds is displayed. + </p> + </dd> +<dt><span class="term"><code class="constant">name</code></span></dt> +<dd> + <p> + is the name of the resource record that is to be looked up. + </p> + </dd> +<dt><span class="term"><code class="constant">type</code></span></dt> +<dd> + <p> + indicates what type of query is required — + ANY, A, MX, SIG, etc. + <em class="parameter"><code>type</code></em> can be any valid query + type. If no + <em class="parameter"><code>type</code></em> argument is supplied, + <span class="command"><strong>dig</strong></span> will perform a lookup for an + A record. + </p> + </dd> +</dl></div> +<p> + </p> + + </div> + + <div class="refsection"> +<a name="id-1.14.2.9"></a><h2>OPTIONS</h2> + + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-4</span></dt> +<dd> + <p> + Use IPv4 only. + </p> + </dd> +<dt><span class="term">-6</span></dt> +<dd> + <p> + Use IPv6 only. + </p> + </dd> +<dt><span class="term">-b <em class="replaceable"><code>address[<span class="optional">#port</span>]</code></em></span></dt> +<dd> + <p> + Set the source IP address of the query. + The <em class="parameter"><code>address</code></em> must be a valid address on + one of the host's network interfaces, or "0.0.0.0" or "::". An + optional port may be specified by appending "#<port>" + </p> + </dd> +<dt><span class="term">-c <em class="replaceable"><code>class</code></em></span></dt> +<dd> + <p> + Set the query class. The + default <em class="parameter"><code>class</code></em> is IN; other classes + are HS for Hesiod records or CH for Chaosnet records. + </p> + </dd> +<dt><span class="term">-f <em class="replaceable"><code>file</code></em></span></dt> +<dd> + <p> + Batch mode: <span class="command"><strong>dig</strong></span> reads a list of lookup + requests to process from the + given <em class="parameter"><code>file</code></em>. Each line in the file + should be organized in the same way they would be + presented as queries to + <span class="command"><strong>dig</strong></span> using the command-line interface. + </p> + </dd> +<dt><span class="term">-i</span></dt> +<dd> + <p> + Do reverse IPv6 lookups using the obsolete RFC 1886 IP6.INT + domain, which is no longer in use. Obsolete bit string + label queries (RFC 2874) are not attempted. + </p> + </dd> +<dt><span class="term">-k <em class="replaceable"><code>keyfile</code></em></span></dt> +<dd> + <p> + Sign queries using TSIG using a key read from the given file. + Key files can be generated using + <span class="citerefentry"> + <span class="refentrytitle">tsig-keygen</span>(8) + </span>. + When using TSIG authentication with <span class="command"><strong>dig</strong></span>, + the name server that is queried needs to know the key and + algorithm that is being used. In BIND, this is done by + providing appropriate <span class="command"><strong>key</strong></span> + and <span class="command"><strong>server</strong></span> statements in + <code class="filename">named.conf</code>. + </p> + </dd> +<dt><span class="term">-m</span></dt> +<dd> + <p> + Enable memory usage debugging. + + </p> + </dd> +<dt><span class="term">-p <em class="replaceable"><code>port</code></em></span></dt> +<dd> + <p> + Send the query to a non-standard port on the server, + instead of the default port 53. This option would be used + to test a name server that has been configured to listen + for queries on a non-standard port number. + </p> + </dd> +<dt><span class="term">-q <em class="replaceable"><code>name</code></em></span></dt> +<dd> + <p> + The domain name to query. This is useful to distinguish + the <em class="parameter"><code>name</code></em> from other arguments. + </p> + </dd> +<dt><span class="term">-t <em class="replaceable"><code>type</code></em></span></dt> +<dd> + <p> + The resource record type to query. It can be any valid query + type. If it is a resource record type supported in BIND 9, it + can be given by the type mnemonic (such as "NS" or "AAAA"). + The default query type is "A", unless the <code class="option">-x</code> + option is supplied to indicate a reverse lookup. A zone + transfer can be requested by specifying a type of AXFR. When + an incremental zone transfer (IXFR) is required, set the + <em class="parameter"><code>type</code></em> to <code class="literal">ixfr=N</code>. + The incremental zone transfer will contain the changes + made to the zone since the serial number in the zone's SOA + record was + <em class="parameter"><code>N</code></em>. + </p> + <p> + All resource record types can be expressed as "TYPEnn", where + "nn" is the number of the type. If the resource record type is + not supported in BIND 9, the result will be displayed as + described in RFC 3597. + </p> + </dd> +<dt><span class="term">-u</span></dt> +<dd> + <p> + Print query times in microseconds instead of milliseconds. + </p> + </dd> +<dt><span class="term">-v</span></dt> +<dd> + <p> + Print the version number and exit. + </p> + </dd> +<dt><span class="term">-x <em class="replaceable"><code>addr</code></em></span></dt> +<dd> + <p> + Simplified reverse lookups, for mapping addresses to + names. The <em class="parameter"><code>addr</code></em> is an IPv4 address + in dotted-decimal notation, or a colon-delimited IPv6 + address. When the <code class="option">-x</code> is used, there is no + need to provide + the <em class="parameter"><code>name</code></em>, <em class="parameter"><code>class</code></em> + and <em class="parameter"><code>type</code></em> + arguments. <span class="command"><strong>dig</strong></span> automatically performs a + lookup for a name like + <code class="literal">94.2.0.192.in-addr.arpa</code> and sets the + query type and class to PTR and IN respectively. IPv6 + addresses are looked up using nibble format under the + IP6.ARPA domain (but see also the <code class="option">-i</code> + option). + </p> + </dd> +<dt><span class="term">-y <em class="replaceable"><code>[<span class="optional">hmac:</span>]keyname:secret</code></em></span></dt> +<dd> + <p> + Sign queries using TSIG with the given authentication key. + <em class="parameter"><code>keyname</code></em> is the name of the key, and + <em class="parameter"><code>secret</code></em> is the base64 encoded shared secret. + <em class="parameter"><code>hmac</code></em> is the name of the key algorithm; + valid choices are <code class="literal">hmac-md5</code>, + <code class="literal">hmac-sha1</code>, <code class="literal">hmac-sha224</code>, + <code class="literal">hmac-sha256</code>, <code class="literal">hmac-sha384</code>, or + <code class="literal">hmac-sha512</code>. If <em class="parameter"><code>hmac</code></em> + is not specified, the default is <code class="literal">hmac-md5</code> + or if MD5 was disabled <code class="literal">hmac-sha256</code>. + </p> + <p> + NOTE: You should use the <code class="option">-k</code> option and + avoid the <code class="option">-y</code> option, because + with <code class="option">-y</code> the shared secret is supplied as + a command line argument in clear text. This may be visible + in the output from + <span class="citerefentry"> + <span class="refentrytitle">ps</span>(1) + </span> + or in a history file maintained by the user's shell. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.2.10"></a><h2>QUERY OPTIONS</h2> + + + <p><span class="command"><strong>dig</strong></span> + provides a number of query options which affect + the way in which lookups are made and the results displayed. Some of + these set or reset flag bits in the query header, some determine which + sections of the answer get printed, and others determine the timeout + and retry strategies. + </p> + + <p> + Each query option is identified by a keyword preceded by a plus sign + (<code class="literal">+</code>). Some keywords set or reset an + option. These may be preceded + by the string <code class="literal">no</code> to negate the meaning of + that keyword. Other + keywords assign values to options like the timeout interval. They + have the form <code class="option">+keyword=value</code>. + Keywords may be abbreviated, provided the abbreviation is + unambiguous; for example, <code class="literal">+cd</code> is equivalent + to <code class="literal">+cdflag</code>. + The query options are: + + </p> +<div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><code class="option">+[no]aaflag</code></span></dt> +<dd> + <p> + A synonym for <em class="parameter"><code>+[no]aaonly</code></em>. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]aaonly</code></span></dt> +<dd> + <p> + Sets the "aa" flag in the query. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]additional</code></span></dt> +<dd> + <p> + Display [do not display] the additional section of a + reply. The default is to display it. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]adflag</code></span></dt> +<dd> + <p> + Set [do not set] the AD (authentic data) bit in the + query. This requests the server to return whether + all of the answer and authority sections have all + been validated as secure according to the security + policy of the server. AD=1 indicates that all records + have been validated as secure and the answer is not + from a OPT-OUT range. AD=0 indicate that some part + of the answer was insecure or not validated. This + bit is set by default. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]all</code></span></dt> +<dd> + <p> + Set or clear all display flags. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]answer</code></span></dt> +<dd> + <p> + Display [do not display] the answer section of a + reply. The default is to display it. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]authority</code></span></dt> +<dd> + <p> + Display [do not display] the authority section of a + reply. The default is to display it. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]badcookie</code></span></dt> +<dd> + <p> + Retry lookup with the new server cookie if a + BADCOOKIE response is received. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]besteffort</code></span></dt> +<dd> + <p> + Attempt to display the contents of messages which are + malformed. The default is to not display malformed + answers. + </p> + </dd> +<dt><span class="term"><code class="option">+bufsize=B</code></span></dt> +<dd> + <p> + Set the UDP message buffer size advertised using EDNS0 + to <em class="parameter"><code>B</code></em> bytes. The maximum and + minimum sizes of this buffer are 65535 and 0 respectively. + Values outside this range are rounded up or down + appropriately. Values other than zero will cause a + EDNS query to be sent. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]cdflag</code></span></dt> +<dd> + <p> + Set [do not set] the CD (checking disabled) bit in + the query. This requests the server to not perform + DNSSEC validation of responses. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]class</code></span></dt> +<dd> + <p> + Display [do not display] the CLASS when printing the + record. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]cmd</code></span></dt> +<dd> + <p> + Toggles the printing of the initial comment in the + output identifying the version of <span class="command"><strong>dig</strong></span> + and the query options that have been applied. This + comment is printed by default. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]comments</code></span></dt> +<dd> + <p> + Toggle the display of comment lines in the output. + The default is to print comments. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]cookie[<span class="optional">=####</span>]</code></span></dt> +<dd> + <p> + Send a COOKIE EDNS option, with optional + value. Replaying a COOKIE from a previous response will + allow the server to identify a previous client. The + default is <code class="option">+cookie</code>. + </p> + <p> + <span class="command"><strong>+cookie</strong></span> is also set when +trace + is set to better emulate the default queries from a + nameserver. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]crypto</code></span></dt> +<dd> + <p> + Toggle the display of cryptographic fields in DNSSEC + records. The contents of these field are unnecessary + to debug most DNSSEC validation failures and removing + them makes it easier to see the common failures. The + default is to display the fields. When omitted they + are replaced by the string "[omitted]" or in the + DNSKEY case the key id is displayed as the replacement, + e.g. "[ key id = value ]". + </p> + </dd> +<dt><span class="term"><code class="option">+[no]defname</code></span></dt> +<dd> + <p> + Deprecated, treated as a synonym for + <em class="parameter"><code>+[no]search</code></em> + </p> + </dd> +<dt><span class="term"><code class="option">+[no]dnssec</code></span></dt> +<dd> + <p> + Requests DNSSEC records be sent by setting the DNSSEC + OK bit (DO) in the OPT record in the additional section + of the query. + </p> + </dd> +<dt><span class="term"><code class="option">+domain=somename</code></span></dt> +<dd> + <p> + Set the search list to contain the single domain + <em class="parameter"><code>somename</code></em>, as if specified in + a <span class="command"><strong>domain</strong></span> directive in + <code class="filename">/etc/resolv.conf</code>, and enable + search list processing as if the + <em class="parameter"><code>+search</code></em> option were given. + </p> + </dd> +<dt><span class="term"><code class="option">+dscp=value</code></span></dt> +<dd> + <p> + Set the DSCP code point to be used when sending the + query. Valid DSCP code points are in the range + [0..63]. By default no code point is explicitly set. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]edns[=#]</code></span></dt> +<dd> + <p> + Specify the EDNS version to query with. Valid values + are 0 to 255. Setting the EDNS version will cause + a EDNS query to be sent. <code class="option">+noedns</code> + clears the remembered EDNS version. EDNS is set to + 0 by default. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]ednsflags[=#]</code></span></dt> +<dd> + <p> + Set the must-be-zero EDNS flags bits (Z bits) to the + specified value. Decimal, hex and octal encodings are + accepted. Setting a named flag (e.g. DO) will silently be + ignored. By default, no Z bits are set. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]ednsnegotiation</code></span></dt> +<dd> + <p> + Enable / disable EDNS version negotiation. By default + EDNS version negotiation is enabled. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]ednsopt[=code[:value]]</code></span></dt> +<dd> + <p> + Specify EDNS option with code point <code class="option">code</code> + and optionally payload of <code class="option">value</code> as a + hexadecimal string. <code class="option">code</code> can be + either an EDNS option name (for example, + <code class="literal">NSID</code> or <code class="literal">ECS</code>), + or an arbitrary numeric value. <code class="option">+noednsopt</code> + clears the EDNS options to be sent. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]expire</code></span></dt> +<dd> + <p> + Send an EDNS Expire option. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]fail</code></span></dt> +<dd> + <p> + Do not try the next server if you receive a SERVFAIL. + The default is to not try the next server which is + the reverse of normal stub resolver behavior. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]header-only</code></span></dt> +<dd> + <p> + Send a query with a DNS header without a question section. + The default is to add a question section. The query type + and query name are ignored when this is set. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]identify</code></span></dt> +<dd> + <p> + Show [or do not show] the IP address and port number + that supplied the answer when the + <em class="parameter"><code>+short</code></em> option is enabled. If + short form answers are requested, the default is not + to show the source address and port number of the + server that provided the answer. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]idnin</code></span></dt> +<dd> + <p> + Process [do not process] IDN domain names on input. + This requires IDN SUPPORT to have been enabled at + compile time. The default is to process IDN input. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]idnout</code></span></dt> +<dd> + <p> + Convert [do not convert] puny code on output. + This requires IDN SUPPORT to have been enabled at + compile time. The default is to convert output. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]ignore</code></span></dt> +<dd> + <p> + Ignore truncation in UDP responses instead of retrying + with TCP. By default, TCP retries are performed. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]keepopen</code></span></dt> +<dd> + <p> + Keep the TCP socket open between queries and reuse + it rather than creating a new TCP socket for each + lookup. The default is <code class="option">+nokeepopen</code>. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]mapped</code></span></dt> +<dd> + <p> + Allow mapped IPv4 over IPv6 addresses to be used. The + default is <code class="option">+mapped</code>. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]multiline</code></span></dt> +<dd> + <p> + Print records like the SOA records in a verbose + multi-line format with human-readable comments. The + default is to print each record on a single line, to + facilitate machine parsing of the <span class="command"><strong>dig</strong></span> + output. + </p> + </dd> +<dt><span class="term"><code class="option">+ndots=D</code></span></dt> +<dd> + <p> + Set the number of dots that have to appear in + <em class="parameter"><code>name</code></em> to <em class="parameter"><code>D</code></em> + for it to be considered absolute. The default value + is that defined using the ndots statement in + <code class="filename">/etc/resolv.conf</code>, or 1 if no + ndots statement is present. Names with fewer dots + are interpreted as relative names and will be searched + for in the domains listed in the <code class="option">search</code> + or <code class="option">domain</code> directive in + <code class="filename">/etc/resolv.conf</code> if + <code class="option">+search</code> is set. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]nsid</code></span></dt> +<dd> + <p> + Include an EDNS name server ID request when sending + a query. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]nssearch</code></span></dt> +<dd> + <p> + When this option is set, <span class="command"><strong>dig</strong></span> + attempts to find the authoritative name servers for + the zone containing the name being looked up and + display the SOA record that each name server has for + the zone. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]onesoa</code></span></dt> +<dd> + <p> + Print only one (starting) SOA record when performing + an AXFR. The default is to print both the starting + and ending SOA records. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]opcode=value</code></span></dt> +<dd> + <p> + Set [restore] the DNS message opcode to the specified + value. The default value is QUERY (0). + </p> + </dd> +<dt><span class="term"><code class="option">+[no]qr</code></span></dt> +<dd> + <p> + Print [do not print] the query as it is sent. By + default, the query is not printed. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]question</code></span></dt> +<dd> + <p> + Print [do not print] the question section of a query + when an answer is returned. The default is to print + the question section as a comment. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]rdflag</code></span></dt> +<dd> + <p> + A synonym for <em class="parameter"><code>+[no]recurse</code></em>. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]recurse</code></span></dt> +<dd> + <p> + Toggle the setting of the RD (recursion desired) bit + in the query. This bit is set by default, which means + <span class="command"><strong>dig</strong></span> normally sends recursive + queries. Recursion is automatically disabled when + the <em class="parameter"><code>+nssearch</code></em> or + <em class="parameter"><code>+trace</code></em> query options are used. + </p> + </dd> +<dt><span class="term"><code class="option">+retry=T</code></span></dt> +<dd> + <p> + Sets the number of times to retry UDP queries to + server to <em class="parameter"><code>T</code></em> instead of the + default, 2. Unlike <em class="parameter"><code>+tries</code></em>, + this does not include the initial query. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]rrcomments</code></span></dt> +<dd> + <p> + Toggle the display of per-record comments in the + output (for example, human-readable key information + about DNSKEY records). The default is not to print + record comments unless multiline mode is active. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]search</code></span></dt> +<dd> + <p> + Use [do not use] the search list defined by the + searchlist or domain directive in + <code class="filename">resolv.conf</code> (if any). The search + list is not used by default. + </p> + <p> + 'ndots' from <code class="filename">resolv.conf</code> (default 1) + which may be overridden by <em class="parameter"><code>+ndots</code></em> + determines if the name will be treated as relative + or not and hence whether a search is eventually + performed or not. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]short</code></span></dt> +<dd> + <p> + Provide a terse answer. The default is to print the + answer in a verbose form. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]showsearch</code></span></dt> +<dd> + <p> + Perform [do not perform] a search showing intermediate + results. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]sigchase</code></span></dt> +<dd> + <p> + Chase DNSSEC signature chains. Requires dig be compiled + with -DDIG_SIGCHASE. This feature is deprecated. + Use <span class="command"><strong>delv</strong></span> instead. + </p> + </dd> +<dt><span class="term"><code class="option">+split=W</code></span></dt> +<dd> + <p> + Split long hex- or base64-formatted fields in resource + records into chunks of <em class="parameter"><code>W</code></em> + characters (where <em class="parameter"><code>W</code></em> is rounded + up to the nearest multiple of 4). + <em class="parameter"><code>+nosplit</code></em> or + <em class="parameter"><code>+split=0</code></em> causes fields not to + be split at all. The default is 56 characters, or + 44 characters when multiline mode is active. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]stats</code></span></dt> +<dd> + <p> + This query option toggles the printing of statistics: + when the query was made, the size of the reply and + so on. The default behavior is to print the query + statistics. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]subnet=addr[/prefix-length]</code></span></dt> +<dd> + <p> + Send (don't send) an EDNS Client Subnet option with the + specified IP address or network prefix. + </p> + <p> + <span class="command"><strong>dig +subnet=0.0.0.0/0</strong></span>, or simply + <span class="command"><strong>dig +subnet=0</strong></span> for short, sends an EDNS + CLIENT-SUBNET option with an empty address and a source + prefix-length of zero, which signals a resolver that + the client's address information must + <span class="emphasis"><em>not</em></span> be used when resolving + this query. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]tcp</code></span></dt> +<dd> + <p> + Use [do not use] TCP when querying name servers. The + default behavior is to use UDP unless a type + <code class="literal">any</code> or <code class="literal">ixfr=N</code> + query is requested, in which case the default is TCP. + AXFR queries always use TCP. + </p> + </dd> +<dt><span class="term"><code class="option">+timeout=T</code></span></dt> +<dd> + <p> + + Sets the timeout for a query to + <em class="parameter"><code>T</code></em> seconds. The default + timeout is 5 seconds. + An attempt to set <em class="parameter"><code>T</code></em> to less + than 1 will result + in a query timeout of 1 second being applied. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]topdown</code></span></dt> +<dd> + <p> + When chasing DNSSEC signature chains perform a top-down + validation. Requires dig be compiled with -DDIG_SIGCHASE. + This feature is deprecated. Use <span class="command"><strong>delv</strong></span> instead. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]trace</code></span></dt> +<dd> + <p> + Toggle tracing of the delegation path from the root + name servers for the name being looked up. Tracing + is disabled by default. When tracing is enabled, + <span class="command"><strong>dig</strong></span> makes iterative queries to + resolve the name being looked up. It will follow + referrals from the root servers, showing the answer + from each server that was used to resolve the lookup. + </p> <p> + If @server is also specified, it affects only the + initial query for the root zone name servers. + </p> <p> + <span class="command"><strong>+dnssec</strong></span> is also set when +trace + is set to better emulate the default queries from a + nameserver. + </p> + </dd> +<dt><span class="term"><code class="option">+tries=T</code></span></dt> +<dd> + <p> + Sets the number of times to try UDP queries to server + to <em class="parameter"><code>T</code></em> instead of the default, + 3. If <em class="parameter"><code>T</code></em> is less than or equal + to zero, the number of tries is silently rounded up + to 1. + </p> + </dd> +<dt><span class="term"><code class="option">+trusted-key=####</code></span></dt> +<dd> + <p> + Specifies a file containing trusted keys to be used + with <code class="option">+sigchase</code>. Each DNSKEY record + must be on its own line. + </p> <p> + If not specified, <span class="command"><strong>dig</strong></span> will look + for <code class="filename">/etc/trusted-key.key</code> then + <code class="filename">trusted-key.key</code> in the current + directory. + </p> <p> + Requires dig be compiled with -DDIG_SIGCHASE. + This feature is deprecated. Use <span class="command"><strong>delv</strong></span> instead. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]ttlid</code></span></dt> +<dd> + <p> + Display [do not display] the TTL when printing the + record. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]ttlunits</code></span></dt> +<dd> + <p> + Display [do not display] the TTL in friendly human-readable + time units of "s", "m", "h", "d", and "w", representing + seconds, minutes, hours, days and weeks. Implies +ttlid. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]unknownformat</code></span></dt> +<dd> + <p> + Print all RDATA in unknown RR type presentation format + (RFC 3597). The default is to print RDATA for known types + in the type's presentation format. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]vc</code></span></dt> +<dd> + <p> + Use [do not use] TCP when querying name servers. This + alternate syntax to <em class="parameter"><code>+[no]tcp</code></em> + is provided for backwards compatibility. The "vc" + stands for "virtual circuit". + </p> + </dd> +<dt><span class="term"><code class="option">+[no]zflag</code></span></dt> +<dd> + <p> + Set [do not set] the last unassigned DNS header flag in a + DNS query. This flag is off by default. + </p> + </dd> +</dl></div> +<p> + + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.2.11"></a><h2>MULTIPLE QUERIES</h2> + + + <p> + The BIND 9 implementation of <span class="command"><strong>dig </strong></span> + supports + specifying multiple queries on the command line (in addition to + supporting the <code class="option">-f</code> batch file option). Each of those + queries can be supplied with its own set of flags, options and query + options. + </p> + + <p> + In this case, each <em class="parameter"><code>query</code></em> argument + represent an + individual query in the command-line syntax described above. Each + consists of any of the standard options and flags, the name to be + looked up, an optional query type and class and any query options that + should be applied to that query. + </p> + + <p> + A global set of query options, which should be applied to all queries, + can also be supplied. These global query options must precede the + first tuple of name, class, type, options, flags, and query options + supplied on the command line. Any global query options (except + the <code class="option">+[no]cmd</code> option) can be + overridden by a query-specific set of query options. For example: + </p> +<pre class="programlisting"> +dig +qr www.isc.org any -x 127.0.0.1 isc.org ns +noqr +</pre> +<p> + shows how <span class="command"><strong>dig</strong></span> could be used from the + command line + to make three lookups: an ANY query for <code class="literal">www.isc.org</code>, a + reverse lookup of 127.0.0.1 and a query for the NS records of + <code class="literal">isc.org</code>. + + A global query option of <em class="parameter"><code>+qr</code></em> is + applied, so + that <span class="command"><strong>dig</strong></span> shows the initial query it made + for each + lookup. The final query has a local query option of + <em class="parameter"><code>+noqr</code></em> which means that <span class="command"><strong>dig</strong></span> + will not print the initial query when it looks up the NS records for + <code class="literal">isc.org</code>. + </p> + + </div> + + <div class="refsection"> +<a name="id-1.14.2.12"></a><h2>IDN SUPPORT</h2> + + <p> + If <span class="command"><strong>dig</strong></span> has been built with IDN (internationalized + domain name) support, it can accept and display non-ASCII domain names. + <span class="command"><strong>dig</strong></span> appropriately converts character encoding of + domain name before sending a request to DNS server or displaying a + reply from the server. + If you'd like to turn off the IDN support for some reason, use + parameters <em class="parameter"><code>+noidnin</code></em> and + <em class="parameter"><code>+noidnout</code></em>. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.2.13"></a><h2>FILES</h2> + + <p><code class="filename">/etc/resolv.conf</code> + </p> + <p><code class="filename">${HOME}/.digrc</code> + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.2.14"></a><h2>SEE ALSO</h2> + + <p><span class="citerefentry"> + <span class="refentrytitle">delv</span>(1) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">host</span>(1) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">named</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">dnssec-keygen</span>(8) + </span>, + <em class="citetitle">RFC 1035</em>. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.2.15"></a><h2>BUGS</h2> + + <p> + There are probably too many query options. + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="Bv9ARM.ch13.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.mdig.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top">Manual pages </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">mdig</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.dnssec-checkds.html b/doc/arm/man.dnssec-checkds.html new file mode 100644 index 0000000..f8b6104 --- /dev/null +++ b/doc/arm/man.dnssec-checkds.html @@ -0,0 +1,153 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>dnssec-checkds</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.nslookup.html" title="nslookup"> +<link rel="next" href="man.dnssec-coverage.html" title="dnssec-coverage"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">dnssec-checkds</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.nslookup.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.dnssec-coverage.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.dnssec-checkds"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">dnssec-checkds</span> + — DNSSEC delegation consistency checking tool + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">dnssec-checkds</code> + [<code class="option">-l <em class="replaceable"><code>domain</code></em></code>] + [<code class="option">-f <em class="replaceable"><code>file</code></em></code>] + [<code class="option">-d <em class="replaceable"><code>dig path</code></em></code>] + [<code class="option">-D <em class="replaceable"><code>dsfromkey path</code></em></code>] + {zone} + </p></div> + <div class="cmdsynopsis"><p> + <code class="command">dnssec-dsfromkey</code> + [<code class="option">-l <em class="replaceable"><code>domain</code></em></code>] + [<code class="option">-f <em class="replaceable"><code>file</code></em></code>] + [<code class="option">-d <em class="replaceable"><code>dig path</code></em></code>] + [<code class="option">-D <em class="replaceable"><code>dsfromkey path</code></em></code>] + {zone} + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.7.7"></a><h2>DESCRIPTION</h2> + + <p><span class="command"><strong>dnssec-checkds</strong></span> + verifies the correctness of Delegation Signer (DS) or DNSSEC + Lookaside Validation (DLV) resource records for keys in a specified + zone. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.7.8"></a><h2>OPTIONS</h2> + + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-f <em class="replaceable"><code>file</code></em></span></dt> +<dd> + <p> + If a <code class="option">file</code> is specified, then the zone is + read from that file to find the DNSKEY records. If not, + then the DNSKEY records for the zone are looked up in the DNS. + </p> + </dd> +<dt><span class="term">-l <em class="replaceable"><code>domain</code></em></span></dt> +<dd> + <p> + Check for a DLV record in the specified lookaside domain, + instead of checking for a DS record in the zone's parent. + </p> + </dd> +<dt><span class="term">-d <em class="replaceable"><code>dig path</code></em></span></dt> +<dd> + <p> + Specifies a path to a <span class="command"><strong>dig</strong></span> binary. Used + for testing. + </p> + </dd> +<dt><span class="term">-D <em class="replaceable"><code>dsfromkey path</code></em></span></dt> +<dd> + <p> + Specifies a path to a <span class="command"><strong>dnssec-dsfromkey</strong></span> binary. + Used for testing. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.7.9"></a><h2>SEE ALSO</h2> + + <p><span class="citerefentry"> + <span class="refentrytitle">dnssec-dsfromkey</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">dnssec-keygen</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">dnssec-signzone</span>(8) + </span>, + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.nslookup.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.dnssec-coverage.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top">nslookup </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">dnssec-coverage</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.dnssec-coverage.html b/doc/arm/man.dnssec-coverage.html new file mode 100644 index 0000000..1655515 --- /dev/null +++ b/doc/arm/man.dnssec-coverage.html @@ -0,0 +1,275 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>dnssec-coverage</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.dnssec-checkds.html" title="dnssec-checkds"> +<link rel="next" href="man.dnssec-dsfromkey.html" title="dnssec-dsfromkey"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">dnssec-coverage</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.dnssec-checkds.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.dnssec-dsfromkey.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.dnssec-coverage"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">dnssec-coverage</span> + — checks future DNSKEY coverage for a zone + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">dnssec-coverage</code> + [<code class="option">-K <em class="replaceable"><code>directory</code></em></code>] + [<code class="option">-l <em class="replaceable"><code>length</code></em></code>] + [<code class="option">-f <em class="replaceable"><code>file</code></em></code>] + [<code class="option">-d <em class="replaceable"><code>DNSKEY TTL</code></em></code>] + [<code class="option">-m <em class="replaceable"><code>max TTL</code></em></code>] + [<code class="option">-r <em class="replaceable"><code>interval</code></em></code>] + [<code class="option">-c <em class="replaceable"><code>compilezone path</code></em></code>] + [<code class="option">-k</code>] + [<code class="option">-z</code>] + [zone...] + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.8.7"></a><h2>DESCRIPTION</h2> + + <p><span class="command"><strong>dnssec-coverage</strong></span> + verifies that the DNSSEC keys for a given zone or a set of zones + have timing metadata set properly to ensure no future lapses in DNSSEC + coverage. + </p> + <p> + If <code class="option">zone</code> is specified, then keys found in + the key repository matching that zone are scanned, and an ordered + list is generated of the events scheduled for that key (i.e., + publication, activation, inactivation, deletion). The list of + events is walked in order of occurrence. Warnings are generated + if any event is scheduled which could cause the zone to enter a + state in which validation failures might occur: for example, if + the number of published or active keys for a given algorithm drops + to zero, or if a key is deleted from the zone too soon after a new + key is rolled, and cached data signed by the prior key has not had + time to expire from resolver caches. + </p> + <p> + If <code class="option">zone</code> is not specified, then all keys in the + key repository will be scanned, and all zones for which there are + keys will be analyzed. (Note: This method of reporting is only + accurate if all the zones that have keys in a given repository + share the same TTL parameters.) + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.8.8"></a><h2>OPTIONS</h2> + + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-K <em class="replaceable"><code>directory</code></em></span></dt> +<dd> + <p> + Sets the directory in which keys can be found. Defaults to the + current working directory. + </p> + </dd> +<dt><span class="term">-f <em class="replaceable"><code>file</code></em></span></dt> +<dd> + <p> + If a <code class="option">file</code> is specified, then the zone is + read from that file; the largest TTL and the DNSKEY TTL are + determined directly from the zone data, and the + <code class="option">-m</code> and <code class="option">-d</code> options do + not need to be specified on the command line. + </p> + </dd> +<dt><span class="term">-l <em class="replaceable"><code>duration</code></em></span></dt> +<dd> + <p> + The length of time to check for DNSSEC coverage. Key events + scheduled further into the future than <code class="option">duration</code> + will be ignored, and assumed to be correct. + </p> + <p> + The value of <code class="option">duration</code> can be set in seconds, + or in larger units of time by adding a suffix: 'mi' for minutes, + 'h' for hours, 'd' for days, 'w' for weeks, 'mo' for months, + 'y' for years. + </p> + </dd> +<dt><span class="term">-m <em class="replaceable"><code>maximum TTL</code></em></span></dt> +<dd> + <p> + Sets the value to be used as the maximum TTL for the zone or + zones being analyzed when determining whether there is a + possibility of validation failure. When a zone-signing key is + deactivated, there must be enough time for the record in the + zone with the longest TTL to have expired from resolver caches + before that key can be purged from the DNSKEY RRset. If that + condition does not apply, a warning will be generated. + </p> + <p> + The length of the TTL can be set in seconds, or in larger units + of time by adding a suffix: 'mi' for minutes, 'h' for hours, + 'd' for days, 'w' for weeks, 'mo' for months, 'y' for years. + </p> + <p> + This option is not necessary if the <code class="option">-f</code> has + been used to specify a zone file. If <code class="option">-f</code> has + been specified, this option may still be used; it will override + the value found in the file. + </p> + <p> + If this option is not used and the maximum TTL cannot be retrieved + from a zone file, a warning is generated and a default value of + 1 week is used. + </p> + </dd> +<dt><span class="term">-d <em class="replaceable"><code>DNSKEY TTL</code></em></span></dt> +<dd> + <p> + Sets the value to be used as the DNSKEY TTL for the zone or + zones being analyzed when determining whether there is a + possibility of validation failure. When a key is rolled (that + is, replaced with a new key), there must be enough time for the + old DNSKEY RRset to have expired from resolver caches before + the new key is activated and begins generating signatures. If + that condition does not apply, a warning will be generated. + </p> + <p> + The length of the TTL can be set in seconds, or in larger units + of time by adding a suffix: 'mi' for minutes, 'h' for hours, + 'd' for days, 'w' for weeks, 'mo' for months, 'y' for years. + </p> + <p> + This option is not necessary if <code class="option">-f</code> has + been used to specify a zone file from which the TTL + of the DNSKEY RRset can be read, or if a default key TTL was + set using ith the <code class="option">-L</code> to + <span class="command"><strong>dnssec-keygen</strong></span>. If either of those is true, + this option may still be used; it will override the values + found in the zone file or the key file. + </p> + <p> + If this option is not used and the key TTL cannot be retrieved + from the zone file or the key file, then a warning is generated + and a default value of 1 day is used. + </p> + </dd> +<dt><span class="term">-r <em class="replaceable"><code>resign interval</code></em></span></dt> +<dd> + <p> + Sets the value to be used as the resign interval for the zone + or zones being analyzed when determining whether there is a + possibility of validation failure. This value defaults to + 22.5 days, which is also the default in + <span class="command"><strong>named</strong></span>. However, if it has been changed + by the <code class="option">sig-validity-interval</code> option in + <code class="filename">named.conf</code>, then it should also be + changed here. + </p> + <p> + The length of the interval can be set in seconds, or in larger + units of time by adding a suffix: 'mi' for minutes, 'h' for hours, + 'd' for days, 'w' for weeks, 'mo' for months, 'y' for years. + </p> + </dd> +<dt><span class="term">-k</span></dt> +<dd> + <p> + Only check KSK coverage; ignore ZSK events. Cannot be + used with <code class="option">-z</code>. + </p> + </dd> +<dt><span class="term">-z</span></dt> +<dd> + <p> + Only check ZSK coverage; ignore KSK events. Cannot be + used with <code class="option">-k</code>. + </p> + </dd> +<dt><span class="term">-c <em class="replaceable"><code>compilezone path</code></em></span></dt> +<dd> + <p> + Specifies a path to a <span class="command"><strong>named-compilezone</strong></span> binary. + Used for testing. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.8.9"></a><h2>SEE ALSO</h2> + + <p> + <span class="citerefentry"> + <span class="refentrytitle">dnssec-checkds</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">dnssec-dsfromkey</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">dnssec-keygen</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">dnssec-signzone</span>(8) + </span> + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.dnssec-checkds.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.dnssec-dsfromkey.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">dnssec-checkds</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">dnssec-dsfromkey</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.dnssec-dsfromkey.html b/doc/arm/man.dnssec-dsfromkey.html new file mode 100644 index 0000000..5a224f1 --- /dev/null +++ b/doc/arm/man.dnssec-dsfromkey.html @@ -0,0 +1,294 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>dnssec-dsfromkey</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.dnssec-coverage.html" title="dnssec-coverage"> +<link rel="next" href="man.dnssec-importkey.html" title="dnssec-importkey"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">dnssec-dsfromkey</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.dnssec-coverage.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.dnssec-importkey.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.dnssec-dsfromkey"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">dnssec-dsfromkey</span> + — DNSSEC DS RR generation tool + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">dnssec-dsfromkey</code> + [<code class="option">-v <em class="replaceable"><code>level</code></em></code>] + [<code class="option">-1</code>] + [<code class="option">-2</code>] + [<code class="option">-a <em class="replaceable"><code>alg</code></em></code>] + [<code class="option">-C</code>] + [<code class="option">-l <em class="replaceable"><code>domain</code></em></code>] + [<code class="option">-T <em class="replaceable"><code>TTL</code></em></code>] + {keyfile} + </p></div> + <div class="cmdsynopsis"><p> + <code class="command">dnssec-dsfromkey</code> + {-s} + [<code class="option">-1</code>] + [<code class="option">-2</code>] + [<code class="option">-a <em class="replaceable"><code>alg</code></em></code>] + [<code class="option">-K <em class="replaceable"><code>directory</code></em></code>] + [<code class="option">-l <em class="replaceable"><code>domain</code></em></code>] + [<code class="option">-s</code>] + [<code class="option">-c <em class="replaceable"><code>class</code></em></code>] + [<code class="option">-T <em class="replaceable"><code>TTL</code></em></code>] + [<code class="option">-f <em class="replaceable"><code>file</code></em></code>] + [<code class="option">-A</code>] + [<code class="option">-v <em class="replaceable"><code>level</code></em></code>] + {dnsname} + </p></div> + <div class="cmdsynopsis"><p> + <code class="command">dnssec-dsfromkey</code> + [<code class="option">-h</code>] + [<code class="option">-V</code>] + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.9.7"></a><h2>DESCRIPTION</h2> + + <p><span class="command"><strong>dnssec-dsfromkey</strong></span> + outputs the Delegation Signer (DS) resource record (RR), as defined in + RFC 3658 and RFC 4509, for the given key(s). + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.9.8"></a><h2>OPTIONS</h2> + + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-1</span></dt> +<dd> + <p> + Use SHA-1 as the digest algorithm (the default is to use + both SHA-1 and SHA-256). + </p> + </dd> +<dt><span class="term">-2</span></dt> +<dd> + <p> + Use SHA-256 as the digest algorithm. + </p> + </dd> +<dt><span class="term">-a <em class="replaceable"><code>algorithm</code></em></span></dt> +<dd> + <p> + Select the digest algorithm. The value of + <code class="option">algorithm</code> must be one of SHA-1 (SHA1), + SHA-256 (SHA256), GOST or SHA-384 (SHA384). + These values are case insensitive. + </p> + </dd> +<dt><span class="term">-C</span></dt> +<dd> + <p> + Generate CDS records rather than DS records. This is mutually + exclusive with generating lookaside records. + </p> + </dd> +<dt><span class="term">-T <em class="replaceable"><code>TTL</code></em></span></dt> +<dd> + <p> + Specifies the TTL of the DS records. + </p> + </dd> +<dt><span class="term">-K <em class="replaceable"><code>directory</code></em></span></dt> +<dd> + <p> + Look for key files (or, in keyset mode, + <code class="filename">keyset-</code> files) in + <code class="option">directory</code>. + </p> + </dd> +<dt><span class="term">-f <em class="replaceable"><code>file</code></em></span></dt> +<dd> + <p> + Zone file mode: in place of the keyfile name, the argument is + the DNS domain name of a zone master file, which can be read + from <code class="option">file</code>. If the zone name is the same as + <code class="option">file</code>, then it may be omitted. + </p> + <p> + If <code class="option">file</code> is set to <code class="literal">"-"</code>, then + the zone data is read from the standard input. This makes it + possible to use the output of the <span class="command"><strong>dig</strong></span> + command as input, as in: + </p> + <p> + <strong class="userinput"><code>dig dnskey example.com | dnssec-dsfromkey -f - example.com</code></strong> + </p> + </dd> +<dt><span class="term">-A</span></dt> +<dd> + <p> + Include ZSKs when generating DS records. Without this option, + only keys which have the KSK flag set will be converted to DS + records and printed. Useful only in zone file mode. + </p> + </dd> +<dt><span class="term">-l <em class="replaceable"><code>domain</code></em></span></dt> +<dd> + <p> + Generate a DLV set instead of a DS set. The specified + <code class="option">domain</code> is appended to the name for each + record in the set. + The DNSSEC Lookaside Validation (DLV) RR is described + in RFC 4431. This is mutually exclusive with generating + CDS records. + </p> + </dd> +<dt><span class="term">-s</span></dt> +<dd> + <p> + Keyset mode: in place of the keyfile name, the argument is + the DNS domain name of a keyset file. + </p> + </dd> +<dt><span class="term">-c <em class="replaceable"><code>class</code></em></span></dt> +<dd> + <p> + Specifies the DNS class (default is IN). Useful only + in keyset or zone file mode. + </p> + </dd> +<dt><span class="term">-v <em class="replaceable"><code>level</code></em></span></dt> +<dd> + <p> + Sets the debugging level. + </p> + </dd> +<dt><span class="term">-h</span></dt> +<dd> + <p> + Prints usage information. + </p> + </dd> +<dt><span class="term">-V</span></dt> +<dd> + <p> + Prints version information. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.9.9"></a><h2>EXAMPLE</h2> + + <p> + To build the SHA-256 DS RR from the + <strong class="userinput"><code>Kexample.com.+003+26160</code></strong> + keyfile name, the following command would be issued: + </p> + <p><strong class="userinput"><code>dnssec-dsfromkey -2 Kexample.com.+003+26160</code></strong> + </p> + <p> + The command would print something like: + </p> + <p><strong class="userinput"><code>example.com. IN DS 26160 5 2 3A1EADA7A74B8D0BA86726B0C227AA85AB8BBD2B2004F41A868A54F0 C5EA0B94</code></strong> + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.9.10"></a><h2>FILES</h2> + + <p> + The keyfile can be designed by the key identification + <code class="filename">Knnnn.+aaa+iiiii</code> or the full file name + <code class="filename">Knnnn.+aaa+iiiii.key</code> as generated by + <span class="refentrytitle">dnssec-keygen</span>(8). + </p> + <p> + The keyset file name is built from the <code class="option">directory</code>, + the string <code class="filename">keyset-</code> and the + <code class="option">dnsname</code>. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.9.11"></a><h2>CAVEAT</h2> + + <p> + A keyfile error can give a "file not found" even if the file exists. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.9.12"></a><h2>SEE ALSO</h2> + + <p><span class="citerefentry"> + <span class="refentrytitle">dnssec-keygen</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">dnssec-signzone</span>(8) + </span>, + <em class="citetitle">BIND 9 Administrator Reference Manual</em>, + <em class="citetitle">RFC 3658</em>, + <em class="citetitle">RFC 4431</em>. + <em class="citetitle">RFC 4509</em>. + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.dnssec-coverage.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.dnssec-importkey.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">dnssec-coverage</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">dnssec-importkey</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.dnssec-importkey.html b/doc/arm/man.dnssec-importkey.html new file mode 100644 index 0000000..7348303 --- /dev/null +++ b/doc/arm/man.dnssec-importkey.html @@ -0,0 +1,255 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>dnssec-importkey</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.dnssec-dsfromkey.html" title="dnssec-dsfromkey"> +<link rel="next" href="man.dnssec-keyfromlabel.html" title="dnssec-keyfromlabel"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">dnssec-importkey</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.dnssec-dsfromkey.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.dnssec-keyfromlabel.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.dnssec-importkey"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">dnssec-importkey</span> + — import DNSKEY records from external systems so they can be managed + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">dnssec-importkey</code> + [<code class="option">-K <em class="replaceable"><code>directory</code></em></code>] + [<code class="option">-L <em class="replaceable"><code>ttl</code></em></code>] + [<code class="option">-P <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-P sync <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-D <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-D sync <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-h</code>] + [<code class="option">-v <em class="replaceable"><code>level</code></em></code>] + [<code class="option">-V</code>] + {<code class="option">keyfile</code>} + </p></div> + <div class="cmdsynopsis"><p> + <code class="command">dnssec-importkey</code> + {<code class="option">-f <em class="replaceable"><code>filename</code></em></code>} + [<code class="option">-K <em class="replaceable"><code>directory</code></em></code>] + [<code class="option">-L <em class="replaceable"><code>ttl</code></em></code>] + [<code class="option">-P <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-P sync <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-D <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-D sync <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-h</code>] + [<code class="option">-v <em class="replaceable"><code>level</code></em></code>] + [<code class="option">-V</code>] + [<code class="option">dnsname</code>] + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.10.7"></a><h2>DESCRIPTION</h2> + + <p><span class="command"><strong>dnssec-importkey</strong></span> + reads a public DNSKEY record and generates a pair of + .key/.private files. The DNSKEY record may be read from an + existing .key file, in which case a corresponding .private file + will be generated, or it may be read from any other file or + from the standard input, in which case both .key and .private + files will be generated. + </p> + <p> + The newly-created .private file does <span class="emphasis"><em>not</em></span> + contain private key data, and cannot be used for signing. + However, having a .private file makes it possible to set + publication (<code class="option">-P</code>) and deletion + (<code class="option">-D</code>) times for the key, which means the + public key can be added to and removed from the DNSKEY RRset + on schedule even if the true private key is stored offline. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.10.8"></a><h2>OPTIONS</h2> + + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-f <em class="replaceable"><code>filename</code></em></span></dt> +<dd> + <p> + Zone file mode: instead of a public keyfile name, the argument + is the DNS domain name of a zone master file, which can be read + from <code class="option">file</code>. If the domain name is the same as + <code class="option">file</code>, then it may be omitted. + </p> + <p> + If <code class="option">file</code> is set to <code class="literal">"-"</code>, then + the zone data is read from the standard input. + </p> + </dd> +<dt><span class="term">-K <em class="replaceable"><code>directory</code></em></span></dt> +<dd> + <p> + Sets the directory in which the key files are to reside. + </p> + </dd> +<dt><span class="term">-L <em class="replaceable"><code>ttl</code></em></span></dt> +<dd> + <p> + Sets the default TTL to use for this key when it is converted + into a DNSKEY RR. If the key is imported into a zone, + this is the TTL that will be used for it, unless there was + already a DNSKEY RRset in place, in which case the existing TTL + would take precedence. Setting the default TTL to + <code class="literal">0</code> or <code class="literal">none</code> removes it. + </p> + </dd> +<dt><span class="term">-h</span></dt> +<dd> + <p> + Emit usage message and exit. + </p> + </dd> +<dt><span class="term">-v <em class="replaceable"><code>level</code></em></span></dt> +<dd> + <p> + Sets the debugging level. + </p> + </dd> +<dt><span class="term">-V</span></dt> +<dd> + <p> + Prints version information. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.10.9"></a><h2>TIMING OPTIONS</h2> + + <p> + Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS. + If the argument begins with a '+' or '-', it is interpreted as + an offset from the present time. For convenience, if such an offset + is followed by one of the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', + then the offset is computed in years (defined as 365 24-hour days, + ignoring leap years), months (defined as 30 24-hour days), weeks, + days, hours, or minutes, respectively. Without a suffix, the offset + is computed in seconds. To explicitly prevent a date from being + set, use 'none' or 'never'. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-P <em class="replaceable"><code>date/offset</code></em></span></dt> +<dd> + <p> + Sets the date on which a key is to be published to the zone. + After that date, the key will be included in the zone but will + not be used to sign it. + </p> + </dd> +<dt><span class="term">-P sync <em class="replaceable"><code>date/offset</code></em></span></dt> +<dd> + <p> + Sets the date on which CDS and CDNSKEY records that match this + key are to be published to the zone. + </p> + </dd> +<dt><span class="term">-D <em class="replaceable"><code>date/offset</code></em></span></dt> +<dd> + <p> + Sets the date on which the key is to be deleted. After that + date, the key will no longer be included in the zone. (It + may remain in the key repository, however.) + </p> + </dd> +<dt><span class="term">-D sync <em class="replaceable"><code>date/offset</code></em></span></dt> +<dd> + <p> + Sets the date on which the CDS and CDNSKEY records that match + this key are to be deleted. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.10.10"></a><h2>FILES</h2> + + <p> + A keyfile can be designed by the key identification + <code class="filename">Knnnn.+aaa+iiiii</code> or the full file name + <code class="filename">Knnnn.+aaa+iiiii.key</code> as generated by + <span class="refentrytitle">dnssec-keygen</span>(8). + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.10.11"></a><h2>SEE ALSO</h2> + + <p><span class="citerefentry"> + <span class="refentrytitle">dnssec-keygen</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">dnssec-signzone</span>(8) + </span>, + <em class="citetitle">BIND 9 Administrator Reference Manual</em>, + <em class="citetitle">RFC 5011</em>. + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.dnssec-dsfromkey.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.dnssec-keyfromlabel.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">dnssec-dsfromkey</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">dnssec-keyfromlabel</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.dnssec-keyfromlabel.html b/doc/arm/man.dnssec-keyfromlabel.html new file mode 100644 index 0000000..f1dfcef --- /dev/null +++ b/doc/arm/man.dnssec-keyfromlabel.html @@ -0,0 +1,497 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>dnssec-keyfromlabel</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.dnssec-importkey.html" title="dnssec-importkey"> +<link rel="next" href="man.dnssec-keygen.html" title="dnssec-keygen"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">dnssec-keyfromlabel</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.dnssec-importkey.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.dnssec-keygen.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.dnssec-keyfromlabel"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">dnssec-keyfromlabel</span> + — DNSSEC key generation tool + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">dnssec-keyfromlabel</code> + {-l <em class="replaceable"><code>label</code></em>} + [<code class="option">-3</code>] + [<code class="option">-a <em class="replaceable"><code>algorithm</code></em></code>] + [<code class="option">-A <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-c <em class="replaceable"><code>class</code></em></code>] + [<code class="option">-D <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-D sync <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-E <em class="replaceable"><code>engine</code></em></code>] + [<code class="option">-f <em class="replaceable"><code>flag</code></em></code>] + [<code class="option">-G</code>] + [<code class="option">-I <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-i <em class="replaceable"><code>interval</code></em></code>] + [<code class="option">-k</code>] + [<code class="option">-K <em class="replaceable"><code>directory</code></em></code>] + [<code class="option">-L <em class="replaceable"><code>ttl</code></em></code>] + [<code class="option">-n <em class="replaceable"><code>nametype</code></em></code>] + [<code class="option">-P <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-P sync <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-p <em class="replaceable"><code>protocol</code></em></code>] + [<code class="option">-R <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-S <em class="replaceable"><code>key</code></em></code>] + [<code class="option">-t <em class="replaceable"><code>type</code></em></code>] + [<code class="option">-v <em class="replaceable"><code>level</code></em></code>] + [<code class="option">-V</code>] + [<code class="option">-y</code>] + {name} + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.11.7"></a><h2>DESCRIPTION</h2> + + <p><span class="command"><strong>dnssec-keyfromlabel</strong></span> + generates a key pair of files that referencing a key object stored + in a cryptographic hardware service module (HSM). The private key + file can be used for DNSSEC signing of zone data as if it were a + conventional signing key created by <span class="command"><strong>dnssec-keygen</strong></span>, + but the key material is stored within the HSM, and the actual signing + takes place there. + </p> + <p> + The <code class="option">name</code> of the key is specified on the command + line. This must match the name of the zone for which the key is + being generated. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.11.8"></a><h2>OPTIONS</h2> + + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-a <em class="replaceable"><code>algorithm</code></em></span></dt> +<dd> + <p> + Selects the cryptographic algorithm. The value of + <code class="option">algorithm</code> must be one of RSAMD5, RSASHA1, + DSA, NSEC3RSASHA1, NSEC3DSA, RSASHA256, RSASHA512, ECCGOST, + ECDSAP256SHA256, ECDSAP384SHA384, ED25519 or ED448. + These values are case insensitive. + </p> + <p> + If no algorithm is specified, then RSASHA1 will be used by + default, unless the <code class="option">-3</code> option is specified, + in which case NSEC3RSASHA1 will be used instead. (If + <code class="option">-3</code> is used and an algorithm is specified, + that algorithm will be checked for compatibility with NSEC3.) + </p> + <p> + Note 1: that for DNSSEC, RSASHA1 is a mandatory to implement + algorithm, and DSA is recommended. + </p> + <p> + Note 2: DH automatically sets the -k flag. + </p> + </dd> +<dt><span class="term">-3</span></dt> +<dd> + <p> + Use an NSEC3-capable algorithm to generate a DNSSEC key. + If this option is used and no algorithm is explicitly + set on the command line, NSEC3RSASHA1 will be used by + default. + </p> + </dd> +<dt><span class="term">-E <em class="replaceable"><code>engine</code></em></span></dt> +<dd> + <p> + Specifies the cryptographic hardware to use. + </p> + <p> + When BIND is built with OpenSSL PKCS#11 support, this defaults + to the string "pkcs11", which identifies an OpenSSL engine + that can drive a cryptographic accelerator or hardware service + module. When BIND is built with native PKCS#11 cryptography + (--enable-native-pkcs11), it defaults to the path of the PKCS#11 + provider library specified via "--with-pkcs11". + </p> + </dd> +<dt><span class="term">-l <em class="replaceable"><code>label</code></em></span></dt> +<dd> + <p> + Specifies the label for a key pair in the crypto hardware. + </p> + <p> + When <acronym class="acronym">BIND</acronym> 9 is built with OpenSSL-based + PKCS#11 support, the label is an arbitrary string that + identifies a particular key. It may be preceded by an + optional OpenSSL engine name, followed by a colon, as in + "pkcs11:<em class="replaceable"><code>keylabel</code></em>". + </p> + <p> + When <acronym class="acronym">BIND</acronym> 9 is built with native PKCS#11 + support, the label is a PKCS#11 URI string in the format + "pkcs11:<code class="option">keyword</code>=<em class="replaceable"><code>value</code></em>[<span class="optional">;<code class="option">keyword</code>=<em class="replaceable"><code>value</code></em>;...</span>]" + Keywords include "token", which identifies the HSM; "object", which + identifies the key; and "pin-source", which identifies a file from + which the HSM's PIN code can be obtained. The label will be + stored in the on-disk "private" file. + </p> + <p> + If the label contains a + <code class="option">pin-source</code> field, tools using the generated + key files will be able to use the HSM for signing and other + operations without any need for an operator to manually enter + a PIN. Note: Making the HSM's PIN accessible in this manner + may reduce the security advantage of using an HSM; be sure + this is what you want to do before making use of this feature. + </p> + </dd> +<dt><span class="term">-n <em class="replaceable"><code>nametype</code></em></span></dt> +<dd> + <p> + Specifies the owner type of the key. The value of + <code class="option">nametype</code> must either be ZONE (for a DNSSEC + zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with + a host (KEY)), + USER (for a key associated with a user(KEY)) or OTHER (DNSKEY). + These values are case insensitive. + </p> + </dd> +<dt><span class="term">-C</span></dt> +<dd> + <p> + Compatibility mode: generates an old-style key, without + any metadata. By default, <span class="command"><strong>dnssec-keyfromlabel</strong></span> + will include the key's creation date in the metadata stored + with the private key, and other dates may be set there as well + (publication date, activation date, etc). Keys that include + this data may be incompatible with older versions of BIND; the + <code class="option">-C</code> option suppresses them. + </p> + </dd> +<dt><span class="term">-c <em class="replaceable"><code>class</code></em></span></dt> +<dd> + <p> + Indicates that the DNS record containing the key should have + the specified class. If not specified, class IN is used. + </p> + </dd> +<dt><span class="term">-f <em class="replaceable"><code>flag</code></em></span></dt> +<dd> + <p> + Set the specified flag in the flag field of the KEY/DNSKEY record. + The only recognized flags are KSK (Key Signing Key) and REVOKE. + </p> + </dd> +<dt><span class="term">-G</span></dt> +<dd> + <p> + Generate a key, but do not publish it or sign with it. This + option is incompatible with -P and -A. + </p> + </dd> +<dt><span class="term">-h</span></dt> +<dd> + <p> + Prints a short summary of the options and arguments to + <span class="command"><strong>dnssec-keyfromlabel</strong></span>. + </p> + </dd> +<dt><span class="term">-K <em class="replaceable"><code>directory</code></em></span></dt> +<dd> + <p> + Sets the directory in which the key files are to be written. + </p> + </dd> +<dt><span class="term">-k</span></dt> +<dd> + <p> + Generate KEY records rather than DNSKEY records. + </p> + </dd> +<dt><span class="term">-L <em class="replaceable"><code>ttl</code></em></span></dt> +<dd> + <p> + Sets the default TTL to use for this key when it is converted + into a DNSKEY RR. If the key is imported into a zone, + this is the TTL that will be used for it, unless there was + already a DNSKEY RRset in place, in which case the existing TTL + would take precedence. Setting the default TTL to + <code class="literal">0</code> or <code class="literal">none</code> removes it. + </p> + </dd> +<dt><span class="term">-p <em class="replaceable"><code>protocol</code></em></span></dt> +<dd> + <p> + Sets the protocol value for the key. The protocol + is a number between 0 and 255. The default is 3 (DNSSEC). + Other possible values for this argument are listed in + RFC 2535 and its successors. + </p> + </dd> +<dt><span class="term">-S <em class="replaceable"><code>key</code></em></span></dt> +<dd> + <p> + Generate a key as an explicit successor to an existing key. + The name, algorithm, size, and type of the key will be set + to match the predecessor. The activation date of the new + key will be set to the inactivation date of the existing + one. The publication date will be set to the activation + date minus the prepublication interval, which defaults to + 30 days. + </p> + </dd> +<dt><span class="term">-t <em class="replaceable"><code>type</code></em></span></dt> +<dd> + <p> + Indicates the use of the key. <code class="option">type</code> must be + one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default + is AUTHCONF. AUTH refers to the ability to authenticate + data, and CONF the ability to encrypt data. + </p> + </dd> +<dt><span class="term">-v <em class="replaceable"><code>level</code></em></span></dt> +<dd> + <p> + Sets the debugging level. + </p> + </dd> +<dt><span class="term">-V</span></dt> +<dd> + <p> + Prints version information. + </p> + </dd> +<dt><span class="term">-y</span></dt> +<dd> + <p> + Allows DNSSEC key files to be generated even if the key ID + would collide with that of an existing key, in the event of + either key being revoked. (This is only safe to use if you + are sure you won't be using RFC 5011 trust anchor maintenance + with either of the keys involved.) + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.11.9"></a><h2>TIMING OPTIONS</h2> + + + <p> + Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS. + If the argument begins with a '+' or '-', it is interpreted as + an offset from the present time. For convenience, if such an offset + is followed by one of the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', + then the offset is computed in years (defined as 365 24-hour days, + ignoring leap years), months (defined as 30 24-hour days), weeks, + days, hours, or minutes, respectively. Without a suffix, the offset + is computed in seconds. To explicitly prevent a date from being + set, use 'none' or 'never'. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-P <em class="replaceable"><code>date/offset</code></em></span></dt> +<dd> + <p> + Sets the date on which a key is to be published to the zone. + After that date, the key will be included in the zone but will + not be used to sign it. If not set, and if the -G option has + not been used, the default is "now". + </p> + </dd> +<dt><span class="term">-P sync <em class="replaceable"><code>date/offset</code></em></span></dt> +<dd> + <p> + Sets the date on which the CDS and CDNSKEY records which match + this key are to be published to the zone. + </p> + </dd> +<dt><span class="term">-A <em class="replaceable"><code>date/offset</code></em></span></dt> +<dd> + <p> + Sets the date on which the key is to be activated. After that + date, the key will be included in the zone and used to sign + it. If not set, and if the -G option has not been used, the + default is "now". + </p> + </dd> +<dt><span class="term">-R <em class="replaceable"><code>date/offset</code></em></span></dt> +<dd> + <p> + Sets the date on which the key is to be revoked. After that + date, the key will be flagged as revoked. It will be included + in the zone and will be used to sign it. + </p> + </dd> +<dt><span class="term">-I <em class="replaceable"><code>date/offset</code></em></span></dt> +<dd> + <p> + Sets the date on which the key is to be retired. After that + date, the key will still be included in the zone, but it + will not be used to sign it. + </p> + </dd> +<dt><span class="term">-D <em class="replaceable"><code>date/offset</code></em></span></dt> +<dd> + <p> + Sets the date on which the key is to be deleted. After that + date, the key will no longer be included in the zone. (It + may remain in the key repository, however.) + </p> + </dd> +<dt><span class="term">-D sync <em class="replaceable"><code>date/offset</code></em></span></dt> +<dd> + <p> + Sets the date on which the CDS and CDNSKEY records which match + this key are to be deleted. + </p> + </dd> +<dt><span class="term">-i <em class="replaceable"><code>interval</code></em></span></dt> +<dd> + <p> + Sets the prepublication interval for a key. If set, then + the publication and activation dates must be separated by at least + this much time. If the activation date is specified but the + publication date isn't, then the publication date will default + to this much time before the activation date; conversely, if + the publication date is specified but activation date isn't, + then activation will be set to this much time after publication. + </p> + <p> + If the key is being created as an explicit successor to another + key, then the default prepublication interval is 30 days; + otherwise it is zero. + </p> + <p> + As with date offsets, if the argument is followed by one of + the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', then the + interval is measured in years, months, weeks, days, hours, + or minutes, respectively. Without a suffix, the interval is + measured in seconds. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.11.10"></a><h2>GENERATED KEY FILES</h2> + + <p> + When <span class="command"><strong>dnssec-keyfromlabel</strong></span> completes + successfully, + it prints a string of the form <code class="filename">Knnnn.+aaa+iiiii</code> + to the standard output. This is an identification string for + the key files it has generated. + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <p><code class="filename">nnnn</code> is the key name. + </p> + </li> +<li class="listitem"> + <p><code class="filename">aaa</code> is the numeric representation + of the algorithm. + </p> + </li> +<li class="listitem"> + <p><code class="filename">iiiii</code> is the key identifier (or + footprint). + </p> + </li> +</ul></div> + <p><span class="command"><strong>dnssec-keyfromlabel</strong></span> + creates two files, with names based + on the printed string. <code class="filename">Knnnn.+aaa+iiiii.key</code> + contains the public key, and + <code class="filename">Knnnn.+aaa+iiiii.private</code> contains the + private key. + </p> + <p> + The <code class="filename">.key</code> file contains a DNS KEY record + that + can be inserted into a zone file (directly or with a $INCLUDE + statement). + </p> + <p> + The <code class="filename">.private</code> file contains + algorithm-specific + fields. For obvious security reasons, this file does not have + general read permission. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.11.11"></a><h2>SEE ALSO</h2> + + <p><span class="citerefentry"> + <span class="refentrytitle">dnssec-keygen</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">dnssec-signzone</span>(8) + </span>, + <em class="citetitle">BIND 9 Administrator Reference Manual</em>, + <em class="citetitle">RFC 4034</em>, + <em class="citetitle">The PKCS#11 URI Scheme (draft-pechanec-pkcs11uri-13)</em>. + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.dnssec-importkey.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.dnssec-keygen.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">dnssec-importkey</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">dnssec-keygen</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.dnssec-keygen.html b/doc/arm/man.dnssec-keygen.html new file mode 100644 index 0000000..822b577 --- /dev/null +++ b/doc/arm/man.dnssec-keygen.html @@ -0,0 +1,584 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>dnssec-keygen</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.dnssec-keyfromlabel.html" title="dnssec-keyfromlabel"> +<link rel="next" href="man.dnssec-keymgr.html" title="dnssec-keymgr"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">dnssec-keygen</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.dnssec-keyfromlabel.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.dnssec-keymgr.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.dnssec-keygen"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">dnssec-keygen</span> + — DNSSEC key generation tool + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">dnssec-keygen</code> + [<code class="option">-a <em class="replaceable"><code>algorithm</code></em></code>] + [<code class="option">-b <em class="replaceable"><code>keysize</code></em></code>] + [<code class="option">-n <em class="replaceable"><code>nametype</code></em></code>] + [<code class="option">-3</code>] + [<code class="option">-A <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-C</code>] + [<code class="option">-c <em class="replaceable"><code>class</code></em></code>] + [<code class="option">-D <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-D sync <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-E <em class="replaceable"><code>engine</code></em></code>] + [<code class="option">-f <em class="replaceable"><code>flag</code></em></code>] + [<code class="option">-G</code>] + [<code class="option">-g <em class="replaceable"><code>generator</code></em></code>] + [<code class="option">-h</code>] + [<code class="option">-I <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-i <em class="replaceable"><code>interval</code></em></code>] + [<code class="option">-K <em class="replaceable"><code>directory</code></em></code>] + [<code class="option">-k</code>] + [<code class="option">-L <em class="replaceable"><code>ttl</code></em></code>] + [<code class="option">-P <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-P sync <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-p <em class="replaceable"><code>protocol</code></em></code>] + [<code class="option">-q</code>] + [<code class="option">-R <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-r <em class="replaceable"><code>randomdev</code></em></code>] + [<code class="option">-S <em class="replaceable"><code>key</code></em></code>] + [<code class="option">-s <em class="replaceable"><code>strength</code></em></code>] + [<code class="option">-t <em class="replaceable"><code>type</code></em></code>] + [<code class="option">-V</code>] + [<code class="option">-v <em class="replaceable"><code>level</code></em></code>] + [<code class="option">-z</code>] + {name} + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.12.7"></a><h2>DESCRIPTION</h2> + + <p><span class="command"><strong>dnssec-keygen</strong></span> + generates keys for DNSSEC (Secure DNS), as defined in RFC 2535 + and RFC 4034. It can also generate keys for use with + TSIG (Transaction Signatures) as defined in RFC 2845, or TKEY + (Transaction Key) as defined in RFC 2930. + </p> + <p> + The <code class="option">name</code> of the key is specified on the command + line. For DNSSEC keys, this must match the name of the zone for + which the key is being generated. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.12.8"></a><h2>OPTIONS</h2> + + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-a <em class="replaceable"><code>algorithm</code></em></span></dt> +<dd> + <p> + Selects the cryptographic algorithm. For DNSSEC keys, the value + of <code class="option">algorithm</code> must be one of RSAMD5, RSASHA1, + DSA, NSEC3RSASHA1, NSEC3DSA, RSASHA256, RSASHA512, ECCGOST, + ECDSAP256SHA256, ECDSAP384SHA384, ED25519 or ED448. + For TSIG/TKEY, the value must + be DH (Diffie Hellman), HMAC-MD5, HMAC-SHA1, HMAC-SHA224, + HMAC-SHA256, HMAC-SHA384, or HMAC-SHA512. These values are + case insensitive. + </p> + <p> + If no algorithm is specified, then RSASHA1 will be used by + default, unless the <code class="option">-3</code> option is specified, + in which case NSEC3RSASHA1 will be used instead. (If + <code class="option">-3</code> is used and an algorithm is specified, + that algorithm will be checked for compatibility with NSEC3.) + </p> + <p> + Note 1: that for DNSSEC, RSASHA1 is a mandatory to implement + algorithm, and DSA is recommended. For TSIG, HMAC-MD5 is + mandatory. + </p> + <p> + Note 2: DH, HMAC-MD5, and HMAC-SHA1 through HMAC-SHA512 + automatically set the -T KEY option. + </p> + </dd> +<dt><span class="term">-b <em class="replaceable"><code>keysize</code></em></span></dt> +<dd> + <p> + Specifies the number of bits in the key. The choice of key + size depends on the algorithm used. RSA keys must be + between 512 and 2048 bits. Diffie Hellman keys must be between + 128 and 4096 bits. DSA keys must be between 512 and 1024 + bits and an exact multiple of 64. HMAC keys must be + between 1 and 512 bits. Elliptic curve algorithms don't need + this parameter. + </p> + <p> + The key size does not need to be specified if using a default + algorithm. The default key size is 1024 bits for zone signing + keys (ZSKs) and 2048 bits for key signing keys (KSKs, + generated with <code class="option">-f KSK</code>). However, if an + algorithm is explicitly specified with the <code class="option">-a</code>, + then there is no default key size, and the <code class="option">-b</code> + must be used. + </p> + </dd> +<dt><span class="term">-n <em class="replaceable"><code>nametype</code></em></span></dt> +<dd> + <p> + Specifies the owner type of the key. The value of + <code class="option">nametype</code> must either be ZONE (for a DNSSEC + zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with + a host (KEY)), + USER (for a key associated with a user(KEY)) or OTHER (DNSKEY). + These values are case insensitive. Defaults to ZONE for DNSKEY + generation. + </p> + </dd> +<dt><span class="term">-3</span></dt> +<dd> + <p> + Use an NSEC3-capable algorithm to generate a DNSSEC key. + If this option is used and no algorithm is explicitly + set on the command line, NSEC3RSASHA1 will be used by + default. Note that RSASHA256, RSASHA512, ECCGOST, + ECDSAP256SHA256, ECDSAP384SHA384, ED25519 and ED448 + algorithms are NSEC3-capable. + </p> + </dd> +<dt><span class="term">-C</span></dt> +<dd> + <p> + Compatibility mode: generates an old-style key, without + any metadata. By default, <span class="command"><strong>dnssec-keygen</strong></span> + will include the key's creation date in the metadata stored + with the private key, and other dates may be set there as well + (publication date, activation date, etc). Keys that include + this data may be incompatible with older versions of BIND; the + <code class="option">-C</code> option suppresses them. + </p> + </dd> +<dt><span class="term">-c <em class="replaceable"><code>class</code></em></span></dt> +<dd> + <p> + Indicates that the DNS record containing the key should have + the specified class. If not specified, class IN is used. + </p> + </dd> +<dt><span class="term">-E <em class="replaceable"><code>engine</code></em></span></dt> +<dd> + <p> + Specifies the cryptographic hardware to use, when applicable. + </p> + <p> + When BIND is built with OpenSSL PKCS#11 support, this defaults + to the string "pkcs11", which identifies an OpenSSL engine + that can drive a cryptographic accelerator or hardware service + module. When BIND is built with native PKCS#11 cryptography + (--enable-native-pkcs11), it defaults to the path of the PKCS#11 + provider library specified via "--with-pkcs11". + </p> + </dd> +<dt><span class="term">-f <em class="replaceable"><code>flag</code></em></span></dt> +<dd> + <p> + Set the specified flag in the flag field of the KEY/DNSKEY record. + The only recognized flags are KSK (Key Signing Key) and REVOKE. + </p> + </dd> +<dt><span class="term">-G</span></dt> +<dd> + <p> + Generate a key, but do not publish it or sign with it. This + option is incompatible with -P and -A. + </p> + </dd> +<dt><span class="term">-g <em class="replaceable"><code>generator</code></em></span></dt> +<dd> + <p> + If generating a Diffie Hellman key, use this generator. + Allowed values are 2 and 5. If no generator + is specified, a known prime from RFC 2539 will be used + if possible; otherwise the default is 2. + </p> + </dd> +<dt><span class="term">-h</span></dt> +<dd> + <p> + Prints a short summary of the options and arguments to + <span class="command"><strong>dnssec-keygen</strong></span>. + </p> + </dd> +<dt><span class="term">-K <em class="replaceable"><code>directory</code></em></span></dt> +<dd> + <p> + Sets the directory in which the key files are to be written. + </p> + </dd> +<dt><span class="term">-k</span></dt> +<dd> + <p> + Deprecated in favor of -T KEY. + </p> + </dd> +<dt><span class="term">-L <em class="replaceable"><code>ttl</code></em></span></dt> +<dd> + <p> + Sets the default TTL to use for this key when it is converted + into a DNSKEY RR. If the key is imported into a zone, + this is the TTL that will be used for it, unless there was + already a DNSKEY RRset in place, in which case the existing TTL + would take precedence. If this value is not set and there + is no existing DNSKEY RRset, the TTL will default to the + SOA TTL. Setting the default TTL to <code class="literal">0</code> + or <code class="literal">none</code> is the same as leaving it unset. + </p> + </dd> +<dt><span class="term">-p <em class="replaceable"><code>protocol</code></em></span></dt> +<dd> + <p> + Sets the protocol value for the generated key. The protocol + is a number between 0 and 255. The default is 3 (DNSSEC). + Other possible values for this argument are listed in + RFC 2535 and its successors. + </p> + </dd> +<dt><span class="term">-q</span></dt> +<dd> + <p> + Quiet mode: Suppresses unnecessary output, including + progress indication. Without this option, when + <span class="command"><strong>dnssec-keygen</strong></span> is run interactively + to generate an RSA or DSA key pair, it will print a string + of symbols to <code class="filename">stderr</code> indicating the + progress of the key generation. A '.' indicates that a + random number has been found which passed an initial + sieve test; '+' means a number has passed a single + round of the Miller-Rabin primality test; a space + means that the number has passed all the tests and is + a satisfactory key. + </p> + </dd> +<dt><span class="term">-r <em class="replaceable"><code>randomdev</code></em></span></dt> +<dd> + <p> + Specifies the source of randomness. If the operating + system does not provide a <code class="filename">/dev/random</code> + or equivalent device, the default source of randomness + is keyboard input. <code class="filename">randomdev</code> + specifies + the name of a character device or file containing random + data to be used instead of the default. The special value + <code class="filename">keyboard</code> indicates that keyboard + input should be used. + </p> + </dd> +<dt><span class="term">-S <em class="replaceable"><code>key</code></em></span></dt> +<dd> + <p> + Create a new key which is an explicit successor to an + existing key. The name, algorithm, size, and type of the + key will be set to match the existing key. The activation + date of the new key will be set to the inactivation date of + the existing one. The publication date will be set to the + activation date minus the prepublication interval, which + defaults to 30 days. + </p> + </dd> +<dt><span class="term">-s <em class="replaceable"><code>strength</code></em></span></dt> +<dd> + <p> + Specifies the strength value of the key. The strength is + a number between 0 and 15, and currently has no defined + purpose in DNSSEC. + </p> + </dd> +<dt><span class="term">-T <em class="replaceable"><code>rrtype</code></em></span></dt> +<dd> + <p> + Specifies the resource record type to use for the key. + <code class="option">rrtype</code> must be either DNSKEY or KEY. The + default is DNSKEY when using a DNSSEC algorithm, but it can be + overridden to KEY for use with SIG(0). + </p> +<p> + </p> +<p> + Using any TSIG algorithm (HMAC-* or DH) forces this option + to KEY. + </p> + </dd> +<dt><span class="term">-t <em class="replaceable"><code>type</code></em></span></dt> +<dd> + <p> + Indicates the use of the key. <code class="option">type</code> must be + one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default + is AUTHCONF. AUTH refers to the ability to authenticate + data, and CONF the ability to encrypt data. + </p> + </dd> +<dt><span class="term">-v <em class="replaceable"><code>level</code></em></span></dt> +<dd> + <p> + Sets the debugging level. + </p> + </dd> +<dt><span class="term">-V</span></dt> +<dd> + <p> + Prints version information. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.12.9"></a><h2>TIMING OPTIONS</h2> + + + <p> + Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS. + If the argument begins with a '+' or '-', it is interpreted as + an offset from the present time. For convenience, if such an offset + is followed by one of the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', + then the offset is computed in years (defined as 365 24-hour days, + ignoring leap years), months (defined as 30 24-hour days), weeks, + days, hours, or minutes, respectively. Without a suffix, the offset + is computed in seconds. To explicitly prevent a date from being + set, use 'none' or 'never'. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-P <em class="replaceable"><code>date/offset</code></em></span></dt> +<dd> + <p> + Sets the date on which a key is to be published to the zone. + After that date, the key will be included in the zone but will + not be used to sign it. If not set, and if the -G option has + not been used, the default is "now". + </p> + </dd> +<dt><span class="term">-P sync <em class="replaceable"><code>date/offset</code></em></span></dt> +<dd> + <p> + Sets the date on which CDS and CDNSKEY records that match this + key are to be published to the zone. + </p> + </dd> +<dt><span class="term">-A <em class="replaceable"><code>date/offset</code></em></span></dt> +<dd> + <p> + Sets the date on which the key is to be activated. After that + date, the key will be included in the zone and used to sign + it. If not set, and if the -G option has not been used, the + default is "now". If set, if and -P is not set, then + the publication date will be set to the activation date + minus the prepublication interval. + </p> + </dd> +<dt><span class="term">-R <em class="replaceable"><code>date/offset</code></em></span></dt> +<dd> + <p> + Sets the date on which the key is to be revoked. After that + date, the key will be flagged as revoked. It will be included + in the zone and will be used to sign it. + </p> + </dd> +<dt><span class="term">-I <em class="replaceable"><code>date/offset</code></em></span></dt> +<dd> + <p> + Sets the date on which the key is to be retired. After that + date, the key will still be included in the zone, but it + will not be used to sign it. + </p> + </dd> +<dt><span class="term">-D <em class="replaceable"><code>date/offset</code></em></span></dt> +<dd> + <p> + Sets the date on which the key is to be deleted. After that + date, the key will no longer be included in the zone. (It + may remain in the key repository, however.) + </p> + </dd> +<dt><span class="term">-D sync <em class="replaceable"><code>date/offset</code></em></span></dt> +<dd> + <p> + Sets the date on which the CDS and CDNSKEY records that match this + key are to be deleted. + </p> + </dd> +<dt><span class="term">-i <em class="replaceable"><code>interval</code></em></span></dt> +<dd> + <p> + Sets the prepublication interval for a key. If set, then + the publication and activation dates must be separated by at least + this much time. If the activation date is specified but the + publication date isn't, then the publication date will default + to this much time before the activation date; conversely, if + the publication date is specified but activation date isn't, + then activation will be set to this much time after publication. + </p> + <p> + If the key is being created as an explicit successor to another + key, then the default prepublication interval is 30 days; + otherwise it is zero. + </p> + <p> + As with date offsets, if the argument is followed by one of + the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', then the + interval is measured in years, months, weeks, days, hours, + or minutes, respectively. Without a suffix, the interval is + measured in seconds. + </p> + </dd> +</dl></div> + </div> + + + <div class="refsection"> +<a name="id-1.14.12.10"></a><h2>GENERATED KEYS</h2> + + <p> + When <span class="command"><strong>dnssec-keygen</strong></span> completes + successfully, + it prints a string of the form <code class="filename">Knnnn.+aaa+iiiii</code> + to the standard output. This is an identification string for + the key it has generated. + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <p><code class="filename">nnnn</code> is the key name. + </p> + </li> +<li class="listitem"> + <p><code class="filename">aaa</code> is the numeric representation + of the + algorithm. + </p> + </li> +<li class="listitem"> + <p><code class="filename">iiiii</code> is the key identifier (or + footprint). + </p> + </li> +</ul></div> + <p><span class="command"><strong>dnssec-keygen</strong></span> + creates two files, with names based + on the printed string. <code class="filename">Knnnn.+aaa+iiiii.key</code> + contains the public key, and + <code class="filename">Knnnn.+aaa+iiiii.private</code> contains the + private + key. + </p> + <p> + The <code class="filename">.key</code> file contains a DNS KEY record + that + can be inserted into a zone file (directly or with a $INCLUDE + statement). + </p> + <p> + The <code class="filename">.private</code> file contains + algorithm-specific + fields. For obvious security reasons, this file does not have + general read permission. + </p> + <p> + Both <code class="filename">.key</code> and <code class="filename">.private</code> + files are generated for symmetric cryptography algorithms such as + HMAC-MD5, even though the public and private key are equivalent. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.12.11"></a><h2>EXAMPLE</h2> + + <p> + To generate a 768-bit DSA key for the domain + <strong class="userinput"><code>example.com</code></strong>, the following command would be + issued: + </p> + <p><strong class="userinput"><code>dnssec-keygen -a DSA -b 768 -n ZONE example.com</code></strong> + </p> + <p> + The command would print a string of the form: + </p> + <p><strong class="userinput"><code>Kexample.com.+003+26160</code></strong> + </p> + <p> + In this example, <span class="command"><strong>dnssec-keygen</strong></span> creates + the files <code class="filename">Kexample.com.+003+26160.key</code> + and + <code class="filename">Kexample.com.+003+26160.private</code>. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.12.12"></a><h2>SEE ALSO</h2> + + <p><span class="citerefentry"> + <span class="refentrytitle">dnssec-signzone</span>(8) + </span>, + <em class="citetitle">BIND 9 Administrator Reference Manual</em>, + <em class="citetitle">RFC 2539</em>, + <em class="citetitle">RFC 2845</em>, + <em class="citetitle">RFC 4034</em>. + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.dnssec-keyfromlabel.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.dnssec-keymgr.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">dnssec-keyfromlabel</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">dnssec-keymgr</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.dnssec-keymgr.html b/doc/arm/man.dnssec-keymgr.html new file mode 100644 index 0000000..c8ee7ca --- /dev/null +++ b/doc/arm/man.dnssec-keymgr.html @@ -0,0 +1,403 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>dnssec-keymgr</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.dnssec-keygen.html" title="dnssec-keygen"> +<link rel="next" href="man.dnssec-revoke.html" title="dnssec-revoke"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">dnssec-keymgr</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.dnssec-keygen.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.dnssec-revoke.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.dnssec-keymgr"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">dnssec-keymgr</span> + — Ensures correct DNSKEY coverage for a zone based on a defined policy + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">dnssec-keymgr</code> + [<code class="option">-K <em class="replaceable"><code>directory</code></em></code>] + [<code class="option">-c <em class="replaceable"><code>file</code></em></code>] + [<code class="option">-f</code>] + [<code class="option">-k</code>] + [<code class="option">-q</code>] + [<code class="option">-v</code>] + [<code class="option">-z</code>] + [<code class="option">-g <em class="replaceable"><code>path</code></em></code>] + [<code class="option">-r <em class="replaceable"><code>path</code></em></code>] + [<code class="option">-s <em class="replaceable"><code>path</code></em></code>] + [zone...] + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.13.7"></a><h2>DESCRIPTION</h2> + <p> + <span class="command"><strong>dnssec-keymgr</strong></span> is a high level Python wrapper + to facilitate the key rollover process for zones handled by + BIND. It uses the BIND commands for manipulating DNSSEC key + metadata: <span class="command"><strong>dnssec-keygen</strong></span> and + <span class="command"><strong>dnssec-settime</strong></span>. + </p> + <p> + DNSSEC policy can be read from a configuration file (default + <code class="filename">/etc/dnssec-policy.conf</code>), from which the key + parameters, publication and rollover schedule, and desired + coverage duration for any given zone can be determined. This + file may be used to define individual DNSSEC policies on a + per-zone basis, or to set a default policy used for all zones. + </p> + <p> + When <span class="command"><strong>dnssec-keymgr</strong></span> runs, it examines the DNSSEC + keys for one or more zones, comparing their timing metadata against + the policies for those zones. If key settings do not conform to the + DNSSEC policy (for example, because the policy has been changed), + they are automatically corrected. + </p> + <p> + A zone policy can specify a duration for which we want to + ensure the key correctness (<code class="option">coverage</code>). It can + also specify a rollover period (<code class="option">roll-period</code>). + If policy indicates that a key should roll over before the + coverage period ends, then a successor key will automatically be + created and added to the end of the key series. + </p> + <p> + If zones are specified on the command line, + <span class="command"><strong>dnssec-keymgr</strong></span> will examine only those zones. + If a specified zone does not already have keys in place, then + keys will be generated for it according to policy. + </p> + <p> + If zones are <span class="emphasis"><em>not</em></span> specified on the command + line, then <span class="command"><strong>dnssec-keymgr</strong></span> will search the + key directory (either the current working directory or the directory + set by the <code class="option">-K</code> option), and check the keys for + all the zones represented in the directory. + </p> + <p> + It is expected that this tool will be run automatically and + unattended (for example, by <span class="command"><strong>cron</strong></span>). + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.13.8"></a><h2>OPTIONS</h2> + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-c <em class="replaceable"><code>file</code></em></span></dt> +<dd> + <p> + If <code class="option">-c</code> is specified, then the DNSSEC + policy is read from <code class="option">file</code>. (If not + specified, then the policy is read from + <code class="filename">/etc/dnssec-policy.conf</code>; if that file + doesn't exist, a built-in global default policy is used.) + </p> + </dd> +<dt><span class="term">-f</span></dt> +<dd> + <p> + Force: allow updating of key events even if they are + already in the past. This is not recommended for use with + zones in which keys have already been published. However, + if a set of keys has been generated all of which have + publication and activation dates in the past, but the + keys have not been published in a zone as yet, then this + option can be used to clean them up and turn them into a + proper series of keys with appropriate rollover intervals. + </p> + </dd> +<dt><span class="term">-g <em class="replaceable"><code>keygen-path</code></em></span></dt> +<dd> + <p> + Specifies a path to a <span class="command"><strong>dnssec-keygen</strong></span> binary. + Used for testing. + See also the <code class="option">-s</code> option. + </p> + </dd> +<dt><span class="term">-h</span></dt> +<dd> + <p> + Print the <span class="command"><strong>dnssec-keymgr</strong></span> help summary + and exit. + </p> + </dd> +<dt><span class="term">-K <em class="replaceable"><code>directory</code></em></span></dt> +<dd> + <p> + Sets the directory in which keys can be found. Defaults to the + current working directory. + </p> + </dd> +<dt><span class="term">-k</span></dt> +<dd> + <p> + Only apply policies to KSK keys. + See also the <code class="option">-z</code> option. + </p> + </dd> +<dt><span class="term">-q</span></dt> +<dd> + <p> + Quiet: suppress printing of <span class="command"><strong>dnssec-keygen</strong></span> + and <span class="command"><strong>dnssec-settime</strong></span>. + </p> + </dd> +<dt><span class="term">-r <em class="replaceable"><code>randomdev</code></em></span></dt> +<dd> + <p> + Specifies a path to a file containing random data. + This is passed to the <span class="command"><strong>dnssec-keygen</strong></span> binary + using its <code class="option">-r</code> option. + + </p> + </dd> +<dt><span class="term">-s <em class="replaceable"><code>settime-path</code></em></span></dt> +<dd> + <p> + Specifies a path to a <span class="command"><strong>dnssec-settime</strong></span> binary. + Used for testing. + See also the <code class="option">-g</code> option. + </p> + </dd> +<dt><span class="term">-v</span></dt> +<dd> + <p> + Print the <span class="command"><strong>dnssec-keymgr</strong></span> version and exit. + </p> + </dd> +<dt><span class="term">-z</span></dt> +<dd> + <p> + Only apply policies to ZSK keys. + See also the <code class="option">-k</code> option. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.13.9"></a><h2>POLICY CONFIGURATION</h2> + <p> + The <code class="filename">dnssec-policy.conf</code> file can specify three kinds + of policies: + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <p> + <span class="emphasis"><em>Policy classes</em></span> + (<code class="option">policy <em class="replaceable"><code>name</code></em> { ... };</code>) + can be inherited by zone policies or other policy classes; these + can be used to create sets of different security profiles. For + example, a policy class <strong class="userinput"><code>normal</code></strong> might specify + 1024-bit key sizes, but a class <strong class="userinput"><code>extra</code></strong> might + specify 2048 bits instead; <strong class="userinput"><code>extra</code></strong> would be + used for zones that had unusually high security needs. + </p> + </li> +<li class="listitem"> + <p> + Algorithm policies: + (<code class="option">algorithm-policy <em class="replaceable"><code>algorithm</code></em> { ... };</code> ) + override default per-algorithm settings. For example, by default, + RSASHA256 keys use 2048-bit key sizes for both KSK and ZSK. This + can be modified using <span class="command"><strong>algorithm-policy</strong></span>, and the + new key sizes would then be used for any key of type RSASHA256. + </p> + </li> +<li class="listitem"> + <p> + Zone policies: + (<code class="option">zone <em class="replaceable"><code>name</code></em> { ... };</code> ) + set policy for a single zone by name. A zone policy can inherit + a policy class by including a <code class="option">policy</code> option. + Zone names beginning with digits (i.e., 0-9) must be quoted. + </p> + </li> +</ul></div> + <p> + Options that can be specified in policies: + </p> + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>algorithm</strong></span></span></dt> +<dd> + <p> + The key algorithm. If no policy is defined, the default is + RSASHA256. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>coverage</strong></span></span></dt> +<dd> + <p> + The length of time to ensure that keys will be correct; no action + will be taken to create new keys to be activated after this time. + This can be represented as a number of seconds, or as a duration using + human-readable units (examples: "1y" or "6 months"). + A default value for this option can be set in algorithm policies + as well as in policy classes or zone policies. + If no policy is configured, the default is six months. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>directory</strong></span></span></dt> +<dd> + <p> + Specifies the directory in which keys should be stored. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>key-size</strong></span></span></dt> +<dd> + <p> + Specifies the number of bits to use in creating keys. + Takes two arguments: keytype (eihter "zsk" or "ksk") and size. + A default value for this option can be set in algorithm policies + as well as in policy classes or zone policies. If no policy is + configured, the default is 1024 bits for DSA keys and 2048 for + RSA. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>keyttl</strong></span></span></dt> +<dd> + <p> + The key TTL. If no policy is defined, the default is one hour. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>post-publish</strong></span></span></dt> +<dd> + <p> + How long after inactivation a key should be deleted from the zone. + Note: If <code class="option">roll-period</code> is not set, this value is + ignored. Takes two arguments: keytype (eihter "zsk" or "ksk") and a + duration. A default value for this option can be set in algorithm + policies as well as in policy classes or zone policies. The default + is one month. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>pre-publish</strong></span></span></dt> +<dd> + <p> + How long before activation a key should be published. Note: If + <code class="option">roll-period</code> is not set, this value is ignored. + Takes two arguments: keytype (either "zsk" or "ksk") and a duration. + A default value for this option can be set in algorithm policies + as well as in policy classes or zone policies. The default is + one month. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>roll-period</strong></span></span></dt> +<dd> + <p> + How frequently keys should be rolled over. + Takes two arguments: keytype (eihter "zsk" or "ksk") and a duration. + A default value for this option can be set in algorithm policies + as well as in policy classes or zone policies. If no policy is + configured, the default is one year for ZSK's. KSK's do not + roll over by default. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>standby</strong></span></span></dt> +<dd> + <p> + Not yet implemented. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.13.10"></a><h2>REMAINING WORK</h2> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <p> + Enable scheduling of KSK rollovers using the <code class="option">-P sync</code> + and <code class="option">-D sync</code> options to + <span class="command"><strong>dnssec-keygen</strong></span> and + <span class="command"><strong>dnssec-settime</strong></span>. Check the parent zone + (as in <span class="command"><strong>dnssec-checkds</strong></span>) to determine when it's + safe for the key to roll. + </p> + </li> +<li class="listitem"> + <p> + Allow configuration of standby keys and use of the REVOKE bit, + for keys that use RFC 5011 semantics. + </p> + </li> +</ul></div> + </div> + + <div class="refsection"> +<a name="id-1.14.13.11"></a><h2>SEE ALSO</h2> + <p> + <span class="citerefentry"> + <span class="refentrytitle">dnssec-coverage</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">dnssec-keygen</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">dnssec-settime</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">dnssec-checkds</span>(8) + </span> + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.dnssec-keygen.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.dnssec-revoke.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">dnssec-keygen</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">dnssec-revoke</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.dnssec-revoke.html b/doc/arm/man.dnssec-revoke.html new file mode 100644 index 0000000..33ddb2f --- /dev/null +++ b/doc/arm/man.dnssec-revoke.html @@ -0,0 +1,176 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>dnssec-revoke</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.dnssec-keymgr.html" title="dnssec-keymgr"> +<link rel="next" href="man.dnssec-settime.html" title="dnssec-settime"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">dnssec-revoke</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.dnssec-keymgr.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.dnssec-settime.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.dnssec-revoke"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">dnssec-revoke</span> + — set the REVOKED bit on a DNSSEC key + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">dnssec-revoke</code> + [<code class="option">-hr</code>] + [<code class="option">-v <em class="replaceable"><code>level</code></em></code>] + [<code class="option">-V</code>] + [<code class="option">-K <em class="replaceable"><code>directory</code></em></code>] + [<code class="option">-E <em class="replaceable"><code>engine</code></em></code>] + [<code class="option">-f</code>] + [<code class="option">-R</code>] + {keyfile} + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.14.7"></a><h2>DESCRIPTION</h2> + + <p><span class="command"><strong>dnssec-revoke</strong></span> + reads a DNSSEC key file, sets the REVOKED bit on the key as defined + in RFC 5011, and creates a new pair of key files containing the + now-revoked key. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.14.8"></a><h2>OPTIONS</h2> + + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-h</span></dt> +<dd> + <p> + Emit usage message and exit. + </p> + </dd> +<dt><span class="term">-K <em class="replaceable"><code>directory</code></em></span></dt> +<dd> + <p> + Sets the directory in which the key files are to reside. + </p> + </dd> +<dt><span class="term">-r</span></dt> +<dd> + <p> + After writing the new keyset files remove the original keyset + files. + </p> + </dd> +<dt><span class="term">-v <em class="replaceable"><code>level</code></em></span></dt> +<dd> + <p> + Sets the debugging level. + </p> + </dd> +<dt><span class="term">-V</span></dt> +<dd> + <p> + Prints version information. + </p> + </dd> +<dt><span class="term">-E <em class="replaceable"><code>engine</code></em></span></dt> +<dd> + <p> + Specifies the cryptographic hardware to use, when applicable. + </p> + <p> + When BIND is built with OpenSSL PKCS#11 support, this defaults + to the string "pkcs11", which identifies an OpenSSL engine + that can drive a cryptographic accelerator or hardware service + module. When BIND is built with native PKCS#11 cryptography + (--enable-native-pkcs11), it defaults to the path of the PKCS#11 + provider library specified via "--with-pkcs11". + </p> + </dd> +<dt><span class="term">-f</span></dt> +<dd> + <p> + Force overwrite: Causes <span class="command"><strong>dnssec-revoke</strong></span> to + write the new key pair even if a file already exists matching + the algorithm and key ID of the revoked key. + </p> + </dd> +<dt><span class="term">-R</span></dt> +<dd> + <p> + Print the key tag of the key with the REVOKE bit set but do + not revoke the key. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.14.9"></a><h2>SEE ALSO</h2> + + <p><span class="citerefentry"> + <span class="refentrytitle">dnssec-keygen</span>(8) + </span>, + <em class="citetitle">BIND 9 Administrator Reference Manual</em>, + <em class="citetitle">RFC 5011</em>. + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.dnssec-keymgr.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.dnssec-settime.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">dnssec-keymgr</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">dnssec-settime</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.dnssec-settime.html b/doc/arm/man.dnssec-settime.html new file mode 100644 index 0000000..6b32c07 --- /dev/null +++ b/doc/arm/man.dnssec-settime.html @@ -0,0 +1,354 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>dnssec-settime</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.dnssec-revoke.html" title="dnssec-revoke"> +<link rel="next" href="man.dnssec-signzone.html" title="dnssec-signzone"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">dnssec-settime</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.dnssec-revoke.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.dnssec-signzone.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.dnssec-settime"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">dnssec-settime</span> + — set the key timing metadata for a DNSSEC key + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">dnssec-settime</code> + [<code class="option">-f</code>] + [<code class="option">-K <em class="replaceable"><code>directory</code></em></code>] + [<code class="option">-L <em class="replaceable"><code>ttl</code></em></code>] + [<code class="option">-P <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-P sync <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-A <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-R <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-I <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-D <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-D sync <em class="replaceable"><code>date/offset</code></em></code>] + [<code class="option">-S <em class="replaceable"><code>key</code></em></code>] + [<code class="option">-i <em class="replaceable"><code>interval</code></em></code>] + [<code class="option">-h</code>] + [<code class="option">-V</code>] + [<code class="option">-v <em class="replaceable"><code>level</code></em></code>] + [<code class="option">-E <em class="replaceable"><code>engine</code></em></code>] + {keyfile} + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.15.7"></a><h2>DESCRIPTION</h2> + + <p><span class="command"><strong>dnssec-settime</strong></span> + reads a DNSSEC private key file and sets the key timing metadata + as specified by the <code class="option">-P</code>, <code class="option">-A</code>, + <code class="option">-R</code>, <code class="option">-I</code>, and <code class="option">-D</code> + options. The metadata can then be used by + <span class="command"><strong>dnssec-signzone</strong></span> or other signing software to + determine when a key is to be published, whether it should be + used for signing a zone, etc. + </p> + <p> + If none of these options is set on the command line, + then <span class="command"><strong>dnssec-settime</strong></span> simply prints the key timing + metadata already stored in the key. + </p> + <p> + When key metadata fields are changed, both files of a key + pair (<code class="filename">Knnnn.+aaa+iiiii.key</code> and + <code class="filename">Knnnn.+aaa+iiiii.private</code>) are regenerated. + Metadata fields are stored in the private file. A human-readable + description of the metadata is also placed in comments in the key + file. The private file's permissions are always set to be + inaccessible to anyone other than the owner (mode 0600). + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.15.8"></a><h2>OPTIONS</h2> + + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-f</span></dt> +<dd> + <p> + Force an update of an old-format key with no metadata fields. + Without this option, <span class="command"><strong>dnssec-settime</strong></span> will + fail when attempting to update a legacy key. With this option, + the key will be recreated in the new format, but with the + original key data retained. The key's creation date will be + set to the present time. If no other values are specified, + then the key's publication and activation dates will also + be set to the present time. + </p> + </dd> +<dt><span class="term">-K <em class="replaceable"><code>directory</code></em></span></dt> +<dd> + <p> + Sets the directory in which the key files are to reside. + </p> + </dd> +<dt><span class="term">-L <em class="replaceable"><code>ttl</code></em></span></dt> +<dd> + <p> + Sets the default TTL to use for this key when it is converted + into a DNSKEY RR. If the key is imported into a zone, + this is the TTL that will be used for it, unless there was + already a DNSKEY RRset in place, in which case the existing TTL + would take precedence. If this value is not set and there + is no existing DNSKEY RRset, the TTL will default to the + SOA TTL. Setting the default TTL to <code class="literal">0</code> + or <code class="literal">none</code> removes it from the key. + </p> + </dd> +<dt><span class="term">-h</span></dt> +<dd> + <p> + Emit usage message and exit. + </p> + </dd> +<dt><span class="term">-V</span></dt> +<dd> + <p> + Prints version information. + </p> + </dd> +<dt><span class="term">-v <em class="replaceable"><code>level</code></em></span></dt> +<dd> + <p> + Sets the debugging level. + </p> + </dd> +<dt><span class="term">-E <em class="replaceable"><code>engine</code></em></span></dt> +<dd> + <p> + Specifies the cryptographic hardware to use, when applicable. + </p> + <p> + When BIND is built with OpenSSL PKCS#11 support, this defaults + to the string "pkcs11", which identifies an OpenSSL engine + that can drive a cryptographic accelerator or hardware service + module. When BIND is built with native PKCS#11 cryptography + (--enable-native-pkcs11), it defaults to the path of the PKCS#11 + provider library specified via "--with-pkcs11". + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.15.9"></a><h2>TIMING OPTIONS</h2> + + <p> + Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS. + If the argument begins with a '+' or '-', it is interpreted as + an offset from the present time. For convenience, if such an offset + is followed by one of the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', + then the offset is computed in years (defined as 365 24-hour days, + ignoring leap years), months (defined as 30 24-hour days), weeks, + days, hours, or minutes, respectively. Without a suffix, the offset + is computed in seconds. To unset a date, use 'none' or 'never'. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-P <em class="replaceable"><code>date/offset</code></em></span></dt> +<dd> + <p> + Sets the date on which a key is to be published to the zone. + After that date, the key will be included in the zone but will + not be used to sign it. + </p> + </dd> +<dt><span class="term">-P sync <em class="replaceable"><code>date/offset</code></em></span></dt> +<dd> + <p> + Sets the date on which CDS and CDNSKEY records that match this + key are to be published to the zone. + </p> + </dd> +<dt><span class="term">-A <em class="replaceable"><code>date/offset</code></em></span></dt> +<dd> + <p> + Sets the date on which the key is to be activated. After that + date, the key will be included in the zone and used to sign + it. + </p> + </dd> +<dt><span class="term">-R <em class="replaceable"><code>date/offset</code></em></span></dt> +<dd> + <p> + Sets the date on which the key is to be revoked. After that + date, the key will be flagged as revoked. It will be included + in the zone and will be used to sign it. + </p> + </dd> +<dt><span class="term">-I <em class="replaceable"><code>date/offset</code></em></span></dt> +<dd> + <p> + Sets the date on which the key is to be retired. After that + date, the key will still be included in the zone, but it + will not be used to sign it. + </p> + </dd> +<dt><span class="term">-D <em class="replaceable"><code>date/offset</code></em></span></dt> +<dd> + <p> + Sets the date on which the key is to be deleted. After that + date, the key will no longer be included in the zone. (It + may remain in the key repository, however.) + </p> + </dd> +<dt><span class="term">-D sync <em class="replaceable"><code>date/offset</code></em></span></dt> +<dd> + <p> + Sets the date on which the CDS and CDNSKEY records that match this + key are to be deleted. + </p> + </dd> +<dt><span class="term">-S <em class="replaceable"><code>predecessor key</code></em></span></dt> +<dd> + <p> + Select a key for which the key being modified will be an + explicit successor. The name, algorithm, size, and type of the + predecessor key must exactly match those of the key being + modified. The activation date of the successor key will be set + to the inactivation date of the predecessor. The publication + date will be set to the activation date minus the prepublication + interval, which defaults to 30 days. + </p> + </dd> +<dt><span class="term">-i <em class="replaceable"><code>interval</code></em></span></dt> +<dd> + <p> + Sets the prepublication interval for a key. If set, then + the publication and activation dates must be separated by at least + this much time. If the activation date is specified but the + publication date isn't, then the publication date will default + to this much time before the activation date; conversely, if + the publication date is specified but activation date isn't, + then activation will be set to this much time after publication. + </p> + <p> + If the key is being set to be an explicit successor to another + key, then the default prepublication interval is 30 days; + otherwise it is zero. + </p> + <p> + As with date offsets, if the argument is followed by one of + the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', then the + interval is measured in years, months, weeks, days, hours, + or minutes, respectively. Without a suffix, the interval is + measured in seconds. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.15.10"></a><h2>PRINTING OPTIONS</h2> + + <p> + <span class="command"><strong>dnssec-settime</strong></span> can also be used to print the + timing metadata associated with a key. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-u</span></dt> +<dd> + <p> + Print times in UNIX epoch format. + </p> + </dd> +<dt><span class="term">-p <em class="replaceable"><code>C/P/Psync/A/R/I/D/Dsync/all</code></em></span></dt> +<dd> + <p> + Print a specific metadata value or set of metadata values. + The <code class="option">-p</code> option may be followed by one or more + of the following letters or strings to indicate which value + or values to print: + <code class="option">C</code> for the creation date, + <code class="option">P</code> for the publication date, + <code class="option">Psync</code> for the CDS and CDNSKEY publication date, + <code class="option">A</code> for the activation date, + <code class="option">R</code> for the revocation date, + <code class="option">I</code> for the inactivation date, + <code class="option">D</code> for the deletion date, and + <code class="option">Dsync</code> for the CDS and CDNSKEY deletion date + To print all of the metadata, use <code class="option">-p all</code>. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.15.11"></a><h2>SEE ALSO</h2> + + <p><span class="citerefentry"> + <span class="refentrytitle">dnssec-keygen</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">dnssec-signzone</span>(8) + </span>, + <em class="citetitle">BIND 9 Administrator Reference Manual</em>, + <em class="citetitle">RFC 5011</em>. + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.dnssec-revoke.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.dnssec-signzone.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">dnssec-revoke</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">dnssec-signzone</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.dnssec-signzone.html b/doc/arm/man.dnssec-signzone.html new file mode 100644 index 0000000..8d0e2b5 --- /dev/null +++ b/doc/arm/man.dnssec-signzone.html @@ -0,0 +1,713 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>dnssec-signzone</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.dnssec-settime.html" title="dnssec-settime"> +<link rel="next" href="man.dnssec-verify.html" title="dnssec-verify"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">dnssec-signzone</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.dnssec-settime.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.dnssec-verify.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.dnssec-signzone"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">dnssec-signzone</span> + — DNSSEC zone signing tool + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">dnssec-signzone</code> + [<code class="option">-a</code>] + [<code class="option">-c <em class="replaceable"><code>class</code></em></code>] + [<code class="option">-d <em class="replaceable"><code>directory</code></em></code>] + [<code class="option">-D</code>] + [<code class="option">-E <em class="replaceable"><code>engine</code></em></code>] + [<code class="option">-e <em class="replaceable"><code>end-time</code></em></code>] + [<code class="option">-f <em class="replaceable"><code>output-file</code></em></code>] + [<code class="option">-g</code>] + [<code class="option">-h</code>] + [<code class="option">-i <em class="replaceable"><code>interval</code></em></code>] + [<code class="option">-I <em class="replaceable"><code>input-format</code></em></code>] + [<code class="option">-j <em class="replaceable"><code>jitter</code></em></code>] + [<code class="option">-K <em class="replaceable"><code>directory</code></em></code>] + [<code class="option">-k <em class="replaceable"><code>key</code></em></code>] + [<code class="option">-L <em class="replaceable"><code>serial</code></em></code>] + [<code class="option">-l <em class="replaceable"><code>domain</code></em></code>] + [<code class="option">-M <em class="replaceable"><code>maxttl</code></em></code>] + [<code class="option">-N <em class="replaceable"><code>soa-serial-format</code></em></code>] + [<code class="option">-o <em class="replaceable"><code>origin</code></em></code>] + [<code class="option">-O <em class="replaceable"><code>output-format</code></em></code>] + [<code class="option">-P</code>] + [<code class="option">-p</code>] + [<code class="option">-Q</code>] + [<code class="option">-R</code>] + [<code class="option">-r <em class="replaceable"><code>randomdev</code></em></code>] + [<code class="option">-S</code>] + [<code class="option">-s <em class="replaceable"><code>start-time</code></em></code>] + [<code class="option">-T <em class="replaceable"><code>ttl</code></em></code>] + [<code class="option">-t</code>] + [<code class="option">-u</code>] + [<code class="option">-v <em class="replaceable"><code>level</code></em></code>] + [<code class="option">-V</code>] + [<code class="option">-X <em class="replaceable"><code>extended end-time</code></em></code>] + [<code class="option">-x</code>] + [<code class="option">-z</code>] + [<code class="option">-3 <em class="replaceable"><code>salt</code></em></code>] + [<code class="option">-H <em class="replaceable"><code>iterations</code></em></code>] + [<code class="option">-A</code>] + {zonefile} + [key...] + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.16.7"></a><h2>DESCRIPTION</h2> + + <p><span class="command"><strong>dnssec-signzone</strong></span> + signs a zone. It generates + NSEC and RRSIG records and produces a signed version of the + zone. The security status of delegations from the signed zone + (that is, whether the child zones are secure or not) is + determined by the presence or absence of a + <code class="filename">keyset</code> file for each child zone. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.16.8"></a><h2>OPTIONS</h2> + + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-a</span></dt> +<dd> + <p> + Verify all generated signatures. + </p> + </dd> +<dt><span class="term">-c <em class="replaceable"><code>class</code></em></span></dt> +<dd> + <p> + Specifies the DNS class of the zone. + </p> + </dd> +<dt><span class="term">-C</span></dt> +<dd> + <p> + Compatibility mode: Generate a + <code class="filename">keyset-<em class="replaceable"><code>zonename</code></em></code> + file in addition to + <code class="filename">dsset-<em class="replaceable"><code>zonename</code></em></code> + when signing a zone, for use by older versions of + <span class="command"><strong>dnssec-signzone</strong></span>. + </p> + </dd> +<dt><span class="term">-d <em class="replaceable"><code>directory</code></em></span></dt> +<dd> + <p> + Look for <code class="filename">dsset-</code> or + <code class="filename">keyset-</code> files in <code class="option">directory</code>. + </p> + </dd> +<dt><span class="term">-D</span></dt> +<dd> + <p> + Output only those record types automatically managed by + <span class="command"><strong>dnssec-signzone</strong></span>, i.e. RRSIG, NSEC, + NSEC3 and NSEC3PARAM records. If smart signing + (<code class="option">-S</code>) is used, DNSKEY records are also + included. The resulting file can be included in the original + zone file with <span class="command"><strong>$INCLUDE</strong></span>. This option + cannot be combined with <code class="option">-O raw</code>, + <code class="option">-O map</code>, or serial number updating. + </p> + </dd> +<dt><span class="term">-E <em class="replaceable"><code>engine</code></em></span></dt> +<dd> + <p> + When applicable, specifies the hardware to use for + cryptographic operations, such as a secure key store used + for signing. + </p> + <p> + When BIND is built with OpenSSL PKCS#11 support, this defaults + to the string "pkcs11", which identifies an OpenSSL engine + that can drive a cryptographic accelerator or hardware service + module. When BIND is built with native PKCS#11 cryptography + (--enable-native-pkcs11), it defaults to the path of the PKCS#11 + provider library specified via "--with-pkcs11". + </p> + </dd> +<dt><span class="term">-g</span></dt> +<dd> + <p> + Generate DS records for child zones from + <code class="filename">dsset-</code> or <code class="filename">keyset-</code> + file. Existing DS records will be removed. + </p> + </dd> +<dt><span class="term">-K <em class="replaceable"><code>directory</code></em></span></dt> +<dd> + <p> + Key repository: Specify a directory to search for DNSSEC keys. + If not specified, defaults to the current directory. + </p> + </dd> +<dt><span class="term">-k <em class="replaceable"><code>key</code></em></span></dt> +<dd> + <p> + Treat specified key as a key signing key ignoring any + key flags. This option may be specified multiple times. + </p> + </dd> +<dt><span class="term">-l <em class="replaceable"><code>domain</code></em></span></dt> +<dd> + <p> + Generate a DLV set in addition to the key (DNSKEY) and DS sets. + The domain is appended to the name of the records. + </p> + </dd> +<dt><span class="term">-M <em class="replaceable"><code>maxttl</code></em></span></dt> +<dd> + <p> + Sets the maximum TTL for the signed zone. + Any TTL higher than <em class="replaceable"><code>maxttl</code></em> in the + input zone will be reduced to <em class="replaceable"><code>maxttl</code></em> + in the output. This provides certainty as to the largest + possible TTL in the signed zone, which is useful to know when + rolling keys because it is the longest possible time before + signatures that have been retrieved by resolvers will expire + from resolver caches. Zones that are signed with this + option should be configured to use a matching + <code class="option">max-zone-ttl</code> in <code class="filename">named.conf</code>. + (Note: This option is incompatible with <code class="option">-D</code>, + because it modifies non-DNSSEC data in the output zone.) + </p> + </dd> +<dt><span class="term">-s <em class="replaceable"><code>start-time</code></em></span></dt> +<dd> + <p> + Specify the date and time when the generated RRSIG records + become valid. This can be either an absolute or relative + time. An absolute start time is indicated by a number + in YYYYMMDDHHMMSS notation; 20000530144500 denotes + 14:45:00 UTC on May 30th, 2000. A relative start time is + indicated by +N, which is N seconds from the current time. + If no <code class="option">start-time</code> is specified, the current + time minus 1 hour (to allow for clock skew) is used. + </p> + </dd> +<dt><span class="term">-e <em class="replaceable"><code>end-time</code></em></span></dt> +<dd> + <p> + Specify the date and time when the generated RRSIG records + expire. As with <code class="option">start-time</code>, an absolute + time is indicated in YYYYMMDDHHMMSS notation. A time relative + to the start time is indicated with +N, which is N seconds from + the start time. A time relative to the current time is + indicated with now+N. If no <code class="option">end-time</code> is + specified, 30 days from the start time is used as a default. + <code class="option">end-time</code> must be later than + <code class="option">start-time</code>. + </p> + </dd> +<dt><span class="term">-X <em class="replaceable"><code>extended end-time</code></em></span></dt> +<dd> + <p> + Specify the date and time when the generated RRSIG records + for the DNSKEY RRset will expire. This is to be used in cases + when the DNSKEY signatures need to persist longer than + signatures on other records; e.g., when the private component + of the KSK is kept offline and the KSK signature is to be + refreshed manually. + </p> + <p> + As with <code class="option">start-time</code>, an absolute + time is indicated in YYYYMMDDHHMMSS notation. A time relative + to the start time is indicated with +N, which is N seconds from + the start time. A time relative to the current time is + indicated with now+N. If no <code class="option">extended end-time</code> is + specified, the value of <code class="option">end-time</code> is used as + the default. (<code class="option">end-time</code>, in turn, defaults to + 30 days from the start time.) <code class="option">extended end-time</code> + must be later than <code class="option">start-time</code>. + </p> + </dd> +<dt><span class="term">-f <em class="replaceable"><code>output-file</code></em></span></dt> +<dd> + <p> + The name of the output file containing the signed zone. The + default is to append <code class="filename">.signed</code> to + the input filename. If <code class="option">output-file</code> is + set to <code class="literal">"-"</code>, then the signed zone is + written to the standard output, with a default output + format of "full". + </p> + </dd> +<dt><span class="term">-h</span></dt> +<dd> + <p> + Prints a short summary of the options and arguments to + <span class="command"><strong>dnssec-signzone</strong></span>. + </p> + </dd> +<dt><span class="term">-V</span></dt> +<dd> + <p> + Prints version information. + </p> + </dd> +<dt><span class="term">-i <em class="replaceable"><code>interval</code></em></span></dt> +<dd> + <p> + When a previously-signed zone is passed as input, records + may be resigned. The <code class="option">interval</code> option + specifies the cycle interval as an offset from the current + time (in seconds). If a RRSIG record expires after the + cycle interval, it is retained. Otherwise, it is considered + to be expiring soon, and it will be replaced. + </p> + <p> + The default cycle interval is one quarter of the difference + between the signature end and start times. So if neither + <code class="option">end-time</code> or <code class="option">start-time</code> + are specified, <span class="command"><strong>dnssec-signzone</strong></span> + generates + signatures that are valid for 30 days, with a cycle + interval of 7.5 days. Therefore, if any existing RRSIG records + are due to expire in less than 7.5 days, they would be + replaced. + </p> + </dd> +<dt><span class="term">-I <em class="replaceable"><code>input-format</code></em></span></dt> +<dd> + <p> + The format of the input zone file. + Possible formats are <span class="command"><strong>"text"</strong></span> (default), + <span class="command"><strong>"raw"</strong></span>, and <span class="command"><strong>"map"</strong></span>. + This option is primarily intended to be used for dynamic + signed zones so that the dumped zone file in a non-text + format containing updates can be signed directly. + The use of this option does not make much sense for + non-dynamic zones. + </p> + </dd> +<dt><span class="term">-j <em class="replaceable"><code>jitter</code></em></span></dt> +<dd> + <p> + When signing a zone with a fixed signature lifetime, all + RRSIG records issued at the time of signing expires + simultaneously. If the zone is incrementally signed, i.e. + a previously-signed zone is passed as input to the signer, + all expired signatures have to be regenerated at about the + same time. The <code class="option">jitter</code> option specifies a + jitter window that will be used to randomize the signature + expire time, thus spreading incremental signature + regeneration over time. + </p> + <p> + Signature lifetime jitter also to some extent benefits + validators and servers by spreading out cache expiration, + i.e. if large numbers of RRSIGs don't expire at the same time + from all caches there will be less congestion than if all + validators need to refetch at mostly the same time. + </p> + </dd> +<dt><span class="term">-L <em class="replaceable"><code>serial</code></em></span></dt> +<dd> + <p> + When writing a signed zone to "raw" or "map" format, set the + "source serial" value in the header to the specified serial + number. (This is expected to be used primarily for testing + purposes.) + </p> + </dd> +<dt><span class="term">-n <em class="replaceable"><code>ncpus</code></em></span></dt> +<dd> + <p> + Specifies the number of threads to use. By default, one + thread is started for each detected CPU. + </p> + </dd> +<dt><span class="term">-N <em class="replaceable"><code>soa-serial-format</code></em></span></dt> +<dd> + <p> + The SOA serial number format of the signed zone. + Possible formats are <span class="command"><strong>"keep"</strong></span> (default), + <span class="command"><strong>"increment"</strong></span>, <span class="command"><strong>"unixtime"</strong></span>, + and <span class="command"><strong>"date"</strong></span>. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>"keep"</strong></span></span></dt> +<dd> + <p>Do not modify the SOA serial number.</p> + </dd> +<dt><span class="term"><span class="command"><strong>"increment"</strong></span></span></dt> +<dd> + <p>Increment the SOA serial number using RFC 1982 + arithmetics.</p> + </dd> +<dt><span class="term"><span class="command"><strong>"unixtime"</strong></span></span></dt> +<dd> + <p>Set the SOA serial number to the number of seconds + since epoch.</p> + </dd> +<dt><span class="term"><span class="command"><strong>"date"</strong></span></span></dt> +<dd> + <p>Set the SOA serial number to today's date in + YYYYMMDDNN format.</p> + </dd> +</dl></div> + + </dd> +<dt><span class="term">-o <em class="replaceable"><code>origin</code></em></span></dt> +<dd> + <p> + The zone origin. If not specified, the name of the zone file + is assumed to be the origin. + </p> + </dd> +<dt><span class="term">-O <em class="replaceable"><code>output-format</code></em></span></dt> +<dd> + <p> + The format of the output file containing the signed zone. + Possible formats are <span class="command"><strong>"text"</strong></span> (default), + which is the standard textual representation of the zone; + <span class="command"><strong>"full"</strong></span>, which is text output in a + format suitable for processing by external scripts; + and <span class="command"><strong>"map"</strong></span>, <span class="command"><strong>"raw"</strong></span>, + and <span class="command"><strong>"raw=N"</strong></span>, which store the zone in + binary formats for rapid loading by <span class="command"><strong>named</strong></span>. + <span class="command"><strong>"raw=N"</strong></span> specifies the format version of + the raw zone file: if N is 0, the raw file can be read by + any version of <span class="command"><strong>named</strong></span>; if N is 1, the file + can be read by release 9.9.0 or higher; the default is 1. + </p> + </dd> +<dt><span class="term">-p</span></dt> +<dd> + <p> + Use pseudo-random data when signing the zone. This is faster, + but less secure, than using real random data. This option + may be useful when signing large zones or when the entropy + source is limited. + </p> + </dd> +<dt><span class="term">-P</span></dt> +<dd> + <p> + Disable post sign verification tests. + </p> + <p> + The post sign verification test ensures that for each algorithm + in use there is at least one non revoked self signed KSK key, + that all revoked KSK keys are self signed, and that all records + in the zone are signed by the algorithm. + This option skips these tests. + </p> + </dd> +<dt><span class="term">-Q</span></dt> +<dd> + <p> + Remove signatures from keys that are no longer active. + </p> + <p> + Normally, when a previously-signed zone is passed as input + to the signer, and a DNSKEY record has been removed and + replaced with a new one, signatures from the old key + that are still within their validity period are retained. + This allows the zone to continue to validate with cached + copies of the old DNSKEY RRset. The <code class="option">-Q</code> + forces <span class="command"><strong>dnssec-signzone</strong></span> to remove + signatures from keys that are no longer active. This + enables ZSK rollover using the procedure described in + RFC 4641, section 4.2.1.1 ("Pre-Publish Key Rollover"). + </p> + </dd> +<dt><span class="term">-R</span></dt> +<dd> + <p> + Remove signatures from keys that are no longer published. + </p> + <p> + This option is similar to <code class="option">-Q</code>, except it + forces <span class="command"><strong>dnssec-signzone</strong></span> to signatures from + keys that are no longer published. This enables ZSK rollover + using the procedure described in RFC 4641, section 4.2.1.2 + ("Double Signature Zone Signing Key Rollover"). + </p> + </dd> +<dt><span class="term">-r <em class="replaceable"><code>randomdev</code></em></span></dt> +<dd> + <p> + Specifies the source of randomness. If the operating + system does not provide a <code class="filename">/dev/random</code> + or equivalent device, the default source of randomness + is keyboard input. <code class="filename">randomdev</code> + specifies + the name of a character device or file containing random + data to be used instead of the default. The special value + <code class="filename">keyboard</code> indicates that keyboard + input should be used. + </p> + </dd> +<dt><span class="term">-S</span></dt> +<dd> + <p> + Smart signing: Instructs <span class="command"><strong>dnssec-signzone</strong></span> to + search the key repository for keys that match the zone being + signed, and to include them in the zone if appropriate. + </p> + <p> + When a key is found, its timing metadata is examined to + determine how it should be used, according to the following + rules. Each successive rule takes priority over the prior + ones: + </p> + <div class="variablelist"><dl class="variablelist"> +<dt></dt> +<dd> + <p> + If no timing metadata has been set for the key, the key is + published in the zone and used to sign the zone. + </p> + </dd> +<dt></dt> +<dd> + <p> + If the key's publication date is set and is in the past, the + key is published in the zone. + </p> + </dd> +<dt></dt> +<dd> + <p> + If the key's activation date is set and in the past, the + key is published (regardless of publication date) and + used to sign the zone. + </p> + </dd> +<dt></dt> +<dd> + <p> + If the key's revocation date is set and in the past, and the + key is published, then the key is revoked, and the revoked key + is used to sign the zone. + </p> + </dd> +<dt></dt> +<dd> + <p> + If either of the key's unpublication or deletion dates are set + and in the past, the key is NOT published or used to sign the + zone, regardless of any other metadata. + </p> + </dd> +</dl></div> + </dd> +<dt><span class="term">-T <em class="replaceable"><code>ttl</code></em></span></dt> +<dd> + <p> + Specifies a TTL to be used for new DNSKEY records imported + into the zone from the key repository. If not + specified, the default is the TTL value from the zone's SOA + record. This option is ignored when signing without + <code class="option">-S</code>, since DNSKEY records are not imported + from the key repository in that case. It is also ignored if + there are any pre-existing DNSKEY records at the zone apex, + in which case new records' TTL values will be set to match + them, or if any of the imported DNSKEY records had a default + TTL value. In the event of a a conflict between TTL values in + imported keys, the shortest one is used. + </p> + </dd> +<dt><span class="term">-t</span></dt> +<dd> + <p> + Print statistics at completion. + </p> + </dd> +<dt><span class="term">-u</span></dt> +<dd> + <p> + Update NSEC/NSEC3 chain when re-signing a previously signed + zone. With this option, a zone signed with NSEC can be + switched to NSEC3, or a zone signed with NSEC3 can + be switch to NSEC or to NSEC3 with different parameters. + Without this option, <span class="command"><strong>dnssec-signzone</strong></span> will + retain the existing chain when re-signing. + </p> + </dd> +<dt><span class="term">-v <em class="replaceable"><code>level</code></em></span></dt> +<dd> + <p> + Sets the debugging level. + </p> + </dd> +<dt><span class="term">-x</span></dt> +<dd> + <p> + Only sign the DNSKEY RRset with key-signing keys, and omit + signatures from zone-signing keys. (This is similar to the + <span class="command"><strong>dnssec-dnskey-kskonly yes;</strong></span> zone option in + <span class="command"><strong>named</strong></span>.) + </p> + </dd> +<dt><span class="term">-z</span></dt> +<dd> + <p> + Ignore KSK flag on key when determining what to sign. This + causes KSK-flagged keys to sign all records, not just the + DNSKEY RRset. (This is similar to the + <span class="command"><strong>update-check-ksk no;</strong></span> zone option in + <span class="command"><strong>named</strong></span>.) + </p> + </dd> +<dt><span class="term">-3 <em class="replaceable"><code>salt</code></em></span></dt> +<dd> + <p> + Generate an NSEC3 chain with the given hex encoded salt. + A dash (<em class="replaceable"><code>salt</code></em>) can + be used to indicate that no salt is to be used when generating the NSEC3 chain. + </p> + </dd> +<dt><span class="term">-H <em class="replaceable"><code>iterations</code></em></span></dt> +<dd> + <p> + When generating an NSEC3 chain, use this many iterations. The + default is 10. + </p> + </dd> +<dt><span class="term">-A</span></dt> +<dd> + <p> + When generating an NSEC3 chain set the OPTOUT flag on all + NSEC3 records and do not generate NSEC3 records for insecure + delegations. + </p> + <p> + Using this option twice (i.e., <code class="option">-AA</code>) + turns the OPTOUT flag off for all records. This is useful + when using the <code class="option">-u</code> option to modify an NSEC3 + chain which previously had OPTOUT set. + </p> + </dd> +<dt><span class="term">zonefile</span></dt> +<dd> + <p> + The file containing the zone to be signed. + </p> + </dd> +<dt><span class="term">key</span></dt> +<dd> + <p> + Specify which keys should be used to sign the zone. If + no keys are specified, then the zone will be examined + for DNSKEY records at the zone apex. If these are found and + there are matching private keys, in the current directory, + then these will be used for signing. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.16.9"></a><h2>EXAMPLE</h2> + + <p> + The following command signs the <strong class="userinput"><code>example.com</code></strong> + zone with the DSA key generated by <span class="command"><strong>dnssec-keygen</strong></span> + (Kexample.com.+003+17247). Because the <span class="command"><strong>-S</strong></span> option + is not being used, the zone's keys must be in the master file + (<code class="filename">db.example.com</code>). This invocation looks + for <code class="filename">dsset</code> files, in the current directory, + so that DS records can be imported from them (<span class="command"><strong>-g</strong></span>). + </p> +<pre class="programlisting">% dnssec-signzone -g -o example.com db.example.com \ +Kexample.com.+003+17247 +db.example.com.signed +%</pre> + <p> + In the above example, <span class="command"><strong>dnssec-signzone</strong></span> creates + the file <code class="filename">db.example.com.signed</code>. This + file should be referenced in a zone statement in a + <code class="filename">named.conf</code> file. + </p> + <p> + This example re-signs a previously signed zone with default parameters. + The private keys are assumed to be in the current directory. + </p> +<pre class="programlisting">% cp db.example.com.signed db.example.com +% dnssec-signzone -o example.com db.example.com +db.example.com.signed +%</pre> + </div> + + <div class="refsection"> +<a name="id-1.14.16.10"></a><h2>SEE ALSO</h2> + + <p><span class="citerefentry"> + <span class="refentrytitle">dnssec-keygen</span>(8) + </span>, + <em class="citetitle">BIND 9 Administrator Reference Manual</em>, + <em class="citetitle">RFC 4033</em>, <em class="citetitle">RFC 4641</em>. + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.dnssec-settime.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.dnssec-verify.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">dnssec-settime</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">dnssec-verify</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.dnssec-verify.html b/doc/arm/man.dnssec-verify.html new file mode 100644 index 0000000..792a3ac --- /dev/null +++ b/doc/arm/man.dnssec-verify.html @@ -0,0 +1,207 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>dnssec-verify</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.dnssec-signzone.html" title="dnssec-signzone"> +<link rel="next" href="man.lwresd.html" title="lwresd"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">dnssec-verify</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.dnssec-signzone.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.lwresd.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.dnssec-verify"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">dnssec-verify</span> + — DNSSEC zone verification tool + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">dnssec-verify</code> + [<code class="option">-c <em class="replaceable"><code>class</code></em></code>] + [<code class="option">-E <em class="replaceable"><code>engine</code></em></code>] + [<code class="option">-I <em class="replaceable"><code>input-format</code></em></code>] + [<code class="option">-o <em class="replaceable"><code>origin</code></em></code>] + [<code class="option">-v <em class="replaceable"><code>level</code></em></code>] + [<code class="option">-V</code>] + [<code class="option">-x</code>] + [<code class="option">-z</code>] + {zonefile} + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.17.7"></a><h2>DESCRIPTION</h2> + + <p><span class="command"><strong>dnssec-verify</strong></span> + verifies that a zone is fully signed for each algorithm found + in the DNSKEY RRset for the zone, and that the NSEC / NSEC3 + chains are complete. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.17.8"></a><h2>OPTIONS</h2> + + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-c <em class="replaceable"><code>class</code></em></span></dt> +<dd> + <p> + Specifies the DNS class of the zone. + </p> + </dd> +<dt><span class="term">-E <em class="replaceable"><code>engine</code></em></span></dt> +<dd> + <p> + Specifies the cryptographic hardware to use, when applicable. + </p> + <p> + When BIND is built with OpenSSL PKCS#11 support, this defaults + to the string "pkcs11", which identifies an OpenSSL engine + that can drive a cryptographic accelerator or hardware service + module. When BIND is built with native PKCS#11 cryptography + (--enable-native-pkcs11), it defaults to the path of the PKCS#11 + provider library specified via "--with-pkcs11". + </p> + </dd> +<dt><span class="term">-I <em class="replaceable"><code>input-format</code></em></span></dt> +<dd> + <p> + The format of the input zone file. + Possible formats are <span class="command"><strong>"text"</strong></span> (default) + and <span class="command"><strong>"raw"</strong></span>. + This option is primarily intended to be used for dynamic + signed zones so that the dumped zone file in a non-text + format containing updates can be verified independently. + The use of this option does not make much sense for + non-dynamic zones. + </p> + </dd> +<dt><span class="term">-o <em class="replaceable"><code>origin</code></em></span></dt> +<dd> + <p> + The zone origin. If not specified, the name of the zone file + is assumed to be the origin. + </p> + </dd> +<dt><span class="term">-v <em class="replaceable"><code>level</code></em></span></dt> +<dd> + <p> + Sets the debugging level. + </p> + </dd> +<dt><span class="term">-V</span></dt> +<dd> + <p> + Prints version information. + </p> + </dd> +<dt><span class="term">-x</span></dt> +<dd> + <p> + Only verify that the DNSKEY RRset is signed with key-signing + keys. Without this flag, it is assumed that the DNSKEY RRset + will be signed by all active keys. When this flag is set, + it will not be an error if the DNSKEY RRset is not signed + by zone-signing keys. This corresponds to the <code class="option">-x</code> + option in <span class="command"><strong>dnssec-signzone</strong></span>. + </p> + </dd> +<dt><span class="term">-z</span></dt> +<dd> + <p> + Ignore the KSK flag on the keys when determining whether + the zone if correctly signed. Without this flag it is + assumed that there will be a non-revoked, self-signed + DNSKEY with the KSK flag set for each algorithm and + that RRsets other than DNSKEY RRset will be signed with + a different DNSKEY without the KSK flag set. + </p> + <p> + With this flag set, we only require that for each algorithm, + there will be at least one non-revoked, self-signed DNSKEY, + regardless of the KSK flag state, and that other RRsets + will be signed by a non-revoked key for the same algorithm + that includes the self-signed key; the same key may be used + for both purposes. This corresponds to the <code class="option">-z</code> + option in <span class="command"><strong>dnssec-signzone</strong></span>. + </p> + </dd> +<dt><span class="term">zonefile</span></dt> +<dd> + <p> + The file containing the zone to be signed. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.17.9"></a><h2>SEE ALSO</h2> + + <p> + <span class="citerefentry"> + <span class="refentrytitle">dnssec-signzone</span>(8) + </span>, + <em class="citetitle">BIND 9 Administrator Reference Manual</em>, + <em class="citetitle">RFC 4033</em>. + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.dnssec-signzone.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.lwresd.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">dnssec-signzone</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">lwresd</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.dnstap-read.html b/doc/arm/man.dnstap-read.html new file mode 100644 index 0000000..6376e7e --- /dev/null +++ b/doc/arm/man.dnstap-read.html @@ -0,0 +1,139 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>dnstap-read</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.arpaname.html" title="arpaname"> +<link rel="next" href="man.genrandom.html" title="genrandom"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">dnstap-read</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.arpaname.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.genrandom.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.dnstap-read"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">dnstap-read</span> + — print dnstap data in human-readable form + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">dnstap-read</code> + [<code class="option">-m</code>] + [<code class="option">-p</code>] + [<code class="option">-y</code>] + {<em class="replaceable"><code>file</code></em>} + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.32.7"></a><h2>DESCRIPTION</h2> + + <p> + <span class="command"><strong>dnstap-read</strong></span> + reads <span class="command"><strong>dnstap</strong></span> data from a specified file + and prints it in a human-readable format. By default, + <span class="command"><strong>dnstap</strong></span> data is printed in a short summary + format, but if the <code class="option">-y</code> option is specified, + then a longer and more detailed YAML format is used instead. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.32.8"></a><h2>OPTIONS</h2> + + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-m</span></dt> +<dd> + <p> + Trace memory allocations; used for debugging memory leaks. + </p> + </dd> +<dt><span class="term">-p</span></dt> +<dd> + <p> + After printing the <span class="command"><strong>dnstap</strong></span> data, print + the text form of the DNS message that was encapsulated in the + <span class="command"><strong>dnstap</strong></span> frame. + </p> + </dd> +<dt><span class="term">-y</span></dt> +<dd> + <p> + Print <span class="command"><strong>dnstap</strong></span> data in a detailed YAML + format. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.32.9"></a><h2>SEE ALSO</h2> + + <p> + <span class="citerefentry"> + <span class="refentrytitle">named</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">rndc</span>(8) + </span>, + <em class="citetitle">BIND 9 Administrator Reference Manual</em>. + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.arpaname.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.genrandom.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">arpaname</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">genrandom</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.genrandom.html b/doc/arm/man.genrandom.html new file mode 100644 index 0000000..be4b8a7 --- /dev/null +++ b/doc/arm/man.genrandom.html @@ -0,0 +1,132 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>genrandom</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.dnstap-read.html" title="dnstap-read"> +<link rel="next" href="man.isc-hmac-fixup.html" title="isc-hmac-fixup"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">genrandom</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.dnstap-read.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.isc-hmac-fixup.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.genrandom"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">genrandom</span> + — generate a file containing random data + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">genrandom</code> + [<code class="option">-n <em class="replaceable"><code>number</code></em></code>] + {<em class="replaceable"><code>size</code></em>} + {<em class="replaceable"><code>filename</code></em>} + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.33.7"></a><h2>DESCRIPTION</h2> + + <p> + <span class="command"><strong>genrandom</strong></span> + generates a file or a set of files containing a specified quantity + of pseudo-random data, which can be used as a source of entropy for + other commands on systems with no random device. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.33.8"></a><h2>ARGUMENTS</h2> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-n <em class="replaceable"><code>number</code></em></span></dt> +<dd> + <p> + In place of generating one file, generates <code class="option">number</code> + (from 2 to 9) files, appending <code class="option">number</code> to the name. + </p> + </dd> +<dt><span class="term">size</span></dt> +<dd> + <p> + The size of the file, in kilobytes, to generate. + </p> + </dd> +<dt><span class="term">filename</span></dt> +<dd> + <p> + The file name into which random data should be written. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.33.9"></a><h2>SEE ALSO</h2> + + <p> + <span class="citerefentry"> + <span class="refentrytitle">rand</span>(3) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">arc4random</span>(3) + </span> + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.dnstap-read.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.isc-hmac-fixup.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">dnstap-read</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">isc-hmac-fixup</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.host.html b/doc/arm/man.host.html new file mode 100644 index 0000000..1925d7b --- /dev/null +++ b/doc/arm/man.host.html @@ -0,0 +1,371 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>host</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.mdig.html" title="mdig"> +<link rel="next" href="man.delv.html" title="delv"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center">host</th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.mdig.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.delv.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.host"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + host + — DNS lookup utility + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">host</code> + [<code class="option">-aCdlnrsTUwv</code>] + [<code class="option">-c <em class="replaceable"><code>class</code></em></code>] + [<code class="option">-N <em class="replaceable"><code>ndots</code></em></code>] + [<code class="option">-R <em class="replaceable"><code>number</code></em></code>] + [<code class="option">-t <em class="replaceable"><code>type</code></em></code>] + [<code class="option">-W <em class="replaceable"><code>wait</code></em></code>] + [<code class="option">-m <em class="replaceable"><code>flag</code></em></code>] + [ + [<code class="option">-4</code>] + | [<code class="option">-6</code>] + ] + [<code class="option">-v</code>] + [<code class="option">-V</code>] + {name} + [server] + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.4.7"></a><h2>DESCRIPTION</h2> + + + <p><span class="command"><strong>host</strong></span> + is a simple utility for performing DNS lookups. + It is normally used to convert names to IP addresses and vice versa. + When no arguments or options are given, + <span class="command"><strong>host</strong></span> + prints a short summary of its command line arguments and options. + </p> + + <p><em class="parameter"><code>name</code></em> is the domain name that is to be + looked + up. It can also be a dotted-decimal IPv4 address or a colon-delimited + IPv6 address, in which case <span class="command"><strong>host</strong></span> will by + default + perform a reverse lookup for that address. + <em class="parameter"><code>server</code></em> is an optional argument which + is either + the name or IP address of the name server that <span class="command"><strong>host</strong></span> + should query instead of the server or servers listed in + <code class="filename">/etc/resolv.conf</code>. + </p> + + </div> + + <div class="refsection"> +<a name="id-1.14.4.8"></a><h2>OPTIONS</h2> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-4</span></dt> +<dd> + <p> + Use IPv4 only for query transport. + See also the <code class="option">-6</code> option. + </p> + </dd> +<dt><span class="term">-6</span></dt> +<dd> + <p> + Use IPv6 only for query transport. + See also the <code class="option">-4</code> option. + </p> + </dd> +<dt><span class="term">-a</span></dt> +<dd> + <p> + "All". The <code class="option">-a</code> option is normally equivalent + to <code class="option">-v -t <code class="literal">ANY</code></code>. + It also affects the behaviour of the <code class="option">-l</code> + list zone option. + </p> + </dd> +<dt><span class="term">-c <em class="replaceable"><code>class</code></em></span></dt> +<dd> + <p> + Query class: This can be used to lookup HS (Hesiod) or CH + (Chaosnet) class resource records. The default class is IN + (Internet). + </p> + </dd> +<dt><span class="term">-C</span></dt> +<dd> + <p> + Check consistency: <span class="command"><strong>host</strong></span> will query the + SOA records for zone <em class="parameter"><code>name</code></em> from all + the listed authoritative name servers for that zone. The + list of name servers is defined by the NS records that are + found for the zone. + </p> + </dd> +<dt><span class="term">-d</span></dt> +<dd> + <p> + Print debugging traces. + Equivalent to the <code class="option">-v</code> verbose option. + </p> + </dd> +<dt><span class="term">-i</span></dt> +<dd> + <p> + Obsolete. + Use the IP6.INT domain for reverse lookups of IPv6 + addresses as defined in RFC1886 and deprecated in RFC4159. + The default is to use IP6.ARPA as specified in RFC3596. + </p> + </dd> +<dt><span class="term">-l</span></dt> +<dd> + <p> + List zone: + The <span class="command"><strong>host</strong></span> command performs a zone transfer of + zone <em class="parameter"><code>name</code></em> and prints out the NS, + PTR and address records (A/AAAA). + </p> + <p> + Together, the <code class="option">-l -a</code> + options print all records in the zone. + </p> + </dd> +<dt><span class="term">-N <em class="replaceable"><code>ndots</code></em></span></dt> +<dd> + <p> + The number of dots that have to be + in <em class="parameter"><code>name</code></em> for it to be considered + absolute. The default value is that defined using the + ndots statement in <code class="filename">/etc/resolv.conf</code>, + or 1 if no ndots statement is present. Names with fewer + dots are interpreted as relative names and will be + searched for in the domains listed in + the <span class="type">search</span> or <span class="type">domain</span> directive + in <code class="filename">/etc/resolv.conf</code>. + </p> + </dd> +<dt><span class="term">-r</span></dt> +<dd> + <p> + Non-recursive query: + Setting this option clears the RD (recursion desired) bit + in the query. This should mean that the name server + receiving the query will not attempt to + resolve <em class="parameter"><code>name</code></em>. + The <code class="option">-r</code> option + enables <span class="command"><strong>host</strong></span> to mimic the behavior of a + name server by making non-recursive queries and expecting + to receive answers to those queries that can be + referrals to other name servers. + </p> + </dd> +<dt><span class="term">-R <em class="replaceable"><code>number</code></em></span></dt> +<dd> + <p> + Number of retries for UDP queries: + If <em class="parameter"><code>number</code></em> is negative or zero, the + number of retries will default to 1. The default value is + 1, or the value of the <em class="parameter"><code>attempts</code></em> + option in <code class="filename">/etc/resolv.conf</code>, if set. + </p> + </dd> +<dt><span class="term">-s</span></dt> +<dd> + <p> + Do <span class="emphasis"><em>not</em></span> send the query to the next + nameserver if any server responds with a SERVFAIL + response, which is the reverse of normal stub resolver + behavior. + </p> + </dd> +<dt><span class="term">-t <em class="replaceable"><code>type</code></em></span></dt> +<dd> + <p> + Query type: + The <em class="parameter"><code>type</code></em> argument can be any + recognized query type: CNAME, NS, SOA, TXT, DNSKEY, AXFR, etc. + </p> + <p> + When no query type is specified, <span class="command"><strong>host</strong></span> + automatically selects an appropriate query type. By default, it + looks for A, AAAA, and MX records. + If the <code class="option">-C</code> option is given, queries will + be made for SOA records. + If <em class="parameter"><code>name</code></em> is a dotted-decimal IPv4 + address or colon-delimited IPv6 + address, <span class="command"><strong>host</strong></span> will query for PTR + records. + </p> + <p> + If a query type of IXFR is chosen the starting serial + number can be specified by appending an equal followed by + the starting serial number + (like <code class="option">-t <code class="literal">IXFR=12345678</code></code>). + </p> + </dd> +<dt> +<span class="term">-T, </span><span class="term">-U</span> +</dt> +<dd> + <p> + TCP/UDP: + By default, <span class="command"><strong>host</strong></span> uses UDP when making + queries. The <code class="option">-T</code> option makes it use a TCP + connection when querying the name server. TCP will be + automatically selected for queries that require it, such + as zone transfer (AXFR) requests. Type ANY queries default + to TCP but can be forced to UDP initially using <code class="option">-U</code>. + </p> + </dd> +<dt><span class="term">-m <em class="replaceable"><code>flag</code></em></span></dt> +<dd> + <p> + Memory usage debugging: the flag can + be <em class="parameter"><code>record</code></em>, <em class="parameter"><code>usage</code></em>, + or <em class="parameter"><code>trace</code></em>. You can specify + the <code class="option">-m</code> option more than once to set + multiple flags. + </p> + </dd> +<dt><span class="term">-v</span></dt> +<dd> + <p> + Verbose output. + Equivalent to the <code class="option">-d</code> debug option. + Verbose output can also be enabled by setting + the <em class="parameter"><code>debug</code></em> option + in <code class="filename">/etc/resolv.conf</code>. + </p> + </dd> +<dt><span class="term">-V</span></dt> +<dd> + <p> + Print the version number and exit. + </p> + </dd> +<dt><span class="term">-w</span></dt> +<dd> + <p> + Wait forever: The query timeout is set to the maximum possible. + See also the <code class="option">-W</code> option. + </p> + </dd> +<dt><span class="term">-W <em class="replaceable"><code>wait</code></em></span></dt> +<dd> + <p> + Timeout: Wait for up to <em class="parameter"><code>wait</code></em> + seconds for a reply. If <em class="parameter"><code>wait</code></em> is + less than one, the wait interval is set to one second. + </p> + <p> + By default, <span class="command"><strong>host</strong></span> will wait for 5 + seconds for UDP responses and 10 seconds for TCP + connections. These defaults can be overridden by + the <em class="parameter"><code>timeout</code></em> option + in <code class="filename">/etc/resolv.conf</code>. + </p> + <p> + See also the <code class="option">-w</code> option. + </p> + </dd> +</dl></div> + + </div> + + <div class="refsection"> +<a name="id-1.14.4.9"></a><h2>IDN SUPPORT</h2> + + <p> + If <span class="command"><strong>host</strong></span> has been built with IDN (internationalized + domain name) support, it can accept and display non-ASCII domain names. + <span class="command"><strong>host</strong></span> appropriately converts character encoding of + domain name before sending a request to DNS server or displaying a + reply from the server. + If you'd like to turn off the IDN support for some reason, defines + the <code class="envar">IDN_DISABLE</code> environment variable. + The IDN support is disabled if the variable is set when + <span class="command"><strong>host</strong></span> runs. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.4.10"></a><h2>FILES</h2> + + <p><code class="filename">/etc/resolv.conf</code> + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.4.11"></a><h2>SEE ALSO</h2> + + <p><span class="citerefentry"> + <span class="refentrytitle">dig</span>(1) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">named</span>(8) + </span>. + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.mdig.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.delv.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">mdig</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> delv</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.isc-hmac-fixup.html b/doc/arm/man.isc-hmac-fixup.html new file mode 100644 index 0000000..02818a9 --- /dev/null +++ b/doc/arm/man.isc-hmac-fixup.html @@ -0,0 +1,131 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>isc-hmac-fixup</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.genrandom.html" title="genrandom"> +<link rel="next" href="man.nsec3hash.html" title="nsec3hash"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">isc-hmac-fixup</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.genrandom.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.nsec3hash.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.isc-hmac-fixup"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">isc-hmac-fixup</span> + — fixes HMAC keys generated by older versions of BIND + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">isc-hmac-fixup</code> + {<em class="replaceable"><code>algorithm</code></em>} + {<em class="replaceable"><code>secret</code></em>} + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.34.7"></a><h2>DESCRIPTION</h2> + + <p> + Versions of BIND 9 up to and including BIND 9.6 had a bug causing + HMAC-SHA* TSIG keys which were longer than the digest length of the + hash algorithm (i.e., SHA1 keys longer than 160 bits, SHA256 keys + longer than 256 bits, etc) to be used incorrectly, generating a + message authentication code that was incompatible with other DNS + implementations. + </p> + <p> + This bug was fixed in BIND 9.7. However, the fix may + cause incompatibility between older and newer versions of + BIND, when using long keys. <span class="command"><strong>isc-hmac-fixup</strong></span> + modifies those keys to restore compatibility. + </p> + <p> + To modify a key, run <span class="command"><strong>isc-hmac-fixup</strong></span> and + specify the key's algorithm and secret on the command line. If the + secret is longer than the digest length of the algorithm (64 bytes + for SHA1 through SHA256, or 128 bytes for SHA384 and SHA512), then a + new secret will be generated consisting of a hash digest of the old + secret. (If the secret did not require conversion, then it will be + printed without modification.) + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.34.8"></a><h2>SECURITY CONSIDERATIONS</h2> + + <p> + Secrets that have been converted by <span class="command"><strong>isc-hmac-fixup</strong></span> + are shortened, but as this is how the HMAC protocol works in + operation anyway, it does not affect security. RFC 2104 notes, + "Keys longer than [the digest length] are acceptable but the + extra length would not significantly increase the function + strength." + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.34.9"></a><h2>SEE ALSO</h2> + + <p> + <em class="citetitle">BIND 9 Administrator Reference Manual</em>, + <em class="citetitle">RFC 2104</em>. + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.genrandom.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.nsec3hash.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">genrandom</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">nsec3hash</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.lwresd.html b/doc/arm/man.lwresd.html new file mode 100644 index 0000000..7b2d3a2 --- /dev/null +++ b/doc/arm/man.lwresd.html @@ -0,0 +1,334 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>lwresd</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.dnssec-verify.html" title="dnssec-verify"> +<link rel="next" href="man.named.html" title="named"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">lwresd</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.dnssec-verify.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.named.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.lwresd"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">lwresd</span> + — lightweight resolver daemon + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">lwresd</code> + [<code class="option">-c <em class="replaceable"><code>config-file</code></em></code>] + [<code class="option">-C <em class="replaceable"><code>config-file</code></em></code>] + [<code class="option">-d <em class="replaceable"><code>debug-level</code></em></code>] + [<code class="option">-f</code>] + [<code class="option">-g</code>] + [<code class="option">-i <em class="replaceable"><code>pid-file</code></em></code>] + [<code class="option">-m <em class="replaceable"><code>flag</code></em></code>] + [<code class="option">-n <em class="replaceable"><code>#cpus</code></em></code>] + [<code class="option">-P <em class="replaceable"><code>port</code></em></code>] + [<code class="option">-p <em class="replaceable"><code>port</code></em></code>] + [<code class="option">-s</code>] + [<code class="option">-t <em class="replaceable"><code>directory</code></em></code>] + [<code class="option">-u <em class="replaceable"><code>user</code></em></code>] + [<code class="option">-v</code>] + [ + [<code class="option">-4</code>] + | [<code class="option">-6</code>] + ] + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.18.7"></a><h2>DESCRIPTION</h2> + + + <p><span class="command"><strong>lwresd</strong></span> + is the daemon providing name lookup + services to clients that use the BIND 9 lightweight resolver + library. It is essentially a stripped-down, caching-only name + server that answers queries using the BIND 9 lightweight + resolver protocol rather than the DNS protocol. + </p> + + <p><span class="command"><strong>lwresd</strong></span> + listens for resolver queries on a + UDP port on the IPv4 loopback interface, 127.0.0.1. This + means that <span class="command"><strong>lwresd</strong></span> can only be used by + processes running on the local machine. By default, UDP port + number 921 is used for lightweight resolver requests and + responses. + </p> + <p> + Incoming lightweight resolver requests are decoded by the + server which then resolves them using the DNS protocol. When + the DNS lookup completes, <span class="command"><strong>lwresd</strong></span> encodes + the answers in the lightweight resolver format and returns + them to the client that made the request. + </p> + <p> + If <code class="filename">/etc/resolv.conf</code> contains any + <code class="option">nameserver</code> entries, <span class="command"><strong>lwresd</strong></span> + sends recursive DNS queries to those servers. This is similar + to the use of forwarders in a caching name server. If no + <code class="option">nameserver</code> entries are present, or if + forwarding fails, <span class="command"><strong>lwresd</strong></span> resolves the + queries autonomously starting at the root name servers, using + a built-in list of root server hints. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.18.8"></a><h2>OPTIONS</h2> + + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-4</span></dt> +<dd> + <p> + Use IPv4 only even if the host machine is capable of IPv6. + <code class="option">-4</code> and <code class="option">-6</code> are mutually + exclusive. + </p> + </dd> +<dt><span class="term">-6</span></dt> +<dd> + <p> + Use IPv6 only even if the host machine is capable of IPv4. + <code class="option">-4</code> and <code class="option">-6</code> are mutually + exclusive. + </p> + </dd> +<dt><span class="term">-c <em class="replaceable"><code>config-file</code></em></span></dt> +<dd> + <p> + Use <em class="replaceable"><code>config-file</code></em> as the + configuration file instead of the default, + <code class="filename">/etc/lwresd.conf</code>. + + <code class="option">-c</code> can not be used with <code class="option">-C</code>. + </p> + </dd> +<dt><span class="term">-C <em class="replaceable"><code>config-file</code></em></span></dt> +<dd> + <p> + Use <em class="replaceable"><code>config-file</code></em> as the + configuration file instead of the default, + <code class="filename">/etc/resolv.conf</code>. + <code class="option">-C</code> can not be used with <code class="option">-c</code>. + </p> + </dd> +<dt><span class="term">-d <em class="replaceable"><code>debug-level</code></em></span></dt> +<dd> + <p> + Set the daemon's debug level to <em class="replaceable"><code>debug-level</code></em>. + Debugging traces from <span class="command"><strong>lwresd</strong></span> become + more verbose as the debug level increases. + </p> + </dd> +<dt><span class="term">-f</span></dt> +<dd> + <p> + Run the server in the foreground (i.e. do not daemonize). + </p> + </dd> +<dt><span class="term">-g</span></dt> +<dd> + <p> + Run the server in the foreground and force all logging + to <code class="filename">stderr</code>. + </p> + </dd> +<dt><span class="term">-i <em class="replaceable"><code>pid-file</code></em></span></dt> +<dd> + <p> + Use <em class="replaceable"><code>pid-file</code></em> as the + PID file instead of the default, + <code class="filename">/var/run/lwresd/lwresd.pid</code>. + </p> + </dd> +<dt><span class="term">-m <em class="replaceable"><code>flag</code></em></span></dt> +<dd> + <p> + Turn on memory usage debugging flags. Possible flags are + <em class="replaceable"><code>usage</code></em>, + <em class="replaceable"><code>trace</code></em>, + <em class="replaceable"><code>record</code></em>, + <em class="replaceable"><code>size</code></em>, and + <em class="replaceable"><code>mctx</code></em>. + These correspond to the ISC_MEM_DEBUGXXXX flags described in + <code class="filename"><isc/mem.h></code>. + </p> + </dd> +<dt><span class="term">-n <em class="replaceable"><code>#cpus</code></em></span></dt> +<dd> + <p> + Create <em class="replaceable"><code>#cpus</code></em> worker threads + to take advantage of multiple CPUs. If not specified, + <span class="command"><strong>lwresd</strong></span> will try to determine the + number of CPUs present and create one thread per CPU. + If it is unable to determine the number of CPUs, a + single worker thread will be created. + </p> + </dd> +<dt><span class="term">-P <em class="replaceable"><code>port</code></em></span></dt> +<dd> + <p> + Listen for lightweight resolver queries on port + <em class="replaceable"><code>port</code></em>. If + not specified, the default is port 921. + </p> + </dd> +<dt><span class="term">-p <em class="replaceable"><code>port</code></em></span></dt> +<dd> + <p> + Send DNS lookups to port <em class="replaceable"><code>port</code></em>. If not + specified, the default is port 53. This provides a + way of testing the lightweight resolver daemon with a + name server that listens for queries on a non-standard + port number. + </p> + </dd> +<dt><span class="term">-s</span></dt> +<dd> + <p> + Write memory usage statistics to <code class="filename">stdout</code> + on exit. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + This option is mainly of interest to BIND 9 developers + and may be removed or changed in a future release. + </p> + </div> + </dd> +<dt><span class="term">-t <em class="replaceable"><code>directory</code></em></span></dt> +<dd> + <p>Chroot + to <em class="replaceable"><code>directory</code></em> after + processing the command line arguments, but before + reading the configuration file. + </p> + <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Warning</h3> + <p> + This option should be used in conjunction with the + <code class="option">-u</code> option, as chrooting a process + running as root doesn't enhance security on most + systems; the way <code class="function">chroot(2)</code> is + defined allows a process with root privileges to + escape a chroot jail. + </p> + </div> + </dd> +<dt><span class="term">-u <em class="replaceable"><code>user</code></em></span></dt> +<dd> + <p>Setuid + to <em class="replaceable"><code>user</code></em> after completing + privileged operations, such as creating sockets that + listen on privileged ports. + </p> + </dd> +<dt><span class="term">-v</span></dt> +<dd> + <p> + Report the version number and exit. + </p> + </dd> +</dl></div> + + </div> + + <div class="refsection"> +<a name="id-1.14.18.9"></a><h2>FILES</h2> + + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><code class="filename">/etc/resolv.conf</code></span></dt> +<dd> + <p> + The default configuration file. + </p> + </dd> +<dt><span class="term"><code class="filename">/var/run/lwresd.pid</code></span></dt> +<dd> + <p> + The default process-id file. + </p> + </dd> +</dl></div> + + </div> + + <div class="refsection"> +<a name="id-1.14.18.10"></a><h2>SEE ALSO</h2> + + <p><span class="citerefentry"> + <span class="refentrytitle">named</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">lwres</span>(3) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">resolver</span>(5) + </span>. + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.dnssec-verify.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.named.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">dnssec-verify</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">named</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.mdig.html b/doc/arm/man.mdig.html new file mode 100644 index 0000000..9ebdc13 --- /dev/null +++ b/doc/arm/man.mdig.html @@ -0,0 +1,614 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>mdig</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.dig.html" title="dig"> +<link rel="next" href="man.host.html" title="host"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">mdig</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.dig.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.host.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.mdig"></a><div class="titlepage"></div> + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">mdig</span> + — DNS pipelined lookup utility + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">mdig</code> + {@server} + [<code class="option">-f <em class="replaceable"><code>filename</code></em></code>] + [<code class="option">-h</code>] + [<code class="option">-v</code>] + [ + [<code class="option">-4</code>] + | [<code class="option">-6</code>] + ] + [<code class="option">-m</code>] + [<code class="option">-b <em class="replaceable"><code>address</code></em></code>] + [<code class="option">-p <em class="replaceable"><code>port#</code></em></code>] + [<code class="option">-c <em class="replaceable"><code>class</code></em></code>] + [<code class="option">-t <em class="replaceable"><code>type</code></em></code>] + [<code class="option">-i</code>] + [<code class="option">-x <em class="replaceable"><code>addr</code></em></code>] + [plusopt...] + </p></div> + + <div class="cmdsynopsis"><p> + <code class="command">mdig</code> + {-h} + </p></div> + + <div class="cmdsynopsis"><p> + <code class="command">mdig</code> + [@server] + {global-opt...} + { + {local-opt...} + {query} + ...} + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.3.7"></a><h2>DESCRIPTION</h2> + + <p><span class="command"><strong>mdig</strong></span> + is a multiple/pipelined query version of <span class="command"><strong>dig</strong></span>: + instead of waiting for a response after sending each query, + it begins by sending all queries. Responses are displayed in + the order in which they are received, not in the order the + corresponding queries were sent. + </p> + + <p> + <span class="command"><strong>mdig</strong></span> options are a subset of the + <span class="command"><strong>dig</strong></span> options, and are divided into "anywhere + options" which can occur anywhere, "global options" which must + occur before the query name (or they are ignored with a warning), + and "local options" which apply to the next query on the command + line. + </p> + + <p> + The {@server} option is a mandatory global + option. It is the name or IP address of the name server to query. + (Unlike <span class="command"><strong>dig</strong></span>, this value is not retrieved from + <code class="filename">/etc/resolv.conf</code>.) It can be an IPv4 address + in dotted-decimal notation, an IPv6 address in colon-delimited + notation, or a hostname. When the supplied + <em class="parameter"><code>server</code></em> argument is a hostname, + <span class="command"><strong>mdig</strong></span> resolves that name before querying + the name server. + </p> + + <p><span class="command"><strong>mdig</strong></span> + provides a number of query options which affect + the way in which lookups are made and the results displayed. Some of + these set or reset flag bits in the query header, some determine which + sections of the answer get printed, and others determine the timeout + and retry strategies. + </p> + + <p> + Each query option is identified by a keyword preceded by a plus + sign (<code class="literal">+</code>). Some keywords set or reset an + option. These may be preceded by the string <code class="literal">no</code> + to negate the meaning of that keyword. Other keywords assign + values to options like the timeout interval. They have the + form <code class="option">+keyword=value</code>. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.3.8"></a><h2>ANYWHERE OPTIONS</h2> + + + <p> + The <code class="option">-f</code> option makes <span class="command"><strong>mdig</strong></span> + operate in batch mode by reading a list of lookup requests to + process from the file <em class="parameter"><code>filename</code></em>. The file + contains a number of queries, one per line. Each entry in the + file should be organized in the same way they would be presented + as queries to <span class="command"><strong>mdig</strong></span> using the command-line interface. + </p> + + <p> + The <code class="option">-h</code> causes <span class="command"><strong>mdig</strong></span> to + print the detailed help with the full list of options and exit. + </p> + + <p> + The <code class="option">-v</code> causes <span class="command"><strong>mdig</strong></span> to + print the version number and exit. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.3.9"></a><h2>GLOBAL OPTIONS</h2> + + + <p> + The <code class="option">-4</code> option forces <span class="command"><strong>mdig</strong></span> to + only use IPv4 query transport. + </p> + + <p> + The <code class="option">-6</code> option forces <span class="command"><strong>mdig</strong></span> to + only use IPv6 query transport. + </p> + + <p> + The <code class="option">-b</code> option sets the source IP address of the + query to <em class="parameter"><code>address</code></em>. This must be a valid + address on one of the host's network interfaces or "0.0.0.0" or + "::". An optional port may be specified by appending + "#<port>" + </p> + + <p> + The <code class="option">-m</code> option enables memory usage debugging. + </p> + + <p> + The <code class="option">-p</code> option is used when a non-standard port + number is to be queried. + <em class="parameter"><code>port#</code></em> is the port number + that <span class="command"><strong>mdig</strong></span> will send its queries instead of + the standard DNS port number 53. This option would be used to + test a name server that has been configured to listen for + queries on a non-standard port number. + </p> + + <p> + The global query options are: + </p> +<div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><code class="option">+[no]additional</code></span></dt> +<dd> + <p> + Display [do not display] the additional section of a + reply. The default is to display it. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]all</code></span></dt> +<dd> + <p> + Set or clear all display flags. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]answer</code></span></dt> +<dd> + <p> + Display [do not display] the answer section of a + reply. The default is to display it. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]authority</code></span></dt> +<dd> + <p> + Display [do not display] the authority section of a + reply. The default is to display it. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]besteffort</code></span></dt> +<dd> + <p> + Attempt to display the contents of messages which are + malformed. The default is to not display malformed + answers. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]cl</code></span></dt> +<dd> + <p> + Display [do not display] the CLASS when printing the + record. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]comments</code></span></dt> +<dd> + <p> + Toggle the display of comment lines in the output. + The default is to print comments. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]continue</code></span></dt> +<dd> + <p> + Continue on errors (e.g. timeouts). + </p> + </dd> +<dt><span class="term"><code class="option">+[no]crypto</code></span></dt> +<dd> + <p> + Toggle the display of cryptographic fields in DNSSEC + records. The contents of these field are unnecessary + to debug most DNSSEC validation failures and removing + them makes it easier to see the common failures. The + default is to display the fields. When omitted they + are replaced by the string "[omitted]" or in the + DNSKEY case the key id is displayed as the replacement, + e.g. "[ key id = value ]". + </p> + </dd> +<dt><span class="term"><code class="option">+dscp[=value]</code></span></dt> +<dd> + <p> + Set the DSCP code point to be used when sending the + query. Valid DSCP code points are in the range + [0..63]. By default no code point is explicitly set. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]multiline</code></span></dt> +<dd> + <p> + Print records like the SOA records in a verbose + multi-line format with human-readable comments. The + default is to print each record on a single line, to + facilitate machine parsing of the <span class="command"><strong>mdig</strong></span> + output. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]question</code></span></dt> +<dd> + <p> + Print [do not print] the question section of a query + when an answer is returned. The default is to print + the question section as a comment. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]rrcomments</code></span></dt> +<dd> + <p> + Toggle the display of per-record comments in the + output (for example, human-readable key information + about DNSKEY records). The default is not to print + record comments unless multiline mode is active. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]short</code></span></dt> +<dd> + <p> + Provide a terse answer. The default is to print the + answer in a verbose form. + </p> + </dd> +<dt><span class="term"><code class="option">+split=W</code></span></dt> +<dd> + <p> + Split long hex- or base64-formatted fields in resource + records into chunks of <em class="parameter"><code>W</code></em> + characters (where <em class="parameter"><code>W</code></em> is rounded + up to the nearest multiple of 4). + <em class="parameter"><code>+nosplit</code></em> or + <em class="parameter"><code>+split=0</code></em> causes fields not to + be split at all. The default is 56 characters, or + 44 characters when multiline mode is active. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]tcp</code></span></dt> +<dd> + <p> + Use [do not use] TCP when querying name servers. The + default behavior is to use UDP. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]ttlid</code></span></dt> +<dd> + <p> + Display [do not display] the TTL when printing the + record. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]ttlunits</code></span></dt> +<dd> + <p> + Display [do not display] the TTL in friendly human-readable + time units of "s", "m", "h", "d", and "w", representing + seconds, minutes, hours, days and weeks. Implies +ttlid. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]vc</code></span></dt> +<dd> + <p> + Use [do not use] TCP when querying name servers. This + alternate syntax to <em class="parameter"><code>+[no]tcp</code></em> + is provided for backwards compatibility. The "vc" + stands for "virtual circuit". + </p> + </dd> +</dl></div> +<p> + + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.3.10"></a><h2>LOCAL OPTIONS</h2> + + + <p> + The <code class="option">-c</code> option sets the query class to + <em class="parameter"><code>class</code></em>. It can be any valid query class + which is supported in BIND 9. The default query class is "IN". + </p> + + <p> + The <code class="option">-t</code> option sets the query type to + <em class="parameter"><code>type</code></em>. It can be any valid query type + which is supported in BIND 9. The default query type is "A", + unless the <code class="option">-x</code> option is supplied to indicate + a reverse lookup with the "PTR" query type. + </p> + + <p> + The <code class="option">-i</code> option sets the reverse domain for + IPv6 addresses to IP6.INT. + </p> + + <p> + Reverse lookups — mapping addresses to names — are + simplified by the <code class="option">-x</code> option. + <em class="parameter"><code>addr</code></em> is an IPv4 + address in dotted-decimal notation, or a colon-delimited IPv6 address. + <span class="command"><strong>mdig</strong></span> automatically performs a lookup for a + query name like <code class="literal">11.12.13.10.in-addr.arpa</code> and + sets the query type and class to PTR and IN respectively. + By default, IPv6 addresses are looked up using nibble format + under the IP6.ARPA domain. To use the older RFC1886 method + using the IP6.INT domain specify the <code class="option">-i</code> option. + </p> + + <p> + The local query options are: + </p> +<div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><code class="option">+[no]aaflag</code></span></dt> +<dd> + <p> + A synonym for <em class="parameter"><code>+[no]aaonly</code></em>. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]aaonly</code></span></dt> +<dd> + <p> + Sets the "aa" flag in the query. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]adflag</code></span></dt> +<dd> + <p> + Set [do not set] the AD (authentic data) bit in the + query. This requests the server to return whether + all of the answer and authority sections have all + been validated as secure according to the security + policy of the server. AD=1 indicates that all records + have been validated as secure and the answer is not + from a OPT-OUT range. AD=0 indicate that some part + of the answer was insecure or not validated. This + bit is set by default. + </p> + </dd> +<dt><span class="term"><code class="option">+bufsize=B</code></span></dt> +<dd> + <p> + Set the UDP message buffer size advertised using EDNS0 + to <em class="parameter"><code>B</code></em> bytes. The maximum and + minimum sizes of this buffer are 65535 and 0 respectively. + Values outside this range are rounded up or down + appropriately. Values other than zero will cause a + EDNS query to be sent. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]cdflag</code></span></dt> +<dd> + <p> + Set [do not set] the CD (checking disabled) bit in + the query. This requests the server to not perform + DNSSEC validation of responses. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]cookie[<span class="optional">=####</span>]</code></span></dt> +<dd> + <p> + Send a COOKIE EDNS option, with optional value. + Replaying a COOKIE from a previous response will allow + the server to identify a previous client. The default + is <code class="option">+nocookie</code>. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]dnssec</code></span></dt> +<dd> + <p> + Requests DNSSEC records be sent by setting the DNSSEC + OK bit (DO) in the OPT record in the additional section + of the query. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]edns[=#]</code></span></dt> +<dd> + <p> + Specify the EDNS version to query with. Valid values + are 0 to 255. Setting the EDNS version will cause + a EDNS query to be sent. <code class="option">+noedns</code> + clears the remembered EDNS version. EDNS is set to + 0 by default. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]ednsflags[=#]</code></span></dt> +<dd> + <p> + Set the must-be-zero EDNS flags bits (Z bits) to the + specified value. Decimal, hex and octal encodings are + accepted. Setting a named flag (e.g. DO) will silently be + ignored. By default, no Z bits are set. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]ednsopt[=code[:value]]</code></span></dt> +<dd> + <p> + Specify EDNS option with code point <code class="option">code</code> + and optionally payload of <code class="option">value</code> as a + hexadecimal string. <code class="option">+noednsopt</code> + clears the EDNS options to be sent. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]expire</code></span></dt> +<dd> + <p> + Send an EDNS Expire option. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]nsid</code></span></dt> +<dd> + <p> + Include an EDNS name server ID request when sending + a query. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]recurse</code></span></dt> +<dd> + <p> + Toggle the setting of the RD (recursion desired) bit + in the query. This bit is set by default, which means + <span class="command"><strong>mdig</strong></span> normally sends recursive + queries. + </p> + </dd> +<dt><span class="term"><code class="option">+retry=T</code></span></dt> +<dd> + <p> + Sets the number of times to retry UDP queries to + server to <em class="parameter"><code>T</code></em> instead of the + default, 2. Unlike <em class="parameter"><code>+tries</code></em>, + this does not include the initial query. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]subnet=addr[/prefix-length]</code></span></dt> +<dd> + <p> + Send (don't send) an EDNS Client Subnet option with the + specified IP address or network prefix. + </p> + <p> + <span class="command"><strong>mdig +subnet=0.0.0.0/0</strong></span>, or simply + <span class="command"><strong>mdig +subnet=0</strong></span> for short, sends an EDNS + client-subnet option with an empty address and a source + prefix-length of zero, which signals a resolver that + the client's address information must + <span class="emphasis"><em>not</em></span> be used when resolving + this query. + </p> + </dd> +<dt><span class="term"><code class="option">+timeout=T</code></span></dt> +<dd> + <p> + Sets the timeout for a query to + <em class="parameter"><code>T</code></em> seconds. The default + timeout is 5 seconds for UDP transport and 10 for TCP. + An attempt to set <em class="parameter"><code>T</code></em> to less + than 1 will result + in a query timeout of 1 second being applied. + </p> + </dd> +<dt><span class="term"><code class="option">+tries=T</code></span></dt> +<dd> + <p> + Sets the number of times to try UDP queries to server + to <em class="parameter"><code>T</code></em> instead of the default, + 3. If <em class="parameter"><code>T</code></em> is less than or equal + to zero, the number of tries is silently rounded up + to 1. + </p> + </dd> +<dt><span class="term"><code class="option">+udptimeout=T</code></span></dt> +<dd> + <p> + Sets the timeout between UDP query retries. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]unknownformat</code></span></dt> +<dd> + <p> + Print all RDATA in unknown RR type presentation format + (RFC 3597). The default is to print RDATA for known types + in the type's presentation format. + </p> + </dd> +<dt><span class="term"><code class="option">+[no]zflag</code></span></dt> +<dd> + <p> + Set [do not set] the last unassigned DNS header flag in a + DNS query. This flag is off by default. + </p> + </dd> +</dl></div> +<p> + + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.3.11"></a><h2>SEE ALSO</h2> + + <p><span class="citerefentry"> + <span class="refentrytitle">dig</span>(1) + </span>, + <em class="citetitle">RFC1035</em>. + </p> + </div> +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.dig.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.host.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top">dig </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> host</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.named-checkconf.html b/doc/arm/man.named-checkconf.html new file mode 100644 index 0000000..5b5a6c3 --- /dev/null +++ b/doc/arm/man.named-checkconf.html @@ -0,0 +1,197 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>named-checkconf</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.named.conf.html" title="named.conf"> +<link rel="next" href="man.named-checkzone.html" title="named-checkzone"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">named-checkconf</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.named.conf.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.named-checkzone.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.named-checkconf"></a><div class="titlepage"></div> + + + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">named-checkconf</span> + — named configuration file syntax checking tool + </p> +</div> + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">named-checkconf</code> + [<code class="option">-hjvz</code>] + [<code class="option">-p</code> + [<code class="option">-x</code> + ]] + [<code class="option">-t <em class="replaceable"><code>directory</code></em></code>] + {filename} + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.21.7"></a><h2>DESCRIPTION</h2> + + <p><span class="command"><strong>named-checkconf</strong></span> + checks the syntax, but not the semantics, of a + <span class="command"><strong>named</strong></span> configuration file. The file is parsed + and checked for syntax errors, along with all files included by it. + If no file is specified, <code class="filename">/etc/named.conf</code> is read + by default. + </p> + <p> + Note: files that <span class="command"><strong>named</strong></span> reads in separate + parser contexts, such as <code class="filename">rndc.key</code> and + <code class="filename">bind.keys</code>, are not automatically read + by <span class="command"><strong>named-checkconf</strong></span>. Configuration + errors in these files may cause <span class="command"><strong>named</strong></span> to + fail to run, even if <span class="command"><strong>named-checkconf</strong></span> was + successful. <span class="command"><strong>named-checkconf</strong></span> can be run + on these files explicitly, however. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.21.8"></a><h2>OPTIONS</h2> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-h</span></dt> +<dd> + <p> + Print the usage summary and exit. + </p> + </dd> +<dt><span class="term">-j</span></dt> +<dd> + <p> + When loading a zonefile read the journal if it exists. + </p> + </dd> +<dt><span class="term">-p</span></dt> +<dd> + <p> + Print out the <code class="filename">named.conf</code> and included files + in canonical form if no errors were detected. + See also the <code class="option">-x</code> option. + </p> + </dd> +<dt><span class="term">-t <em class="replaceable"><code>directory</code></em></span></dt> +<dd> + <p> + Chroot to <code class="filename">directory</code> so that include + directives in the configuration file are processed as if + run by a similarly chrooted <span class="command"><strong>named</strong></span>. + </p> + </dd> +<dt><span class="term">-v</span></dt> +<dd> + <p> + Print the version of the <span class="command"><strong>named-checkconf</strong></span> + program and exit. + </p> + </dd> +<dt><span class="term">-x</span></dt> +<dd> + <p> + When printing the configuration files in canonical + form, obscure shared secrets by replacing them with + strings of question marks ('?'). This allows the + contents of <code class="filename">named.conf</code> and related + files to be shared — for example, when submitting + bug reports — without compromising private data. + This option cannot be used without <code class="option">-p</code>. + </p> + </dd> +<dt><span class="term">-z</span></dt> +<dd> + <p> + Perform a test load of all master zones found in + <code class="filename">named.conf</code>. + </p> + </dd> +<dt><span class="term">filename</span></dt> +<dd> + <p> + The name of the configuration file to be checked. If not + specified, it defaults to <code class="filename">/etc/named.conf</code>. + </p> + </dd> +</dl></div> + + </div> + + <div class="refsection"> +<a name="id-1.14.21.9"></a><h2>RETURN VALUES</h2> + + <p><span class="command"><strong>named-checkconf</strong></span> + returns an exit status of 1 if + errors were detected and 0 otherwise. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.21.10"></a><h2>SEE ALSO</h2> + + <p><span class="citerefentry"> + <span class="refentrytitle">named</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">named-checkzone</span>(8) + </span>, + <em class="citetitle">BIND 9 Administrator Reference Manual</em>. + </p> + </div> +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.named.conf.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.named-checkzone.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<code class="filename">named.conf</code> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">named-checkzone</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.named-checkzone.html b/doc/arm/man.named-checkzone.html new file mode 100644 index 0000000..9ea0851 --- /dev/null +++ b/doc/arm/man.named-checkzone.html @@ -0,0 +1,468 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>named-checkzone</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.named-checkconf.html" title="named-checkconf"> +<link rel="next" href="man.named-journalprint.html" title="named-journalprint"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">named-checkzone</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.named-checkconf.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.named-journalprint.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.named-checkzone"></a><div class="titlepage"></div> + + + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">named-checkzone</span>, + <span class="application">named-compilezone</span> + — zone file validity checking or converting tool + </p> +</div> + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">named-checkzone</code> + [<code class="option">-d</code>] + [<code class="option">-h</code>] + [<code class="option">-j</code>] + [<code class="option">-q</code>] + [<code class="option">-v</code>] + [<code class="option">-c <em class="replaceable"><code>class</code></em></code>] + [<code class="option">-f <em class="replaceable"><code>format</code></em></code>] + [<code class="option">-F <em class="replaceable"><code>format</code></em></code>] + [<code class="option">-J <em class="replaceable"><code>filename</code></em></code>] + [<code class="option">-i <em class="replaceable"><code>mode</code></em></code>] + [<code class="option">-k <em class="replaceable"><code>mode</code></em></code>] + [<code class="option">-m <em class="replaceable"><code>mode</code></em></code>] + [<code class="option">-M <em class="replaceable"><code>mode</code></em></code>] + [<code class="option">-n <em class="replaceable"><code>mode</code></em></code>] + [<code class="option">-l <em class="replaceable"><code>ttl</code></em></code>] + [<code class="option">-L <em class="replaceable"><code>serial</code></em></code>] + [<code class="option">-o <em class="replaceable"><code>filename</code></em></code>] + [<code class="option">-r <em class="replaceable"><code>mode</code></em></code>] + [<code class="option">-s <em class="replaceable"><code>style</code></em></code>] + [<code class="option">-S <em class="replaceable"><code>mode</code></em></code>] + [<code class="option">-t <em class="replaceable"><code>directory</code></em></code>] + [<code class="option">-T <em class="replaceable"><code>mode</code></em></code>] + [<code class="option">-w <em class="replaceable"><code>directory</code></em></code>] + [<code class="option">-D</code>] + [<code class="option">-W <em class="replaceable"><code>mode</code></em></code>] + {zonename} + {filename} + </p></div> + <div class="cmdsynopsis"><p> + <code class="command">named-compilezone</code> + [<code class="option">-d</code>] + [<code class="option">-j</code>] + [<code class="option">-q</code>] + [<code class="option">-v</code>] + [<code class="option">-c <em class="replaceable"><code>class</code></em></code>] + [<code class="option">-C <em class="replaceable"><code>mode</code></em></code>] + [<code class="option">-f <em class="replaceable"><code>format</code></em></code>] + [<code class="option">-F <em class="replaceable"><code>format</code></em></code>] + [<code class="option">-J <em class="replaceable"><code>filename</code></em></code>] + [<code class="option">-i <em class="replaceable"><code>mode</code></em></code>] + [<code class="option">-k <em class="replaceable"><code>mode</code></em></code>] + [<code class="option">-m <em class="replaceable"><code>mode</code></em></code>] + [<code class="option">-n <em class="replaceable"><code>mode</code></em></code>] + [<code class="option">-l <em class="replaceable"><code>ttl</code></em></code>] + [<code class="option">-L <em class="replaceable"><code>serial</code></em></code>] + [<code class="option">-r <em class="replaceable"><code>mode</code></em></code>] + [<code class="option">-s <em class="replaceable"><code>style</code></em></code>] + [<code class="option">-t <em class="replaceable"><code>directory</code></em></code>] + [<code class="option">-T <em class="replaceable"><code>mode</code></em></code>] + [<code class="option">-w <em class="replaceable"><code>directory</code></em></code>] + [<code class="option">-D</code>] + [<code class="option">-W <em class="replaceable"><code>mode</code></em></code>] + {<code class="option">-o <em class="replaceable"><code>filename</code></em></code>} + {zonename} + {filename} + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.22.7"></a><h2>DESCRIPTION</h2> + + <p><span class="command"><strong>named-checkzone</strong></span> + checks the syntax and integrity of a zone file. It performs the + same checks as <span class="command"><strong>named</strong></span> does when loading a + zone. This makes <span class="command"><strong>named-checkzone</strong></span> useful for + checking zone files before configuring them into a name server. + </p> + <p> + <span class="command"><strong>named-compilezone</strong></span> is similar to + <span class="command"><strong>named-checkzone</strong></span>, but it always dumps the + zone contents to a specified file in a specified format. + Additionally, it applies stricter check levels by default, + since the dump output will be used as an actual zone file + loaded by <span class="command"><strong>named</strong></span>. + When manually specified otherwise, the check levels must at + least be as strict as those specified in the + <span class="command"><strong>named</strong></span> configuration file. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.22.8"></a><h2>OPTIONS</h2> + + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-d</span></dt> +<dd> + <p> + Enable debugging. + </p> + </dd> +<dt><span class="term">-h</span></dt> +<dd> + <p> + Print the usage summary and exit. + </p> + </dd> +<dt><span class="term">-q</span></dt> +<dd> + <p> + Quiet mode - exit code only. + </p> + </dd> +<dt><span class="term">-v</span></dt> +<dd> + <p> + Print the version of the <span class="command"><strong>named-checkzone</strong></span> + program and exit. + </p> + </dd> +<dt><span class="term">-j</span></dt> +<dd> + <p> + When loading a zone file, read the journal if it exists. + The journal file name is assumed to be the zone file name + appended with the string <code class="filename">.jnl</code>. + </p> + </dd> +<dt><span class="term">-J <em class="replaceable"><code>filename</code></em></span></dt> +<dd> + <p> + When loading the zone file read the journal from the given + file, if it exists. (Implies -j.) + </p> + </dd> +<dt><span class="term">-c <em class="replaceable"><code>class</code></em></span></dt> +<dd> + <p> + Specify the class of the zone. If not specified, "IN" is assumed. + </p> + </dd> +<dt><span class="term">-i <em class="replaceable"><code>mode</code></em></span></dt> +<dd> + <p> + Perform post-load zone integrity checks. Possible modes are + <span class="command"><strong>"full"</strong></span> (default), + <span class="command"><strong>"full-sibling"</strong></span>, + <span class="command"><strong>"local"</strong></span>, + <span class="command"><strong>"local-sibling"</strong></span> and + <span class="command"><strong>"none"</strong></span>. + </p> + <p> + Mode <span class="command"><strong>"full"</strong></span> checks that MX records + refer to A or AAAA record (both in-zone and out-of-zone + hostnames). Mode <span class="command"><strong>"local"</strong></span> only + checks MX records which refer to in-zone hostnames. + </p> + <p> + Mode <span class="command"><strong>"full"</strong></span> checks that SRV records + refer to A or AAAA record (both in-zone and out-of-zone + hostnames). Mode <span class="command"><strong>"local"</strong></span> only + checks SRV records which refer to in-zone hostnames. + </p> + <p> + Mode <span class="command"><strong>"full"</strong></span> checks that delegation NS + records refer to A or AAAA record (both in-zone and out-of-zone + hostnames). It also checks that glue address records + in the zone match those advertised by the child. + Mode <span class="command"><strong>"local"</strong></span> only checks NS records which + refer to in-zone hostnames or that some required glue exists, + that is when the nameserver is in a child zone. + </p> + <p> + Mode <span class="command"><strong>"full-sibling"</strong></span> and + <span class="command"><strong>"local-sibling"</strong></span> disable sibling glue + checks but are otherwise the same as <span class="command"><strong>"full"</strong></span> + and <span class="command"><strong>"local"</strong></span> respectively. + </p> + <p> + Mode <span class="command"><strong>"none"</strong></span> disables the checks. + </p> + </dd> +<dt><span class="term">-f <em class="replaceable"><code>format</code></em></span></dt> +<dd> + <p> + Specify the format of the zone file. + Possible formats are <span class="command"><strong>"text"</strong></span> (default), + <span class="command"><strong>"raw"</strong></span>, and <span class="command"><strong>"map"</strong></span>. + </p> + </dd> +<dt><span class="term">-F <em class="replaceable"><code>format</code></em></span></dt> +<dd> + <p> + Specify the format of the output file specified. + For <span class="command"><strong>named-checkzone</strong></span>, + this does not cause any effects unless it dumps the zone + contents. + </p> + <p> + Possible formats are <span class="command"><strong>"text"</strong></span> (default), + which is the standard textual representation of the zone, + and <span class="command"><strong>"map"</strong></span>, <span class="command"><strong>"raw"</strong></span>, + and <span class="command"><strong>"raw=N"</strong></span>, which store the zone in a + binary format for rapid loading by <span class="command"><strong>named</strong></span>. + <span class="command"><strong>"raw=N"</strong></span> specifies the format version of + the raw zone file: if N is 0, the raw file can be read by + any version of <span class="command"><strong>named</strong></span>; if N is 1, the file + can be read by release 9.9.0 or higher; the default is 1. + </p> + </dd> +<dt><span class="term">-k <em class="replaceable"><code>mode</code></em></span></dt> +<dd> + <p> + Perform <span class="command"><strong>"check-names"</strong></span> checks with the + specified failure mode. + Possible modes are <span class="command"><strong>"fail"</strong></span> + (default for <span class="command"><strong>named-compilezone</strong></span>), + <span class="command"><strong>"warn"</strong></span> + (default for <span class="command"><strong>named-checkzone</strong></span>) and + <span class="command"><strong>"ignore"</strong></span>. + </p> + </dd> +<dt><span class="term">-l <em class="replaceable"><code>ttl</code></em></span></dt> +<dd> + <p> + Sets a maximum permissible TTL for the input file. + Any record with a TTL higher than this value will cause + the zone to be rejected. This is similar to using the + <span class="command"><strong>max-zone-ttl</strong></span> option in + <code class="filename">named.conf</code>. + </p> + </dd> +<dt><span class="term">-L <em class="replaceable"><code>serial</code></em></span></dt> +<dd> + <p> + When compiling a zone to "raw" or "map" format, set the + "source serial" value in the header to the specified serial + number. (This is expected to be used primarily for testing + purposes.) + </p> + </dd> +<dt><span class="term">-m <em class="replaceable"><code>mode</code></em></span></dt> +<dd> + <p> + Specify whether MX records should be checked to see if they + are addresses. Possible modes are <span class="command"><strong>"fail"</strong></span>, + <span class="command"><strong>"warn"</strong></span> (default) and + <span class="command"><strong>"ignore"</strong></span>. + </p> + </dd> +<dt><span class="term">-M <em class="replaceable"><code>mode</code></em></span></dt> +<dd> + <p> + Check if a MX record refers to a CNAME. + Possible modes are <span class="command"><strong>"fail"</strong></span>, + <span class="command"><strong>"warn"</strong></span> (default) and + <span class="command"><strong>"ignore"</strong></span>. + </p> + </dd> +<dt><span class="term">-n <em class="replaceable"><code>mode</code></em></span></dt> +<dd> + <p> + Specify whether NS records should be checked to see if they + are addresses. + Possible modes are <span class="command"><strong>"fail"</strong></span> + (default for <span class="command"><strong>named-compilezone</strong></span>), + <span class="command"><strong>"warn"</strong></span> + (default for <span class="command"><strong>named-checkzone</strong></span>) and + <span class="command"><strong>"ignore"</strong></span>. + </p> + </dd> +<dt><span class="term">-o <em class="replaceable"><code>filename</code></em></span></dt> +<dd> + <p> + Write zone output to <code class="filename">filename</code>. + If <code class="filename">filename</code> is <code class="filename">-</code> then + write to standard out. + This is mandatory for <span class="command"><strong>named-compilezone</strong></span>. + </p> + </dd> +<dt><span class="term">-r <em class="replaceable"><code>mode</code></em></span></dt> +<dd> + <p> + Check for records that are treated as different by DNSSEC but + are semantically equal in plain DNS. + Possible modes are <span class="command"><strong>"fail"</strong></span>, + <span class="command"><strong>"warn"</strong></span> (default) and + <span class="command"><strong>"ignore"</strong></span>. + </p> + </dd> +<dt><span class="term">-s <em class="replaceable"><code>style</code></em></span></dt> +<dd> + <p> + Specify the style of the dumped zone file. + Possible styles are <span class="command"><strong>"full"</strong></span> (default) + and <span class="command"><strong>"relative"</strong></span>. + The full format is most suitable for processing + automatically by a separate script. + On the other hand, the relative format is more + human-readable and is thus suitable for editing by hand. + For <span class="command"><strong>named-checkzone</strong></span> + this does not cause any effects unless it dumps the zone + contents. + It also does not have any meaning if the output format + is not text. + </p> + </dd> +<dt><span class="term">-S <em class="replaceable"><code>mode</code></em></span></dt> +<dd> + <p> + Check if a SRV record refers to a CNAME. + Possible modes are <span class="command"><strong>"fail"</strong></span>, + <span class="command"><strong>"warn"</strong></span> (default) and + <span class="command"><strong>"ignore"</strong></span>. + </p> + </dd> +<dt><span class="term">-t <em class="replaceable"><code>directory</code></em></span></dt> +<dd> + <p> + Chroot to <code class="filename">directory</code> so that + include + directives in the configuration file are processed as if + run by a similarly chrooted <span class="command"><strong>named</strong></span>. + </p> + </dd> +<dt><span class="term">-T <em class="replaceable"><code>mode</code></em></span></dt> +<dd> + <p> + Check if Sender Policy Framework (SPF) records exist + and issues a warning if an SPF-formatted TXT record is + not also present. Possible modes are <span class="command"><strong>"warn"</strong></span> + (default), <span class="command"><strong>"ignore"</strong></span>. + </p> + </dd> +<dt><span class="term">-w <em class="replaceable"><code>directory</code></em></span></dt> +<dd> + <p> + chdir to <code class="filename">directory</code> so that + relative + filenames in master file $INCLUDE directives work. This + is similar to the directory clause in + <code class="filename">named.conf</code>. + </p> + </dd> +<dt><span class="term">-D</span></dt> +<dd> + <p> + Dump zone file in canonical format. + This is always enabled for <span class="command"><strong>named-compilezone</strong></span>. + </p> + </dd> +<dt><span class="term">-W <em class="replaceable"><code>mode</code></em></span></dt> +<dd> + <p> + Specify whether to check for non-terminal wildcards. + Non-terminal wildcards are almost always the result of a + failure to understand the wildcard matching algorithm (RFC 1034). + Possible modes are <span class="command"><strong>"warn"</strong></span> (default) + and + <span class="command"><strong>"ignore"</strong></span>. + </p> + </dd> +<dt><span class="term">zonename</span></dt> +<dd> + <p> + The domain name of the zone being checked. + </p> + </dd> +<dt><span class="term">filename</span></dt> +<dd> + <p> + The name of the zone file. + </p> + </dd> +</dl></div> + + </div> + + <div class="refsection"> +<a name="id-1.14.22.9"></a><h2>RETURN VALUES</h2> + + <p><span class="command"><strong>named-checkzone</strong></span> + returns an exit status of 1 if + errors were detected and 0 otherwise. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.22.10"></a><h2>SEE ALSO</h2> + + <p><span class="citerefentry"> + <span class="refentrytitle">named</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">named-checkconf</span>(8) + </span>, + <em class="citetitle">RFC 1035</em>, + <em class="citetitle">BIND 9 Administrator Reference Manual</em>. + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.named-checkconf.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.named-journalprint.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">named-checkconf</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">named-journalprint</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.named-journalprint.html b/doc/arm/man.named-journalprint.html new file mode 100644 index 0000000..7c7be26 --- /dev/null +++ b/doc/arm/man.named-journalprint.html @@ -0,0 +1,122 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>named-journalprint</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.named-checkzone.html" title="named-checkzone"> +<link rel="next" href="man.named-nzd2nzf.html" title="named-nzd2nzf"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">named-journalprint</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.named-checkzone.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.named-nzd2nzf.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.named-journalprint"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">named-journalprint</span> + — print zone journal in human-readable form + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">named-journalprint</code> + {<em class="replaceable"><code>journal</code></em>} + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.23.7"></a><h2>DESCRIPTION</h2> + + <p> + <span class="command"><strong>named-journalprint</strong></span> + prints the contents of a zone journal file in a human-readable + form. + </p> + <p> + Journal files are automatically created by <span class="command"><strong>named</strong></span> + when changes are made to dynamic zones (e.g., by + <span class="command"><strong>nsupdate</strong></span>). They record each addition + or deletion of a resource record, in binary format, allowing the + changes to be re-applied to the zone when the server is + restarted after a shutdown or crash. By default, the name of + the journal file is formed by appending the extension + <code class="filename">.jnl</code> to the name of the corresponding + zone file. + </p> + <p> + <span class="command"><strong>named-journalprint</strong></span> converts the contents of a given + journal file into a human-readable text format. Each line begins + with "add" or "del", to indicate whether the record was added or + deleted, and continues with the resource record in master-file + format. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.23.8"></a><h2>SEE ALSO</h2> + + <p> + <span class="citerefentry"> + <span class="refentrytitle">named</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">nsupdate</span>(1) + </span>, + <em class="citetitle">BIND 9 Administrator Reference Manual</em>. + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.named-checkzone.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.named-nzd2nzf.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">named-checkzone</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">named-nzd2nzf</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.named-nzd2nzf.html b/doc/arm/man.named-nzd2nzf.html new file mode 100644 index 0000000..931788a --- /dev/null +++ b/doc/arm/man.named-nzd2nzf.html @@ -0,0 +1,124 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>named-nzd2nzf</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.named-journalprint.html" title="named-journalprint"> +<link rel="next" href="man.named-rrchecker.html" title="named-rrchecker"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">named-nzd2nzf</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.named-journalprint.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.named-rrchecker.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.named-nzd2nzf"></a><div class="titlepage"></div> + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">named-nzd2nzf</span> + — + Convert an NZD database to NZF text format + + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">named-nzd2nzf</code> + {filename} + </p></div> + </div> + + <div class="refsect1"> +<a name="id-1.14.24.6"></a><h2>DESCRIPTION</h2> + + <p> + <span class="command"><strong>named-nzd2nzf</strong></span> converts an NZD database to NZF + format and prints it to standard output. This can be used to + review the configuration of zones that were added to + <span class="command"><strong>named</strong></span> via <span class="command"><strong>rndc addzone</strong></span>. + It can also be used to restore the old file format + when rolling back from a newer version + of BIND to an older version. + </p> + </div> + + <div class="refsect1"> +<a name="id-1.14.24.7"></a><h2>ARGUMENTS</h2> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">filename</span></dt> +<dd> + <p> + The name of the <code class="filename">.nzd</code> file whose contents + should be printed. + </p> + </dd> +</dl></div> + </div> + + <div class="refsect1"> +<a name="id-1.14.24.8"></a><h2>SEE ALSO</h2> + + <p> + <em class="citetitle">BIND 9 Administrator Reference Manual</em> + </p> + </div> + + <div class="refsect1"> +<a name="id-1.14.24.9"></a><h2>AUTHOR</h2> + + <p><span class="corpauthor">Internet Systems Consortium</span> + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.named-journalprint.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.named-rrchecker.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">named-journalprint</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">named-rrchecker</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.named-rrchecker.html b/doc/arm/man.named-rrchecker.html new file mode 100644 index 0000000..4ad45c9 --- /dev/null +++ b/doc/arm/man.named-rrchecker.html @@ -0,0 +1,126 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>named-rrchecker</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.named-nzd2nzf.html" title="named-nzd2nzf"> +<link rel="next" href="man.nsupdate.html" title="nsupdate"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">named-rrchecker</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.named-nzd2nzf.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.nsupdate.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.named-rrchecker"></a><div class="titlepage"></div> + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">named-rrchecker</span> + — syntax checker for individual DNS resource records + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">named-rrchecker</code> + [<code class="option">-h</code>] + [<code class="option">-o <em class="replaceable"><code>origin</code></em></code>] + [<code class="option">-p</code>] + [<code class="option">-u</code>] + [<code class="option">-C</code>] + [<code class="option">-T</code>] + [<code class="option">-P</code>] + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.25.7"></a><h2>DESCRIPTION</h2> + + <p><span class="command"><strong>named-rrchecker</strong></span> + read a individual DNS resource record from standard input and checks if it + is syntactically correct. + </p> + <p> + The <code class="option">-h</code> prints out the help menu. + </p> + <p> + The <code class="option">-o <em class="replaceable"><code>origin</code></em></code> + option specifies a origin to be used when interpreting the record. + </p> + <p> + The <code class="option">-p</code> prints out the resulting record in canonical + form. If there is no canonical form defined then the record will be + printed in unknown record format. + </p> + <p> + The <code class="option">-u</code> prints out the resulting record in unknown record + form. + </p> + <p> + The <code class="option">-C</code>, <code class="option">-T</code> and <code class="option">-P</code> + print out the known class, standard type and private type mnemonics + respectively. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.25.8"></a><h2>SEE ALSO</h2> + + <p> + <em class="citetitle">RFC 1034</em>, + <em class="citetitle">RFC 1035</em>, + <span class="citerefentry"> + <span class="refentrytitle">named</span>(8) + </span> + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.named-nzd2nzf.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.nsupdate.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">named-nzd2nzf</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">nsupdate</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.named.conf.html b/doc/arm/man.named.conf.html new file mode 100644 index 0000000..479f38c --- /dev/null +++ b/doc/arm/man.named.conf.html @@ -0,0 +1,1041 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>named.conf</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.named.html" title="named"> +<link rel="next" href="man.named-checkconf.html" title="named-checkconf"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><code class="filename">named.conf</code></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.named.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.named-checkconf.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.named.conf"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <code class="filename">named.conf</code> + — configuration file for <span class="command"><strong>named</strong></span> + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">named.conf</code> + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.20.7"></a><h2>DESCRIPTION</h2> + + <p><code class="filename">named.conf</code> is the configuration file + for + <span class="command"><strong>named</strong></span>. Statements are enclosed + in braces and terminated with a semi-colon. Clauses in + the statements are also semi-colon terminated. The usual + comment styles are supported: + </p> + <p> + C style: /* */ + </p> + <p> + C++ style: // to end of line + </p> + <p> + Unix style: # to end of line + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.20.8"></a><h2>ACL</h2> + + <div class="literallayout"><p><br> +acl <em class="replaceable"><code>string</code></em> { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> +</p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.20.9"></a><h2>CONTROLS</h2> + + <div class="literallayout"><p><br> +controls {<br> + inet ( <em class="replaceable"><code>ipv4_address</code></em> | <em class="replaceable"><code>ipv6_address</code></em> |<br> + * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] allow<br> + { <em class="replaceable"><code>address_match_element</code></em>; ... } [<br> + keys { <em class="replaceable"><code>string</code></em>; ... } ] [ read-only<br> + <em class="replaceable"><code>boolean</code></em> ];<br> + unix <em class="replaceable"><code>quoted_string</code></em> perm <em class="replaceable"><code>integer</code></em><br> + owner <em class="replaceable"><code>integer</code></em> group <em class="replaceable"><code>integer</code></em> [<br> + keys { <em class="replaceable"><code>string</code></em>; ... } ] [ read-only<br> + <em class="replaceable"><code>boolean</code></em> ];<br> +};<br> +</p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.20.10"></a><h2>DLZ</h2> + + <div class="literallayout"><p><br> +dlz <em class="replaceable"><code>string</code></em> {<br> + database <em class="replaceable"><code>string</code></em>;<br> + search <em class="replaceable"><code>boolean</code></em>;<br> +};<br> +</p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.20.11"></a><h2>DYNDB</h2> + + <div class="literallayout"><p><br> +dyndb <em class="replaceable"><code>string</code></em> <em class="replaceable"><code>quoted_string</code></em> {<br> + <em class="replaceable"><code>unspecified-text</code></em> };<br> +</p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.20.12"></a><h2>KEY</h2> + + <div class="literallayout"><p><br> +key <em class="replaceable"><code>string</code></em> {<br> + algorithm <em class="replaceable"><code>string</code></em>;<br> + secret <em class="replaceable"><code>string</code></em>;<br> +};<br> +</p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.20.13"></a><h2>LOGGING</h2> + + <div class="literallayout"><p><br> +logging {<br> + category <em class="replaceable"><code>string</code></em> { <em class="replaceable"><code>string</code></em>; ... };<br> + channel <em class="replaceable"><code>string</code></em> {<br> + buffered <em class="replaceable"><code>boolean</code></em>;<br> + file <em class="replaceable"><code>quoted_string</code></em> [ versions ( "unlimited" | <em class="replaceable"><code>integer</code></em> )<br> + ] [ size <em class="replaceable"><code>size</code></em> ];<br> + null;<br> + print-category <em class="replaceable"><code>boolean</code></em>;<br> + print-severity <em class="replaceable"><code>boolean</code></em>;<br> + print-time <em class="replaceable"><code>boolean</code></em>;<br> + severity <em class="replaceable"><code>log_severity</code></em>;<br> + stderr;<br> + syslog [ <em class="replaceable"><code>syslog_facility</code></em> ];<br> + };<br> +};<br> +</p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.20.14"></a><h2>LWRES</h2> + + <div class="literallayout"><p><br> +lwres {<br> + listen-on [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>ipv4_address</code></em><br> + | <em class="replaceable"><code>ipv6_address</code></em> ) [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ]; ... };<br> + lwres-clients <em class="replaceable"><code>integer</code></em>;<br> + lwres-tasks <em class="replaceable"><code>integer</code></em>;<br> + ndots <em class="replaceable"><code>integer</code></em>;<br> + search { <em class="replaceable"><code>string</code></em>; ... };<br> + view <em class="replaceable"><code>string</code></em> [ <em class="replaceable"><code>class</code></em> ];<br> +};<br> +</p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.20.15"></a><h2>MANAGED-KEYS</h2> + + <div class="literallayout"><p><br> +managed-keys { <em class="replaceable"><code>string</code></em> <em class="replaceable"><code>string</code></em> <em class="replaceable"><code>integer</code></em><br> + <em class="replaceable"><code>integer</code></em> <em class="replaceable"><code>integer</code></em> <em class="replaceable"><code>quoted_string</code></em>; ... };<br> +</p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.20.16"></a><h2>MASTERS</h2> + + <div class="literallayout"><p><br> +masters <em class="replaceable"><code>string</code></em> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp<br> + <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>masters</code></em> | <em class="replaceable"><code>ipv4_address</code></em> [<br> + port <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port<br> + <em class="replaceable"><code>integer</code></em> ] ) [ key <em class="replaceable"><code>string</code></em> ]; ... };<br> +</p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.20.17"></a><h2>OPTIONS</h2> + + <div class="literallayout"><p><br> +options {<br> + acache-cleaning-interval <em class="replaceable"><code>integer</code></em>;<br> + acache-enable <em class="replaceable"><code>boolean</code></em>;<br> + additional-from-auth <em class="replaceable"><code>boolean</code></em>;<br> + additional-from-cache <em class="replaceable"><code>boolean</code></em>;<br> + allow-new-zones <em class="replaceable"><code>boolean</code></em>;<br> + allow-notify { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-query { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-query-cache { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-query-cache-on { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-query-on { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-recursion { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-recursion-on { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-transfer { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-update { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-update-forwarding { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + also-notify [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>masters</code></em> |<br> + <em class="replaceable"><code>ipv4_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port<br> + <em class="replaceable"><code>integer</code></em> ] ) [ key <em class="replaceable"><code>string</code></em> ]; ... };<br> + alt-transfer-source ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * )<br> + ] [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + alt-transfer-source-v6 ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> |<br> + * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + answer-cookie <em class="replaceable"><code>boolean</code></em>;<br> + attach-cache <em class="replaceable"><code>string</code></em>;<br> + auth-nxdomain <em class="replaceable"><code>boolean</code></em>; // default changed<br> + auto-dnssec ( allow | maintain | off );<br> + automatic-interface-scan <em class="replaceable"><code>boolean</code></em>;<br> + avoid-v4-udp-ports { <em class="replaceable"><code>portrange</code></em>; ... };<br> + avoid-v6-udp-ports { <em class="replaceable"><code>portrange</code></em>; ... };<br> + bindkeys-file <em class="replaceable"><code>quoted_string</code></em>;<br> + blackhole { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + cache-file <em class="replaceable"><code>quoted_string</code></em>;<br> + catalog-zones { zone <em class="replaceable"><code>quoted_string</code></em> [ default-masters [ port<br> + <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>masters</code></em> | <em class="replaceable"><code>ipv4_address</code></em> [<br> + port <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] ) [ key<br> + <em class="replaceable"><code>string</code></em> ]; ... } ] [ zone-directory <em class="replaceable"><code>quoted_string</code></em> ] [<br> + in-memory <em class="replaceable"><code>boolean</code></em> ] [ min-update-interval <em class="replaceable"><code>integer</code></em> ]; ... };<br> + check-dup-records ( fail | warn | ignore );<br> + check-integrity <em class="replaceable"><code>boolean</code></em>;<br> + check-mx ( fail | warn | ignore );<br> + check-mx-cname ( fail | warn | ignore );<br> + check-names ( master | slave | response<br> + ) ( fail | warn | ignore );<br> + check-sibling <em class="replaceable"><code>boolean</code></em>;<br> + check-spf ( warn | ignore );<br> + check-srv-cname ( fail | warn | ignore );<br> + check-wildcard <em class="replaceable"><code>boolean</code></em>;<br> + cleaning-interval <em class="replaceable"><code>integer</code></em>;<br> + clients-per-query <em class="replaceable"><code>integer</code></em>;<br> + cookie-algorithm ( aes | sha1 | sha256 );<br> + cookie-secret <em class="replaceable"><code>string</code></em>;<br> + coresize ( default | unlimited | <em class="replaceable"><code>sizeval</code></em> );<br> + datasize ( default | unlimited | <em class="replaceable"><code>sizeval</code></em> );<br> + deny-answer-addresses { <em class="replaceable"><code>address_match_element</code></em>; ... } [<br> + except-from { <em class="replaceable"><code>quoted_string</code></em>; ... } ];<br> + deny-answer-aliases { <em class="replaceable"><code>quoted_string</code></em>; ... } [ except-from {<br> + <em class="replaceable"><code>quoted_string</code></em>; ... } ];<br> + dialup ( notify | notify-passive | passive | refresh | <em class="replaceable"><code>boolean</code></em> );<br> + directory <em class="replaceable"><code>quoted_string</code></em>;<br> + disable-algorithms <em class="replaceable"><code>string</code></em> { <em class="replaceable"><code>string</code></em>;<br> + ... };<br> + disable-ds-digests <em class="replaceable"><code>string</code></em> { <em class="replaceable"><code>string</code></em>;<br> + ... };<br> + disable-empty-zone <em class="replaceable"><code>string</code></em>;<br> + dns64 <em class="replaceable"><code>netprefix</code></em> {<br> + break-dnssec <em class="replaceable"><code>boolean</code></em>;<br> + clients { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + exclude { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + mapped { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + recursive-only <em class="replaceable"><code>boolean</code></em>;<br> + suffix <em class="replaceable"><code>ipv6_address</code></em>;<br> + };<br> + dns64-contact <em class="replaceable"><code>string</code></em>;<br> + dns64-server <em class="replaceable"><code>string</code></em>;<br> + dnssec-accept-expired <em class="replaceable"><code>boolean</code></em>;<br> + dnssec-dnskey-kskonly <em class="replaceable"><code>boolean</code></em>;<br> + dnssec-enable <em class="replaceable"><code>boolean</code></em>;<br> + dnssec-loadkeys-interval <em class="replaceable"><code>integer</code></em>;<br> + dnssec-lookaside ( <em class="replaceable"><code>string</code></em> trust-anchor<br> + <em class="replaceable"><code>string</code></em> | auto | no );<br> + dnssec-must-be-secure <em class="replaceable"><code>string</code></em> <em class="replaceable"><code>boolean</code></em>;<br> + dnssec-secure-to-insecure <em class="replaceable"><code>boolean</code></em>;<br> + dnssec-update-mode ( maintain | no-resign );<br> + dnssec-validation ( yes | no | auto );<br> + dnstap { ( all | auth | client | forwarder |<br> + resolver ) [ ( query | response ) ]; ... };<br> + dnstap-identity ( <em class="replaceable"><code>quoted_string</code></em> | none |<br> + hostname );<br> + dnstap-output ( file | unix ) <em class="replaceable"><code>quoted_string</code></em>;<br> + dnstap-version ( <em class="replaceable"><code>quoted_string</code></em> | none );<br> + dscp <em class="replaceable"><code>integer</code></em>;<br> + dual-stack-servers [ port <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>quoted_string</code></em> [ port<br> + <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv4_address</code></em> [ port<br> + <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port<br> + <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] ); ... };<br> + dump-file <em class="replaceable"><code>quoted_string</code></em>;<br> + edns-udp-size <em class="replaceable"><code>integer</code></em>;<br> + empty-contact <em class="replaceable"><code>string</code></em>;<br> + empty-server <em class="replaceable"><code>string</code></em>;<br> + empty-zones-enable <em class="replaceable"><code>boolean</code></em>;<br> + fetch-quota-params <em class="replaceable"><code>integer</code></em> <em class="replaceable"><code>fixedpoint</code></em> <em class="replaceable"><code>fixedpoint</code></em> <em class="replaceable"><code>fixedpoint</code></em>;<br> + fetches-per-server <em class="replaceable"><code>integer</code></em> [ ( drop | fail ) ];<br> + fetches-per-zone <em class="replaceable"><code>integer</code></em> [ ( drop | fail ) ];<br> + files ( default | unlimited | <em class="replaceable"><code>sizeval</code></em> );<br> + filter-aaaa { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + filter-aaaa-on-v4 ( break-dnssec | <em class="replaceable"><code>boolean</code></em> );<br> + filter-aaaa-on-v6 ( break-dnssec | <em class="replaceable"><code>boolean</code></em> );<br> + flush-zones-on-shutdown <em class="replaceable"><code>boolean</code></em>;<br> + forward ( first | only );<br> + forwarders [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>ipv4_address</code></em><br> + | <em class="replaceable"><code>ipv6_address</code></em> ) [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ]; ... };<br> + fstrm-set-buffer-hint <em class="replaceable"><code>integer</code></em>;<br> + fstrm-set-flush-timeout <em class="replaceable"><code>integer</code></em>;<br> + fstrm-set-input-queue-size <em class="replaceable"><code>integer</code></em>;<br> + fstrm-set-output-notify-threshold <em class="replaceable"><code>integer</code></em>;<br> + fstrm-set-output-queue-model ( mpsc | spsc );<br> + fstrm-set-output-queue-size <em class="replaceable"><code>integer</code></em>;<br> + fstrm-set-reopen-interval <em class="replaceable"><code>integer</code></em>;<br> + geoip-directory ( <em class="replaceable"><code>quoted_string</code></em> | none );<br> + geoip-use-ecs <em class="replaceable"><code>boolean</code></em>;<br> + heartbeat-interval <em class="replaceable"><code>integer</code></em>;<br> + hostname ( <em class="replaceable"><code>quoted_string</code></em> | none );<br> + inline-signing <em class="replaceable"><code>boolean</code></em>;<br> + interface-interval <em class="replaceable"><code>integer</code></em>;<br> + ixfr-from-differences ( master | slave | <em class="replaceable"><code>boolean</code></em> );<br> + keep-response-order { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + key-directory <em class="replaceable"><code>quoted_string</code></em>;<br> + lame-ttl <em class="replaceable"><code>ttlval</code></em>;<br> + listen-on [ port <em class="replaceable"><code>integer</code></em> ] [ dscp<br> + <em class="replaceable"><code>integer</code></em> ] {<br> + <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + listen-on-v6 [ port <em class="replaceable"><code>integer</code></em> ] [ dscp<br> + <em class="replaceable"><code>integer</code></em> ] {<br> + <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + lmdb-mapsize <em class="replaceable"><code>sizeval</code></em>;<br> + lock-file ( <em class="replaceable"><code>quoted_string</code></em> | none );<br> + managed-keys-directory <em class="replaceable"><code>quoted_string</code></em>;<br> + masterfile-format ( map | raw | text );<br> + masterfile-style ( full | relative );<br> + match-mapped-addresses <em class="replaceable"><code>boolean</code></em>;<br> + max-acache-size ( unlimited | <em class="replaceable"><code>sizeval</code></em> );<br> + max-cache-size ( default | unlimited | <em class="replaceable"><code>sizeval</code></em> | <em class="replaceable"><code>percentage</code></em> );<br> + max-cache-ttl <em class="replaceable"><code>integer</code></em>;<br> + max-clients-per-query <em class="replaceable"><code>integer</code></em>;<br> + max-journal-size ( unlimited | <em class="replaceable"><code>sizeval</code></em> );<br> + max-ncache-ttl <em class="replaceable"><code>integer</code></em>;<br> + max-records <em class="replaceable"><code>integer</code></em>;<br> + max-recursion-depth <em class="replaceable"><code>integer</code></em>;<br> + max-recursion-queries <em class="replaceable"><code>integer</code></em>;<br> + max-refresh-time <em class="replaceable"><code>integer</code></em>;<br> + max-retry-time <em class="replaceable"><code>integer</code></em>;<br> + max-rsa-exponent-size <em class="replaceable"><code>integer</code></em>;<br> + max-transfer-idle-in <em class="replaceable"><code>integer</code></em>;<br> + max-transfer-idle-out <em class="replaceable"><code>integer</code></em>;<br> + max-transfer-time-in <em class="replaceable"><code>integer</code></em>;<br> + max-transfer-time-out <em class="replaceable"><code>integer</code></em>;<br> + max-udp-size <em class="replaceable"><code>integer</code></em>;<br> + max-zone-ttl ( unlimited | <em class="replaceable"><code>ttlval</code></em> );<br> + memstatistics <em class="replaceable"><code>boolean</code></em>;<br> + memstatistics-file <em class="replaceable"><code>quoted_string</code></em>;<br> + message-compression <em class="replaceable"><code>boolean</code></em>;<br> + min-refresh-time <em class="replaceable"><code>integer</code></em>;<br> + min-retry-time <em class="replaceable"><code>integer</code></em>;<br> + minimal-any <em class="replaceable"><code>boolean</code></em>;<br> + minimal-responses ( no-auth | no-auth-recursive | <em class="replaceable"><code>boolean</code></em> );<br> + multi-master <em class="replaceable"><code>boolean</code></em>;<br> + no-case-compress { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + nocookie-udp-size <em class="replaceable"><code>integer</code></em>;<br> + notify ( explicit | master-only | <em class="replaceable"><code>boolean</code></em> );<br> + notify-delay <em class="replaceable"><code>integer</code></em>;<br> + notify-rate <em class="replaceable"><code>integer</code></em>;<br> + notify-source ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [<br> + dscp <em class="replaceable"><code>integer</code></em> ];<br> + notify-source-v6 ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ]<br> + [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + notify-to-soa <em class="replaceable"><code>boolean</code></em>;<br> + nta-lifetime <em class="replaceable"><code>ttlval</code></em>;<br> + nta-recheck <em class="replaceable"><code>ttlval</code></em>;<br> + nxdomain-redirect <em class="replaceable"><code>string</code></em>;<br> + pid-file ( <em class="replaceable"><code>quoted_string</code></em> | none );<br> + port <em class="replaceable"><code>integer</code></em>;<br> + preferred-glue <em class="replaceable"><code>string</code></em>;<br> + prefetch <em class="replaceable"><code>integer</code></em> [ <em class="replaceable"><code>integer</code></em> ];<br> + provide-ixfr <em class="replaceable"><code>boolean</code></em>;<br> + query-source ( ( [ address ] ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port (<br> + <em class="replaceable"><code>integer</code></em> | * ) ] ) | ( [ [ address ] ( <em class="replaceable"><code>ipv4_address</code></em> | * ) ]<br> + port ( <em class="replaceable"><code>integer</code></em> | * ) ) ) [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + query-source-v6 ( ( [ address ] ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port (<br> + <em class="replaceable"><code>integer</code></em> | * ) ] ) | ( [ [ address ] ( <em class="replaceable"><code>ipv6_address</code></em> | * ) ]<br> + port ( <em class="replaceable"><code>integer</code></em> | * ) ) ) [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + querylog <em class="replaceable"><code>boolean</code></em>;<br> + random-device <em class="replaceable"><code>quoted_string</code></em>;<br> + rate-limit {<br> + all-per-second <em class="replaceable"><code>integer</code></em>;<br> + errors-per-second <em class="replaceable"><code>integer</code></em>;<br> + exempt-clients { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + ipv4-prefix-length <em class="replaceable"><code>integer</code></em>;<br> + ipv6-prefix-length <em class="replaceable"><code>integer</code></em>;<br> + log-only <em class="replaceable"><code>boolean</code></em>;<br> + max-table-size <em class="replaceable"><code>integer</code></em>;<br> + min-table-size <em class="replaceable"><code>integer</code></em>;<br> + nodata-per-second <em class="replaceable"><code>integer</code></em>;<br> + nxdomains-per-second <em class="replaceable"><code>integer</code></em>;<br> + qps-scale <em class="replaceable"><code>integer</code></em>;<br> + referrals-per-second <em class="replaceable"><code>integer</code></em>;<br> + responses-per-second <em class="replaceable"><code>integer</code></em>;<br> + slip <em class="replaceable"><code>integer</code></em>;<br> + window <em class="replaceable"><code>integer</code></em>;<br> + };<br> + recursing-file <em class="replaceable"><code>quoted_string</code></em>;<br> + recursion <em class="replaceable"><code>boolean</code></em>;<br> + recursive-clients <em class="replaceable"><code>integer</code></em>;<br> + request-expire <em class="replaceable"><code>boolean</code></em>;<br> + request-ixfr <em class="replaceable"><code>boolean</code></em>;<br> + request-nsid <em class="replaceable"><code>boolean</code></em>;<br> + require-server-cookie <em class="replaceable"><code>boolean</code></em>;<br> + reserved-sockets <em class="replaceable"><code>integer</code></em>;<br> + resolver-query-timeout <em class="replaceable"><code>integer</code></em>;<br> + response-policy { zone <em class="replaceable"><code>quoted_string</code></em> [ log <em class="replaceable"><code>boolean</code></em> ] [<br> + max-policy-ttl <em class="replaceable"><code>integer</code></em> ] [ policy ( cname | disabled | drop |<br> + given | no-op | nodata | nxdomain | passthru | tcp-only<br> + <em class="replaceable"><code>quoted_string</code></em> ) ] [ recursive-only <em class="replaceable"><code>boolean</code></em> ]; ... } [<br> + break-dnssec <em class="replaceable"><code>boolean</code></em> ] [ max-policy-ttl <em class="replaceable"><code>integer</code></em> ] [<br> + min-ns-dots <em class="replaceable"><code>integer</code></em> ] [ nsip-wait-recurse <em class="replaceable"><code>boolean</code></em> ] [<br> + qname-wait-recurse <em class="replaceable"><code>boolean</code></em> ] [ recursive-only <em class="replaceable"><code>boolean</code></em> ];<br> + root-delegation-only [ exclude { <em class="replaceable"><code>quoted_string</code></em>; ... } ];<br> + root-key-sentinel <em class="replaceable"><code>boolean</code></em>;<br> + rrset-order { [ class <em class="replaceable"><code>string</code></em> ] [ type <em class="replaceable"><code>string</code></em> ] [ name<br> + <em class="replaceable"><code>quoted_string</code></em> ] <em class="replaceable"><code>string</code></em> <em class="replaceable"><code>string</code></em>; ... };<br> + secroots-file <em class="replaceable"><code>quoted_string</code></em>;<br> + send-cookie <em class="replaceable"><code>boolean</code></em>;<br> + serial-query-rate <em class="replaceable"><code>integer</code></em>;<br> + serial-update-method ( date | increment | unixtime );<br> + server-id ( <em class="replaceable"><code>quoted_string</code></em> | none | hostname );<br> + servfail-ttl <em class="replaceable"><code>ttlval</code></em>;<br> + session-keyalg <em class="replaceable"><code>string</code></em>;<br> + session-keyfile ( <em class="replaceable"><code>quoted_string</code></em> | none );<br> + session-keyname <em class="replaceable"><code>string</code></em>;<br> + sig-signing-nodes <em class="replaceable"><code>integer</code></em>;<br> + sig-signing-signatures <em class="replaceable"><code>integer</code></em>;<br> + sig-signing-type <em class="replaceable"><code>integer</code></em>;<br> + sig-validity-interval <em class="replaceable"><code>integer</code></em> [ <em class="replaceable"><code>integer</code></em> ];<br> + sortlist { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + stacksize ( default | unlimited | <em class="replaceable"><code>sizeval</code></em> );<br> + startup-notify-rate <em class="replaceable"><code>integer</code></em>;<br> + statistics-file <em class="replaceable"><code>quoted_string</code></em>;<br> + tcp-clients <em class="replaceable"><code>integer</code></em>;<br> + tcp-listen-queue <em class="replaceable"><code>integer</code></em>;<br> + tkey-dhkey <em class="replaceable"><code>quoted_string</code></em> <em class="replaceable"><code>integer</code></em>;<br> + tkey-domain <em class="replaceable"><code>quoted_string</code></em>;<br> + tkey-gssapi-credential <em class="replaceable"><code>quoted_string</code></em>;<br> + tkey-gssapi-keytab <em class="replaceable"><code>quoted_string</code></em>;<br> + transfer-format ( many-answers | one-answer );<br> + transfer-message-size <em class="replaceable"><code>integer</code></em>;<br> + transfer-source ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [<br> + dscp <em class="replaceable"><code>integer</code></em> ];<br> + transfer-source-v6 ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * )<br> + ] [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + transfers-in <em class="replaceable"><code>integer</code></em>;<br> + transfers-out <em class="replaceable"><code>integer</code></em>;<br> + transfers-per-ns <em class="replaceable"><code>integer</code></em>;<br> + trust-anchor-telemetry <em class="replaceable"><code>boolean</code></em>; // experimental<br> + try-tcp-refresh <em class="replaceable"><code>boolean</code></em>;<br> + update-check-ksk <em class="replaceable"><code>boolean</code></em>;<br> + use-alt-transfer-source <em class="replaceable"><code>boolean</code></em>;<br> + use-v4-udp-ports { <em class="replaceable"><code>portrange</code></em>; ... };<br> + use-v6-udp-ports { <em class="replaceable"><code>portrange</code></em>; ... };<br> + v6-bias <em class="replaceable"><code>integer</code></em>;<br> + version ( <em class="replaceable"><code>quoted_string</code></em> | none );<br> + zero-no-soa-ttl <em class="replaceable"><code>boolean</code></em>;<br> + zero-no-soa-ttl-cache <em class="replaceable"><code>boolean</code></em>;<br> + zone-statistics ( full | terse | none | <em class="replaceable"><code>boolean</code></em> );<br> +};<br> +</p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.20.18"></a><h2>SERVER</h2> + + <div class="literallayout"><p><br> +server <em class="replaceable"><code>netprefix</code></em> {<br> + bogus <em class="replaceable"><code>boolean</code></em>;<br> + edns <em class="replaceable"><code>boolean</code></em>;<br> + edns-udp-size <em class="replaceable"><code>integer</code></em>;<br> + edns-version <em class="replaceable"><code>integer</code></em>;<br> + keys <em class="replaceable"><code>server_key</code></em>;<br> + max-udp-size <em class="replaceable"><code>integer</code></em>;<br> + notify-source ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [<br> + dscp <em class="replaceable"><code>integer</code></em> ];<br> + notify-source-v6 ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ]<br> + [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + provide-ixfr <em class="replaceable"><code>boolean</code></em>;<br> + query-source ( ( [ address ] ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port (<br> + <em class="replaceable"><code>integer</code></em> | * ) ] ) | ( [ [ address ] ( <em class="replaceable"><code>ipv4_address</code></em> | * ) ]<br> + port ( <em class="replaceable"><code>integer</code></em> | * ) ) ) [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + query-source-v6 ( ( [ address ] ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port (<br> + <em class="replaceable"><code>integer</code></em> | * ) ] ) | ( [ [ address ] ( <em class="replaceable"><code>ipv6_address</code></em> | * ) ]<br> + port ( <em class="replaceable"><code>integer</code></em> | * ) ) ) [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + request-expire <em class="replaceable"><code>boolean</code></em>;<br> + request-ixfr <em class="replaceable"><code>boolean</code></em>;<br> + request-nsid <em class="replaceable"><code>boolean</code></em>;<br> + send-cookie <em class="replaceable"><code>boolean</code></em>;<br> + tcp-only <em class="replaceable"><code>boolean</code></em>;<br> + transfer-format ( many-answers | one-answer );<br> + transfer-source ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [<br> + dscp <em class="replaceable"><code>integer</code></em> ];<br> + transfer-source-v6 ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * )<br> + ] [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + transfers <em class="replaceable"><code>integer</code></em>;<br> +};<br> +</p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.20.19"></a><h2>STATISTICS-CHANNELS</h2> + + <div class="literallayout"><p><br> +statistics-channels {<br> + inet ( <em class="replaceable"><code>ipv4_address</code></em> | <em class="replaceable"><code>ipv6_address</code></em> |<br> + * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [<br> + allow { <em class="replaceable"><code>address_match_element</code></em>; ...<br> + } ];<br> +};<br> +</p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.20.20"></a><h2>TRUSTED-KEYS</h2> + + <div class="literallayout"><p><br> +trusted-keys { <em class="replaceable"><code>string</code></em> <em class="replaceable"><code>integer</code></em> <em class="replaceable"><code>integer</code></em><br> + <em class="replaceable"><code>integer</code></em> <em class="replaceable"><code>quoted_string</code></em>; ... };<br> +</p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.20.21"></a><h2>VIEW</h2> + + <div class="literallayout"><p><br> +view <em class="replaceable"><code>string</code></em> [ <em class="replaceable"><code>class</code></em> ] {<br> + acache-cleaning-interval <em class="replaceable"><code>integer</code></em>;<br> + acache-enable <em class="replaceable"><code>boolean</code></em>;<br> + additional-from-auth <em class="replaceable"><code>boolean</code></em>;<br> + additional-from-cache <em class="replaceable"><code>boolean</code></em>;<br> + allow-new-zones <em class="replaceable"><code>boolean</code></em>;<br> + allow-notify { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-query { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-query-cache { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-query-cache-on { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-query-on { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-recursion { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-recursion-on { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-transfer { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-update { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-update-forwarding { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + also-notify [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>masters</code></em> |<br> + <em class="replaceable"><code>ipv4_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port<br> + <em class="replaceable"><code>integer</code></em> ] ) [ key <em class="replaceable"><code>string</code></em> ]; ... };<br> + alt-transfer-source ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * )<br> + ] [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + alt-transfer-source-v6 ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> |<br> + * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + attach-cache <em class="replaceable"><code>string</code></em>;<br> + auth-nxdomain <em class="replaceable"><code>boolean</code></em>; // default changed<br> + auto-dnssec ( allow | maintain | off );<br> + cache-file <em class="replaceable"><code>quoted_string</code></em>;<br> + catalog-zones { zone <em class="replaceable"><code>quoted_string</code></em> [ default-masters [ port<br> + <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>masters</code></em> | <em class="replaceable"><code>ipv4_address</code></em> [<br> + port <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] ) [ key<br> + <em class="replaceable"><code>string</code></em> ]; ... } ] [ zone-directory <em class="replaceable"><code>quoted_string</code></em> ] [<br> + in-memory <em class="replaceable"><code>boolean</code></em> ] [ min-update-interval <em class="replaceable"><code>integer</code></em> ]; ... };<br> + check-dup-records ( fail | warn | ignore );<br> + check-integrity <em class="replaceable"><code>boolean</code></em>;<br> + check-mx ( fail | warn | ignore );<br> + check-mx-cname ( fail | warn | ignore );<br> + check-names ( master | slave | response<br> + ) ( fail | warn | ignore );<br> + check-sibling <em class="replaceable"><code>boolean</code></em>;<br> + check-spf ( warn | ignore );<br> + check-srv-cname ( fail | warn | ignore );<br> + check-wildcard <em class="replaceable"><code>boolean</code></em>;<br> + cleaning-interval <em class="replaceable"><code>integer</code></em>;<br> + clients-per-query <em class="replaceable"><code>integer</code></em>;<br> + deny-answer-addresses { <em class="replaceable"><code>address_match_element</code></em>; ... } [<br> + except-from { <em class="replaceable"><code>quoted_string</code></em>; ... } ];<br> + deny-answer-aliases { <em class="replaceable"><code>quoted_string</code></em>; ... } [ except-from {<br> + <em class="replaceable"><code>quoted_string</code></em>; ... } ];<br> + dialup ( notify | notify-passive | passive | refresh | <em class="replaceable"><code>boolean</code></em> );<br> + disable-algorithms <em class="replaceable"><code>string</code></em> { <em class="replaceable"><code>string</code></em>;<br> + ... };<br> + disable-ds-digests <em class="replaceable"><code>string</code></em> { <em class="replaceable"><code>string</code></em>;<br> + ... };<br> + disable-empty-zone <em class="replaceable"><code>string</code></em>;<br> + dlz <em class="replaceable"><code>string</code></em> {<br> + database <em class="replaceable"><code>string</code></em>;<br> + search <em class="replaceable"><code>boolean</code></em>;<br> + };<br> + dns64 <em class="replaceable"><code>netprefix</code></em> {<br> + break-dnssec <em class="replaceable"><code>boolean</code></em>;<br> + clients { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + exclude { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + mapped { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + recursive-only <em class="replaceable"><code>boolean</code></em>;<br> + suffix <em class="replaceable"><code>ipv6_address</code></em>;<br> + };<br> + dns64-contact <em class="replaceable"><code>string</code></em>;<br> + dns64-server <em class="replaceable"><code>string</code></em>;<br> + dnssec-accept-expired <em class="replaceable"><code>boolean</code></em>;<br> + dnssec-dnskey-kskonly <em class="replaceable"><code>boolean</code></em>;<br> + dnssec-enable <em class="replaceable"><code>boolean</code></em>;<br> + dnssec-loadkeys-interval <em class="replaceable"><code>integer</code></em>;<br> + dnssec-lookaside ( <em class="replaceable"><code>string</code></em> trust-anchor<br> + <em class="replaceable"><code>string</code></em> | auto | no );<br> + dnssec-must-be-secure <em class="replaceable"><code>string</code></em> <em class="replaceable"><code>boolean</code></em>;<br> + dnssec-secure-to-insecure <em class="replaceable"><code>boolean</code></em>;<br> + dnssec-update-mode ( maintain | no-resign );<br> + dnssec-validation ( yes | no | auto );<br> + dnstap { ( all | auth | client | forwarder |<br> + resolver ) [ ( query | response ) ]; ... };<br> + dual-stack-servers [ port <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>quoted_string</code></em> [ port<br> + <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv4_address</code></em> [ port<br> + <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port<br> + <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] ); ... };<br> + dyndb <em class="replaceable"><code>string</code></em> <em class="replaceable"><code>quoted_string</code></em> {<br> + <em class="replaceable"><code>unspecified-text</code></em> };<br> + edns-udp-size <em class="replaceable"><code>integer</code></em>;<br> + empty-contact <em class="replaceable"><code>string</code></em>;<br> + empty-server <em class="replaceable"><code>string</code></em>;<br> + empty-zones-enable <em class="replaceable"><code>boolean</code></em>;<br> + fetch-quota-params <em class="replaceable"><code>integer</code></em> <em class="replaceable"><code>fixedpoint</code></em> <em class="replaceable"><code>fixedpoint</code></em> <em class="replaceable"><code>fixedpoint</code></em>;<br> + fetches-per-server <em class="replaceable"><code>integer</code></em> [ ( drop | fail ) ];<br> + fetches-per-zone <em class="replaceable"><code>integer</code></em> [ ( drop | fail ) ];<br> + filter-aaaa { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + filter-aaaa-on-v4 ( break-dnssec | <em class="replaceable"><code>boolean</code></em> );<br> + filter-aaaa-on-v6 ( break-dnssec | <em class="replaceable"><code>boolean</code></em> );<br> + forward ( first | only );<br> + forwarders [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>ipv4_address</code></em><br> + | <em class="replaceable"><code>ipv6_address</code></em> ) [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ]; ... };<br> + inline-signing <em class="replaceable"><code>boolean</code></em>;<br> + ixfr-from-differences ( master | slave | <em class="replaceable"><code>boolean</code></em> );<br> + key <em class="replaceable"><code>string</code></em> {<br> + algorithm <em class="replaceable"><code>string</code></em>;<br> + secret <em class="replaceable"><code>string</code></em>;<br> + };<br> + key-directory <em class="replaceable"><code>quoted_string</code></em>;<br> + lame-ttl <em class="replaceable"><code>ttlval</code></em>;<br> + lmdb-mapsize <em class="replaceable"><code>sizeval</code></em>;<br> + managed-keys { <em class="replaceable"><code>string</code></em> <em class="replaceable"><code>string</code></em><br> + <em class="replaceable"><code>integer</code></em> <em class="replaceable"><code>integer</code></em> <em class="replaceable"><code>integer</code></em><br> + <em class="replaceable"><code>quoted_string</code></em>; ... };<br> + masterfile-format ( map | raw | text );<br> + masterfile-style ( full | relative );<br> + match-clients { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + match-destinations { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + match-recursive-only <em class="replaceable"><code>boolean</code></em>;<br> + max-acache-size ( unlimited | <em class="replaceable"><code>sizeval</code></em> );<br> + max-cache-size ( default | unlimited | <em class="replaceable"><code>sizeval</code></em> | <em class="replaceable"><code>percentage</code></em> );<br> + max-cache-ttl <em class="replaceable"><code>integer</code></em>;<br> + max-clients-per-query <em class="replaceable"><code>integer</code></em>;<br> + max-journal-size ( unlimited | <em class="replaceable"><code>sizeval</code></em> );<br> + max-ncache-ttl <em class="replaceable"><code>integer</code></em>;<br> + max-records <em class="replaceable"><code>integer</code></em>;<br> + max-recursion-depth <em class="replaceable"><code>integer</code></em>;<br> + max-recursion-queries <em class="replaceable"><code>integer</code></em>;<br> + max-refresh-time <em class="replaceable"><code>integer</code></em>;<br> + max-retry-time <em class="replaceable"><code>integer</code></em>;<br> + max-transfer-idle-in <em class="replaceable"><code>integer</code></em>;<br> + max-transfer-idle-out <em class="replaceable"><code>integer</code></em>;<br> + max-transfer-time-in <em class="replaceable"><code>integer</code></em>;<br> + max-transfer-time-out <em class="replaceable"><code>integer</code></em>;<br> + max-udp-size <em class="replaceable"><code>integer</code></em>;<br> + max-zone-ttl ( unlimited | <em class="replaceable"><code>ttlval</code></em> );<br> + message-compression <em class="replaceable"><code>boolean</code></em>;<br> + min-refresh-time <em class="replaceable"><code>integer</code></em>;<br> + min-retry-time <em class="replaceable"><code>integer</code></em>;<br> + minimal-any <em class="replaceable"><code>boolean</code></em>;<br> + minimal-responses ( no-auth | no-auth-recursive | <em class="replaceable"><code>boolean</code></em> );<br> + multi-master <em class="replaceable"><code>boolean</code></em>;<br> + no-case-compress { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + nocookie-udp-size <em class="replaceable"><code>integer</code></em>;<br> + notify ( explicit | master-only | <em class="replaceable"><code>boolean</code></em> );<br> + notify-delay <em class="replaceable"><code>integer</code></em>;<br> + notify-source ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [<br> + dscp <em class="replaceable"><code>integer</code></em> ];<br> + notify-source-v6 ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ]<br> + [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + notify-to-soa <em class="replaceable"><code>boolean</code></em>;<br> + nta-lifetime <em class="replaceable"><code>ttlval</code></em>;<br> + nta-recheck <em class="replaceable"><code>ttlval</code></em>;<br> + nxdomain-redirect <em class="replaceable"><code>string</code></em>;<br> + preferred-glue <em class="replaceable"><code>string</code></em>;<br> + prefetch <em class="replaceable"><code>integer</code></em> [ <em class="replaceable"><code>integer</code></em> ];<br> + provide-ixfr <em class="replaceable"><code>boolean</code></em>;<br> + query-source ( ( [ address ] ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port (<br> + <em class="replaceable"><code>integer</code></em> | * ) ] ) | ( [ [ address ] ( <em class="replaceable"><code>ipv4_address</code></em> | * ) ]<br> + port ( <em class="replaceable"><code>integer</code></em> | * ) ) ) [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + query-source-v6 ( ( [ address ] ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port (<br> + <em class="replaceable"><code>integer</code></em> | * ) ] ) | ( [ [ address ] ( <em class="replaceable"><code>ipv6_address</code></em> | * ) ]<br> + port ( <em class="replaceable"><code>integer</code></em> | * ) ) ) [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + rate-limit {<br> + all-per-second <em class="replaceable"><code>integer</code></em>;<br> + errors-per-second <em class="replaceable"><code>integer</code></em>;<br> + exempt-clients { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + ipv4-prefix-length <em class="replaceable"><code>integer</code></em>;<br> + ipv6-prefix-length <em class="replaceable"><code>integer</code></em>;<br> + log-only <em class="replaceable"><code>boolean</code></em>;<br> + max-table-size <em class="replaceable"><code>integer</code></em>;<br> + min-table-size <em class="replaceable"><code>integer</code></em>;<br> + nodata-per-second <em class="replaceable"><code>integer</code></em>;<br> + nxdomains-per-second <em class="replaceable"><code>integer</code></em>;<br> + qps-scale <em class="replaceable"><code>integer</code></em>;<br> + referrals-per-second <em class="replaceable"><code>integer</code></em>;<br> + responses-per-second <em class="replaceable"><code>integer</code></em>;<br> + slip <em class="replaceable"><code>integer</code></em>;<br> + window <em class="replaceable"><code>integer</code></em>;<br> + };<br> + recursion <em class="replaceable"><code>boolean</code></em>;<br> + request-expire <em class="replaceable"><code>boolean</code></em>;<br> + request-ixfr <em class="replaceable"><code>boolean</code></em>;<br> + request-nsid <em class="replaceable"><code>boolean</code></em>;<br> + require-server-cookie <em class="replaceable"><code>boolean</code></em>;<br> + resolver-query-timeout <em class="replaceable"><code>integer</code></em>;<br> + response-policy { zone <em class="replaceable"><code>quoted_string</code></em> [ log <em class="replaceable"><code>boolean</code></em> ] [<br> + max-policy-ttl <em class="replaceable"><code>integer</code></em> ] [ policy ( cname | disabled | drop |<br> + given | no-op | nodata | nxdomain | passthru | tcp-only<br> + <em class="replaceable"><code>quoted_string</code></em> ) ] [ recursive-only <em class="replaceable"><code>boolean</code></em> ]; ... } [<br> + break-dnssec <em class="replaceable"><code>boolean</code></em> ] [ max-policy-ttl <em class="replaceable"><code>integer</code></em> ] [<br> + min-ns-dots <em class="replaceable"><code>integer</code></em> ] [ nsip-wait-recurse <em class="replaceable"><code>boolean</code></em> ] [<br> + qname-wait-recurse <em class="replaceable"><code>boolean</code></em> ] [ recursive-only <em class="replaceable"><code>boolean</code></em> ];<br> + root-delegation-only [ exclude { <em class="replaceable"><code>quoted_string</code></em>; ... } ];<br> + root-key-sentinel <em class="replaceable"><code>boolean</code></em>;<br> + rrset-order { [ class <em class="replaceable"><code>string</code></em> ] [ type <em class="replaceable"><code>string</code></em> ] [ name<br> + <em class="replaceable"><code>quoted_string</code></em> ] <em class="replaceable"><code>string</code></em> <em class="replaceable"><code>string</code></em>; ... };<br> + send-cookie <em class="replaceable"><code>boolean</code></em>;<br> + serial-update-method ( date | increment | unixtime );<br> + server <em class="replaceable"><code>netprefix</code></em> {<br> + bogus <em class="replaceable"><code>boolean</code></em>;<br> + edns <em class="replaceable"><code>boolean</code></em>;<br> + edns-udp-size <em class="replaceable"><code>integer</code></em>;<br> + edns-version <em class="replaceable"><code>integer</code></em>;<br> + keys <em class="replaceable"><code>server_key</code></em>;<br> + max-udp-size <em class="replaceable"><code>integer</code></em>;<br> + notify-source ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | *<br> + ) ] [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + notify-source-v6 ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em><br> + | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + provide-ixfr <em class="replaceable"><code>boolean</code></em>;<br> + query-source ( ( [ address ] ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port<br> + ( <em class="replaceable"><code>integer</code></em> | * ) ] ) | ( [ [ address ] (<br> + <em class="replaceable"><code>ipv4_address</code></em> | * ) ] port ( <em class="replaceable"><code>integer</code></em> | * ) ) ) [<br> + dscp <em class="replaceable"><code>integer</code></em> ];<br> + query-source-v6 ( ( [ address ] ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [<br> + port ( <em class="replaceable"><code>integer</code></em> | * ) ] ) | ( [ [ address ] (<br> + <em class="replaceable"><code>ipv6_address</code></em> | * ) ] port ( <em class="replaceable"><code>integer</code></em> | * ) ) ) [<br> + dscp <em class="replaceable"><code>integer</code></em> ];<br> + request-expire <em class="replaceable"><code>boolean</code></em>;<br> + request-ixfr <em class="replaceable"><code>boolean</code></em>;<br> + request-nsid <em class="replaceable"><code>boolean</code></em>;<br> + send-cookie <em class="replaceable"><code>boolean</code></em>;<br> + tcp-only <em class="replaceable"><code>boolean</code></em>;<br> + transfer-format ( many-answers | one-answer );<br> + transfer-source ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> |<br> + * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + transfer-source-v6 ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port (<br> + <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + transfers <em class="replaceable"><code>integer</code></em>;<br> + };<br> + servfail-ttl <em class="replaceable"><code>ttlval</code></em>;<br> + sig-signing-nodes <em class="replaceable"><code>integer</code></em>;<br> + sig-signing-signatures <em class="replaceable"><code>integer</code></em>;<br> + sig-signing-type <em class="replaceable"><code>integer</code></em>;<br> + sig-validity-interval <em class="replaceable"><code>integer</code></em> [ <em class="replaceable"><code>integer</code></em> ];<br> + sortlist { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + transfer-format ( many-answers | one-answer );<br> + transfer-source ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [<br> + dscp <em class="replaceable"><code>integer</code></em> ];<br> + transfer-source-v6 ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * )<br> + ] [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + trust-anchor-telemetry <em class="replaceable"><code>boolean</code></em>; // experimental<br> + trusted-keys { <em class="replaceable"><code>string</code></em> <em class="replaceable"><code>integer</code></em><br> + <em class="replaceable"><code>integer</code></em> <em class="replaceable"><code>integer</code></em> <em class="replaceable"><code>quoted_string</code></em>;<br> + ... };<br> + try-tcp-refresh <em class="replaceable"><code>boolean</code></em>;<br> + update-check-ksk <em class="replaceable"><code>boolean</code></em>;<br> + use-alt-transfer-source <em class="replaceable"><code>boolean</code></em>;<br> + v6-bias <em class="replaceable"><code>integer</code></em>;<br> + zero-no-soa-ttl <em class="replaceable"><code>boolean</code></em>;<br> + zero-no-soa-ttl-cache <em class="replaceable"><code>boolean</code></em>;<br> + zone <em class="replaceable"><code>string</code></em> [ <em class="replaceable"><code>class</code></em> ] {<br> + allow-notify { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-query { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-query-on { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-transfer { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-update { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-update-forwarding { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + also-notify [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { (<br> + <em class="replaceable"><code>masters</code></em> | <em class="replaceable"><code>ipv4_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] |<br> + <em class="replaceable"><code>ipv6_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] ) [ key <em class="replaceable"><code>string</code></em> ];<br> + ... };<br> + alt-transfer-source ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port (<br> + <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + alt-transfer-source-v6 ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port (<br> + <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + auto-dnssec ( allow | maintain | off );<br> + check-dup-records ( fail | warn | ignore );<br> + check-integrity <em class="replaceable"><code>boolean</code></em>;<br> + check-mx ( fail | warn | ignore );<br> + check-mx-cname ( fail | warn | ignore );<br> + check-names ( fail | warn | ignore );<br> + check-sibling <em class="replaceable"><code>boolean</code></em>;<br> + check-spf ( warn | ignore );<br> + check-srv-cname ( fail | warn | ignore );<br> + check-wildcard <em class="replaceable"><code>boolean</code></em>;<br> + database <em class="replaceable"><code>string</code></em>;<br> + delegation-only <em class="replaceable"><code>boolean</code></em>;<br> + dialup ( notify | notify-passive | passive | refresh |<br> + <em class="replaceable"><code>boolean</code></em> );<br> + dlz <em class="replaceable"><code>string</code></em>;<br> + dnssec-dnskey-kskonly <em class="replaceable"><code>boolean</code></em>;<br> + dnssec-loadkeys-interval <em class="replaceable"><code>integer</code></em>;<br> + dnssec-secure-to-insecure <em class="replaceable"><code>boolean</code></em>;<br> + dnssec-update-mode ( maintain | no-resign );<br> + file <em class="replaceable"><code>quoted_string</code></em>;<br> + forward ( first | only );<br> + forwarders [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { (<br> + <em class="replaceable"><code>ipv4_address</code></em> | <em class="replaceable"><code>ipv6_address</code></em> ) [ port <em class="replaceable"><code>integer</code></em> ] [<br> + dscp <em class="replaceable"><code>integer</code></em> ]; ... };<br> + in-view <em class="replaceable"><code>string</code></em>;<br> + inline-signing <em class="replaceable"><code>boolean</code></em>;<br> + ixfr-from-differences <em class="replaceable"><code>boolean</code></em>;<br> + journal <em class="replaceable"><code>quoted_string</code></em>;<br> + key-directory <em class="replaceable"><code>quoted_string</code></em>;<br> + masterfile-format ( map | raw | text );<br> + masterfile-style ( full | relative );<br> + masters [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>masters</code></em><br> + | <em class="replaceable"><code>ipv4_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [<br> + port <em class="replaceable"><code>integer</code></em> ] ) [ key <em class="replaceable"><code>string</code></em> ]; ... };<br> + max-ixfr-log-size ( default | unlimited |<br> + max-journal-size ( unlimited | <em class="replaceable"><code>sizeval</code></em> );<br> + max-records <em class="replaceable"><code>integer</code></em>;<br> + max-refresh-time <em class="replaceable"><code>integer</code></em>;<br> + max-retry-time <em class="replaceable"><code>integer</code></em>;<br> + max-transfer-idle-in <em class="replaceable"><code>integer</code></em>;<br> + max-transfer-idle-out <em class="replaceable"><code>integer</code></em>;<br> + max-transfer-time-in <em class="replaceable"><code>integer</code></em>;<br> + max-transfer-time-out <em class="replaceable"><code>integer</code></em>;<br> + max-zone-ttl ( unlimited | <em class="replaceable"><code>ttlval</code></em> );<br> + min-refresh-time <em class="replaceable"><code>integer</code></em>;<br> + min-retry-time <em class="replaceable"><code>integer</code></em>;<br> + multi-master <em class="replaceable"><code>boolean</code></em>;<br> + notify ( explicit | master-only | <em class="replaceable"><code>boolean</code></em> );<br> + notify-delay <em class="replaceable"><code>integer</code></em>;<br> + notify-source ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | *<br> + ) ] [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + notify-source-v6 ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em><br> + | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + notify-to-soa <em class="replaceable"><code>boolean</code></em>;<br> + pubkey <em class="replaceable"><code>integer</code></em><br> + <em class="replaceable"><code>integer</code></em><br> + <em class="replaceable"><code>integer</code></em><br> + request-expire <em class="replaceable"><code>boolean</code></em>;<br> + request-ixfr <em class="replaceable"><code>boolean</code></em>;<br> + serial-update-method ( date | increment | unixtime );<br> + server-addresses { ( <em class="replaceable"><code>ipv4_address</code></em> | <em class="replaceable"><code>ipv6_address</code></em> ) [<br> + port <em class="replaceable"><code>integer</code></em> ]; ... };<br> + server-names { <em class="replaceable"><code>quoted_string</code></em>; ... };<br> + sig-signing-nodes <em class="replaceable"><code>integer</code></em>;<br> + sig-signing-signatures <em class="replaceable"><code>integer</code></em>;<br> + sig-signing-type <em class="replaceable"><code>integer</code></em>;<br> + sig-validity-interval <em class="replaceable"><code>integer</code></em> [ <em class="replaceable"><code>integer</code></em> ];<br> + transfer-source ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> |<br> + * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + transfer-source-v6 ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port (<br> + <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + try-tcp-refresh <em class="replaceable"><code>boolean</code></em>;<br> + type ( delegation-only | forward | hint | master | redirect<br> + | slave | static-stub | stub );<br> + update-check-ksk <em class="replaceable"><code>boolean</code></em>;<br> + update-policy ( local | { ( deny | grant ) <em class="replaceable"><code>string</code></em> (<br> + 6to4-self | external | krb5-self | krb5-selfsub |<br> + krb5-subdomain | ms-self | ms-selfsub | ms-subdomain |<br> + name | self | selfsub | selfwild | subdomain | tcp-self<br> + | wildcard | zonesub ) [ <em class="replaceable"><code>string</code></em> ] <em class="replaceable"><code>rrtypelist</code></em>; ... };<br> + use-alt-transfer-source <em class="replaceable"><code>boolean</code></em>;<br> + zero-no-soa-ttl <em class="replaceable"><code>boolean</code></em>;<br> + zone-statistics ( full | terse | none | <em class="replaceable"><code>boolean</code></em> );<br> + };<br> + zone-statistics ( full | terse | none | <em class="replaceable"><code>boolean</code></em> );<br> +};<br> +</p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.20.22"></a><h2>ZONE</h2> + + <div class="literallayout"><p><br> +zone <em class="replaceable"><code>string</code></em> [ <em class="replaceable"><code>class</code></em> ] {<br> + allow-notify { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-query { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-query-on { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-transfer { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-update { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + allow-update-forwarding { <em class="replaceable"><code>address_match_element</code></em>; ... };<br> + also-notify [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>masters</code></em> |<br> + <em class="replaceable"><code>ipv4_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port<br> + <em class="replaceable"><code>integer</code></em> ] ) [ key <em class="replaceable"><code>string</code></em> ]; ... };<br> + alt-transfer-source ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * )<br> + ] [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + alt-transfer-source-v6 ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> |<br> + * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + auto-dnssec ( allow | maintain | off );<br> + check-dup-records ( fail | warn | ignore );<br> + check-integrity <em class="replaceable"><code>boolean</code></em>;<br> + check-mx ( fail | warn | ignore );<br> + check-mx-cname ( fail | warn | ignore );<br> + check-names ( fail | warn | ignore );<br> + check-sibling <em class="replaceable"><code>boolean</code></em>;<br> + check-spf ( warn | ignore );<br> + check-srv-cname ( fail | warn | ignore );<br> + check-wildcard <em class="replaceable"><code>boolean</code></em>;<br> + database <em class="replaceable"><code>string</code></em>;<br> + delegation-only <em class="replaceable"><code>boolean</code></em>;<br> + dialup ( notify | notify-passive | passive | refresh | <em class="replaceable"><code>boolean</code></em> );<br> + dlz <em class="replaceable"><code>string</code></em>;<br> + dnssec-dnskey-kskonly <em class="replaceable"><code>boolean</code></em>;<br> + dnssec-loadkeys-interval <em class="replaceable"><code>integer</code></em>;<br> + dnssec-secure-to-insecure <em class="replaceable"><code>boolean</code></em>;<br> + dnssec-update-mode ( maintain | no-resign );<br> + file <em class="replaceable"><code>quoted_string</code></em>;<br> + forward ( first | only );<br> + forwarders [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>ipv4_address</code></em><br> + | <em class="replaceable"><code>ipv6_address</code></em> ) [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ]; ... };<br> + in-view <em class="replaceable"><code>string</code></em>;<br> + inline-signing <em class="replaceable"><code>boolean</code></em>;<br> + ixfr-from-differences <em class="replaceable"><code>boolean</code></em>;<br> + journal <em class="replaceable"><code>quoted_string</code></em>;<br> + key-directory <em class="replaceable"><code>quoted_string</code></em>;<br> + masterfile-format ( map | raw | text );<br> + masterfile-style ( full | relative );<br> + masters [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>masters</code></em> |<br> + <em class="replaceable"><code>ipv4_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port<br> + <em class="replaceable"><code>integer</code></em> ] ) [ key <em class="replaceable"><code>string</code></em> ]; ... };<br> + max-journal-size ( unlimited | <em class="replaceable"><code>sizeval</code></em> );<br> + max-records <em class="replaceable"><code>integer</code></em>;<br> + max-refresh-time <em class="replaceable"><code>integer</code></em>;<br> + max-retry-time <em class="replaceable"><code>integer</code></em>;<br> + max-transfer-idle-in <em class="replaceable"><code>integer</code></em>;<br> + max-transfer-idle-out <em class="replaceable"><code>integer</code></em>;<br> + max-transfer-time-in <em class="replaceable"><code>integer</code></em>;<br> + max-transfer-time-out <em class="replaceable"><code>integer</code></em>;<br> + max-zone-ttl ( unlimited | <em class="replaceable"><code>ttlval</code></em> );<br> + min-refresh-time <em class="replaceable"><code>integer</code></em>;<br> + min-retry-time <em class="replaceable"><code>integer</code></em>;<br> + multi-master <em class="replaceable"><code>boolean</code></em>;<br> + notify ( explicit | master-only | <em class="replaceable"><code>boolean</code></em> );<br> + notify-delay <em class="replaceable"><code>integer</code></em>;<br> + notify-source ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [<br> + dscp <em class="replaceable"><code>integer</code></em> ];<br> + notify-source-v6 ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ]<br> + [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + notify-to-soa <em class="replaceable"><code>boolean</code></em>;<br> + pubkey <em class="replaceable"><code>integer</code></em> <em class="replaceable"><code>integer</code></em><br> + request-expire <em class="replaceable"><code>boolean</code></em>;<br> + request-ixfr <em class="replaceable"><code>boolean</code></em>;<br> + serial-update-method ( date | increment | unixtime );<br> + server-addresses { ( <em class="replaceable"><code>ipv4_address</code></em> | <em class="replaceable"><code>ipv6_address</code></em> ) [ port<br> + <em class="replaceable"><code>integer</code></em> ]; ... };<br> + server-names { <em class="replaceable"><code>quoted_string</code></em>; ... };<br> + sig-signing-nodes <em class="replaceable"><code>integer</code></em>;<br> + sig-signing-signatures <em class="replaceable"><code>integer</code></em>;<br> + sig-signing-type <em class="replaceable"><code>integer</code></em>;<br> + sig-validity-interval <em class="replaceable"><code>integer</code></em> [ <em class="replaceable"><code>integer</code></em> ];<br> + transfer-source ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [<br> + dscp <em class="replaceable"><code>integer</code></em> ];<br> + transfer-source-v6 ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * )<br> + ] [ dscp <em class="replaceable"><code>integer</code></em> ];<br> + try-tcp-refresh <em class="replaceable"><code>boolean</code></em>;<br> + type ( delegation-only | forward | hint | master | redirect | slave<br> + | static-stub | stub );<br> + update-check-ksk <em class="replaceable"><code>boolean</code></em>;<br> + update-policy ( local | { ( deny | grant ) <em class="replaceable"><code>string</code></em> ( 6to4-self |<br> + external | krb5-self | krb5-selfsub | krb5-subdomain | ms-self<br> + | ms-selfsub | ms-subdomain | name | self | selfsub | selfwild<br> + | subdomain | tcp-self | wildcard | zonesub ) [ <em class="replaceable"><code>string</code></em> ]<br> + <em class="replaceable"><code>rrtypelist</code></em>; ... };<br> + use-alt-transfer-source <em class="replaceable"><code>boolean</code></em>;<br> + zero-no-soa-ttl <em class="replaceable"><code>boolean</code></em>;<br> + zone-statistics ( full | terse | none | <em class="replaceable"><code>boolean</code></em> );<br> +};<br> +</p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.20.23"></a><h2>FILES</h2> + + <p><code class="filename">/etc/named.conf</code> + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.20.24"></a><h2>SEE ALSO</h2> + + <p><span class="citerefentry"> + <span class="refentrytitle">ddns-confgen</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">named</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">named-checkconf</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">rndc</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">rndc-confgen</span>(8) + </span>, + <em class="citetitle">BIND 9 Administrator Reference Manual</em>. + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.named.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.named-checkconf.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">named</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">named-checkconf</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.named.html b/doc/arm/man.named.html new file mode 100644 index 0000000..c257eaf --- /dev/null +++ b/doc/arm/man.named.html @@ -0,0 +1,495 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>named</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.lwresd.html" title="lwresd"> +<link rel="next" href="man.named.conf.html" title="named.conf"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">named</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.lwresd.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.named.conf.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.named"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">named</span> + — Internet domain name server + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">named</code> + [ + [<code class="option">-4</code>] + | [<code class="option">-6</code>] + ] + [<code class="option">-c <em class="replaceable"><code>config-file</code></em></code>] + [<code class="option">-d <em class="replaceable"><code>debug-level</code></em></code>] + [<code class="option">-D <em class="replaceable"><code>string</code></em></code>] + [<code class="option">-E <em class="replaceable"><code>engine-name</code></em></code>] + [<code class="option">-f</code>] + [<code class="option">-g</code>] + [<code class="option">-L <em class="replaceable"><code>logfile</code></em></code>] + [<code class="option">-M <em class="replaceable"><code>option</code></em></code>] + [<code class="option">-m <em class="replaceable"><code>flag</code></em></code>] + [<code class="option">-n <em class="replaceable"><code>#cpus</code></em></code>] + [<code class="option">-p <em class="replaceable"><code>port</code></em></code>] + [<code class="option">-s</code>] + [<code class="option">-S <em class="replaceable"><code>#max-socks</code></em></code>] + [<code class="option">-t <em class="replaceable"><code>directory</code></em></code>] + [<code class="option">-U <em class="replaceable"><code>#listeners</code></em></code>] + [<code class="option">-u <em class="replaceable"><code>user</code></em></code>] + [<code class="option">-v</code>] + [<code class="option">-V</code>] + [<code class="option">-X <em class="replaceable"><code>lock-file</code></em></code>] + [<code class="option">-x <em class="replaceable"><code>cache-file</code></em></code>] + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.19.7"></a><h2>DESCRIPTION</h2> + + <p><span class="command"><strong>named</strong></span> + is a Domain Name System (DNS) server, + part of the BIND 9 distribution from ISC. For more + information on the DNS, see RFCs 1033, 1034, and 1035. + </p> + <p> + When invoked without arguments, <span class="command"><strong>named</strong></span> + will + read the default configuration file + <code class="filename">/etc/named.conf</code>, read any initial + data, and listen for queries. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.19.8"></a><h2>OPTIONS</h2> + + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-4</span></dt> +<dd> + <p> + Use IPv4 only even if the host machine is capable of IPv6. + <code class="option">-4</code> and <code class="option">-6</code> are mutually + exclusive. + </p> + </dd> +<dt><span class="term">-6</span></dt> +<dd> + <p> + Use IPv6 only even if the host machine is capable of IPv4. + <code class="option">-4</code> and <code class="option">-6</code> are mutually + exclusive. + </p> + </dd> +<dt><span class="term">-c <em class="replaceable"><code>config-file</code></em></span></dt> +<dd> + <p> + Use <em class="replaceable"><code>config-file</code></em> as the + configuration file instead of the default, + <code class="filename">/etc/named.conf</code>. To + ensure that reloading the configuration file continues + to work after the server has changed its working + directory due to to a possible + <code class="option">directory</code> option in the configuration + file, <em class="replaceable"><code>config-file</code></em> should be + an absolute pathname. + </p> + </dd> +<dt><span class="term">-d <em class="replaceable"><code>debug-level</code></em></span></dt> +<dd> + <p> + Set the daemon's debug level to <em class="replaceable"><code>debug-level</code></em>. + Debugging traces from <span class="command"><strong>named</strong></span> become + more verbose as the debug level increases. + </p> + </dd> +<dt><span class="term">-D <em class="replaceable"><code>string</code></em></span></dt> +<dd> + <p> + Specifies a string that is used to identify a instance of + <span class="command"><strong>named</strong></span> in a process listing. The contents + of <em class="replaceable"><code>string</code></em> are + not examined. + </p> + </dd> +<dt><span class="term">-E <em class="replaceable"><code>engine-name</code></em></span></dt> +<dd> + <p> + When applicable, specifies the hardware to use for + cryptographic operations, such as a secure key store used + for signing. + </p> + <p> + When BIND is built with OpenSSL PKCS#11 support, this defaults + to the string "pkcs11", which identifies an OpenSSL engine + that can drive a cryptographic accelerator or hardware service + module. When BIND is built with native PKCS#11 cryptography + (--enable-native-pkcs11), it defaults to the path of the PKCS#11 + provider library specified via "--with-pkcs11". + </p> + </dd> +<dt><span class="term">-f</span></dt> +<dd> + <p> + Run the server in the foreground (i.e. do not daemonize). + </p> + </dd> +<dt><span class="term">-g</span></dt> +<dd> + <p> + Run the server in the foreground and force all logging + to <code class="filename">stderr</code>. + </p> + </dd> +<dt><span class="term">-L <em class="replaceable"><code>logfile</code></em></span></dt> +<dd> + <p> + Log to the file <code class="option">logfile</code> by default + instead of the system log. + </p> + </dd> +<dt><span class="term">-M <em class="replaceable"><code>option</code></em></span></dt> +<dd> + <p> + Sets the default memory context options. Currently + the only supported option is + <em class="replaceable"><code>external</code></em>, + which causes the internal memory manager to be bypassed + in favor of system-provided memory allocation functions. + </p> + </dd> +<dt><span class="term">-m <em class="replaceable"><code>flag</code></em></span></dt> +<dd> + <p> + Turn on memory usage debugging flags. Possible flags are + <em class="replaceable"><code>usage</code></em>, + <em class="replaceable"><code>trace</code></em>, + <em class="replaceable"><code>record</code></em>, + <em class="replaceable"><code>size</code></em>, and + <em class="replaceable"><code>mctx</code></em>. + These correspond to the ISC_MEM_DEBUGXXXX flags described in + <code class="filename"><isc/mem.h></code>. + </p> + </dd> +<dt><span class="term">-n <em class="replaceable"><code>#cpus</code></em></span></dt> +<dd> + <p> + Create <em class="replaceable"><code>#cpus</code></em> worker threads + to take advantage of multiple CPUs. If not specified, + <span class="command"><strong>named</strong></span> will try to determine the + number of CPUs present and create one thread per CPU. + If it is unable to determine the number of CPUs, a + single worker thread will be created. + </p> + </dd> +<dt><span class="term">-p <em class="replaceable"><code>port</code></em></span></dt> +<dd> + <p> + Listen for queries on port <em class="replaceable"><code>port</code></em>. If not + specified, the default is port 53. + </p> + </dd> +<dt><span class="term">-s</span></dt> +<dd> + <p> + Write memory usage statistics to <code class="filename">stdout</code> on exit. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + This option is mainly of interest to BIND 9 developers + and may be removed or changed in a future release. + </p> + </div> + </dd> +<dt><span class="term">-S <em class="replaceable"><code>#max-socks</code></em></span></dt> +<dd> + <p> + Allow <span class="command"><strong>named</strong></span> to use up to + <em class="replaceable"><code>#max-socks</code></em> sockets. + The default value is 4096 on systems built with default + configuration options, and 21000 on systems built with + "configure --with-tuning=large". + </p> + <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Warning</h3> + <p> + This option should be unnecessary for the vast majority + of users. + The use of this option could even be harmful because the + specified value may exceed the limitation of the + underlying system API. + It is therefore set only when the default configuration + causes exhaustion of file descriptors and the + operational environment is known to support the + specified number of sockets. + Note also that the actual maximum number is normally a little + fewer than the specified value because + <span class="command"><strong>named</strong></span> reserves some file descriptors + for its internal use. + </p> + </div> + </dd> +<dt><span class="term">-t <em class="replaceable"><code>directory</code></em></span></dt> +<dd> + <p>Chroot + to <em class="replaceable"><code>directory</code></em> after + processing the command line arguments, but before + reading the configuration file. + </p> + <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Warning</h3> + <p> + This option should be used in conjunction with the + <code class="option">-u</code> option, as chrooting a process + running as root doesn't enhance security on most + systems; the way <code class="function">chroot(2)</code> is + defined allows a process with root privileges to + escape a chroot jail. + </p> + </div> + </dd> +<dt><span class="term">-U <em class="replaceable"><code>#listeners</code></em></span></dt> +<dd> + <p> + Use <em class="replaceable"><code>#listeners</code></em> + worker threads to listen for incoming UDP packets on each + address. If not specified, <span class="command"><strong>named</strong></span> will + calculate a default value based on the number of detected + CPUs: 1 for 1 CPU, and the number of detected CPUs + minus one for machines with more than 1 CPU. This cannot + be increased to a value higher than the number of CPUs. + If <code class="option">-n</code> has been set to a higher value than + the number of detected CPUs, then <code class="option">-U</code> may + be increased as high as that value, but no higher. + On Windows, the number of UDP listeners is hardwired to 1 + and this option has no effect. + </p> + </dd> +<dt><span class="term">-u <em class="replaceable"><code>user</code></em></span></dt> +<dd> + <p>Setuid + to <em class="replaceable"><code>user</code></em> after completing + privileged operations, such as creating sockets that + listen on privileged ports. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + On Linux, <span class="command"><strong>named</strong></span> uses the kernel's + capability mechanism to drop all root privileges + except the ability to <code class="function">bind(2)</code> to + a + privileged port and set process resource limits. + Unfortunately, this means that the <code class="option">-u</code> + option only works when <span class="command"><strong>named</strong></span> is + run + on kernel 2.2.18 or later, or kernel 2.3.99-pre3 or + later, since previous kernels did not allow privileges + to be retained after <code class="function">setuid(2)</code>. + </p> + </div> + </dd> +<dt><span class="term">-v</span></dt> +<dd> + <p> + Report the version number and exit. + </p> + </dd> +<dt><span class="term">-V</span></dt> +<dd> + <p> + Report the version number and build options, and exit. + </p> + </dd> +<dt><span class="term">-X <em class="replaceable"><code>lock-file</code></em></span></dt> +<dd> + <p> + Acquire a lock on the specified file at runtime; this + helps to prevent duplicate <span class="command"><strong>named</strong></span> instances + from running simultaneously. + Use of this option overrides the <span class="command"><strong>lock-file</strong></span> + option in <code class="filename">named.conf</code>. + If set to <code class="literal">none</code>, the lock file check + is disabled. + </p> + </dd> +<dt><span class="term">-x <em class="replaceable"><code>cache-file</code></em></span></dt> +<dd> + <p> + Load data from <em class="replaceable"><code>cache-file</code></em> into the + cache of the default view. + </p> + <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Warning</h3> + <p> + This option must not be used. It is only of interest + to BIND 9 developers and may be removed or changed in a + future release. + </p> + </div> + </dd> +</dl></div> + + </div> + + <div class="refsection"> +<a name="id-1.14.19.9"></a><h2>SIGNALS</h2> + + <p> + In routine operation, signals should not be used to control + the nameserver; <span class="command"><strong>rndc</strong></span> should be used + instead. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">SIGHUP</span></dt> +<dd> + <p> + Force a reload of the server. + </p> + </dd> +<dt><span class="term">SIGINT, SIGTERM</span></dt> +<dd> + <p> + Shut down the server. + </p> + </dd> +</dl></div> + + <p> + The result of sending any other signals to the server is undefined. + </p> + + </div> + + <div class="refsection"> +<a name="id-1.14.19.10"></a><h2>CONFIGURATION</h2> + + <p> + The <span class="command"><strong>named</strong></span> configuration file is too complex + to describe in detail here. A complete description is provided + in the + <em class="citetitle">BIND 9 Administrator Reference Manual</em>. + </p> + + <p> + <span class="command"><strong>named</strong></span> inherits the <code class="function">umask</code> + (file creation mode mask) from the parent process. If files + created by <span class="command"><strong>named</strong></span>, such as journal files, + need to have custom permissions, the <code class="function">umask</code> + should be set explicitly in the script used to start the + <span class="command"><strong>named</strong></span> process. + </p> + + </div> + + <div class="refsection"> +<a name="id-1.14.19.11"></a><h2>FILES</h2> + + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><code class="filename">/etc/named.conf</code></span></dt> +<dd> + <p> + The default configuration file. + </p> + </dd> +<dt><span class="term"><code class="filename">/var/run/named/named.pid</code></span></dt> +<dd> + <p> + The default process-id file. + </p> + </dd> +</dl></div> + + </div> + + <div class="refsection"> +<a name="id-1.14.19.12"></a><h2>SEE ALSO</h2> + + <p><em class="citetitle">RFC 1033</em>, + <em class="citetitle">RFC 1034</em>, + <em class="citetitle">RFC 1035</em>, + <span class="citerefentry"> + <span class="refentrytitle">named-checkconf</span> + (8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">named-checkzone</span> + (8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">rndc</span> + (8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">lwresd</span> + (8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">named.conf</span> + (5) + </span>, + <em class="citetitle">BIND 9 Administrator Reference Manual</em>. + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.lwresd.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.named.conf.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">lwresd</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <code class="filename">named.conf</code> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.nsec3hash.html b/doc/arm/man.nsec3hash.html new file mode 100644 index 0000000..37de2e8 --- /dev/null +++ b/doc/arm/man.nsec3hash.html @@ -0,0 +1,136 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>nsec3hash</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.isc-hmac-fixup.html" title="isc-hmac-fixup"> +<link rel="next" href="man.pkcs11-destroy.html" title="pkcs11-destroy"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">nsec3hash</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.isc-hmac-fixup.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.pkcs11-destroy.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.nsec3hash"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">nsec3hash</span> + — generate NSEC3 hash + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">nsec3hash</code> + {<em class="replaceable"><code>salt</code></em>} + {<em class="replaceable"><code>algorithm</code></em>} + {<em class="replaceable"><code>iterations</code></em>} + {<em class="replaceable"><code>domain</code></em>} + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.35.7"></a><h2>DESCRIPTION</h2> + + <p> + <span class="command"><strong>nsec3hash</strong></span> generates an NSEC3 hash based on + a set of NSEC3 parameters. This can be used to check the validity + of NSEC3 records in a signed zone. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.35.8"></a><h2>ARGUMENTS</h2> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">salt</span></dt> +<dd> + <p> + The salt provided to the hash algorithm. + </p> + </dd> +<dt><span class="term">algorithm</span></dt> +<dd> + <p> + A number indicating the hash algorithm. Currently the + only supported hash algorithm for NSEC3 is SHA-1, which is + indicated by the number 1; consequently "1" is the only + useful value for this argument. + </p> + </dd> +<dt><span class="term">iterations</span></dt> +<dd> + <p> + The number of additional times the hash should be performed. + </p> + </dd> +<dt><span class="term">domain</span></dt> +<dd> + <p> + The domain name to be hashed. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.35.9"></a><h2>SEE ALSO</h2> + + <p> + <em class="citetitle">BIND 9 Administrator Reference Manual</em>, + <em class="citetitle">RFC 5155</em>. + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.isc-hmac-fixup.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.pkcs11-destroy.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">isc-hmac-fixup</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">pkcs11-destroy</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.nslookup.html b/doc/arm/man.nslookup.html new file mode 100644 index 0000000..ba3fb3c --- /dev/null +++ b/doc/arm/man.nslookup.html @@ -0,0 +1,424 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>nslookup</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.delv.html" title="delv"> +<link rel="next" href="man.dnssec-checkds.html" title="dnssec-checkds"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center">nslookup</th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.delv.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.dnssec-checkds.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.nslookup"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + nslookup + — query Internet name servers interactively + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">nslookup</code> + [<code class="option">-option</code>] + [name | -] + [server] + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.6.7"></a><h2>DESCRIPTION</h2> + + <p><span class="command"><strong>Nslookup</strong></span> + is a program to query Internet domain name servers. <span class="command"><strong>Nslookup</strong></span> + has two modes: interactive and non-interactive. Interactive mode allows + the user to query name servers for information about various hosts and + domains or to print a list of hosts in a domain. Non-interactive mode + is + used to print just the name and requested information for a host or + domain. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.6.8"></a><h2>ARGUMENTS</h2> + + <p> + Interactive mode is entered in the following cases: + </p> +<div class="orderedlist"><ol class="orderedlist" type="a"> +<li class="listitem"> + <p> + when no arguments are given (the default name server will be used) + </p> + </li> +<li class="listitem"> + <p> + when the first argument is a hyphen (-) and the second argument is + the host name or Internet address of a name server. + </p> + </li> +</ol></div> +<p> + </p> + + <p> + Non-interactive mode is used when the name or Internet address of the + host to be looked up is given as the first argument. The optional second + argument specifies the host name or address of a name server. + </p> + + <p> + Options can also be specified on the command line if they precede the + arguments and are prefixed with a hyphen. For example, to + change the default query type to host information, and the initial + timeout to 10 seconds, type: + + </p> +<pre class="programlisting"> +nslookup -query=hinfo -timeout=10 +</pre> +<p> + + </p> + <p> + The <code class="option">-version</code> option causes + <span class="command"><strong>nslookup</strong></span> to print the version + number and immediately exits. + </p> + + </div> + + <div class="refsection"> +<a name="id-1.14.6.9"></a><h2>INTERACTIVE COMMANDS</h2> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><code class="constant">host</code> [<span class="optional">server</span>]</span></dt> +<dd> + <p> + Look up information for host using the current default server or + using server, if specified. If host is an Internet address and + the query type is A or PTR, the name of the host is returned. + If host is a name and does not have a trailing period, the + search list is used to qualify the name. + </p> + + <p> + To look up a host not in the current domain, append a period to + the name. + </p> + </dd> +<dt><span class="term"><code class="constant">server</code> <em class="replaceable"><code>domain</code></em></span></dt> +<dd> + <p></p> + </dd> +<dt><span class="term"><code class="constant">lserver</code> <em class="replaceable"><code>domain</code></em></span></dt> +<dd> + <p> + Change the default server to <em class="replaceable"><code>domain</code></em>; <code class="constant">lserver</code> uses the initial + server to look up information about <em class="replaceable"><code>domain</code></em>, while <code class="constant">server</code> uses + the current default server. If an authoritative answer can't be + found, the names of servers that might have the answer are + returned. + </p> + </dd> +<dt><span class="term"><code class="constant">root</code></span></dt> +<dd> + <p> + not implemented + </p> + </dd> +<dt><span class="term"><code class="constant">finger</code></span></dt> +<dd> + <p> + not implemented + </p> + </dd> +<dt><span class="term"><code class="constant">ls</code></span></dt> +<dd> + <p> + not implemented + </p> + </dd> +<dt><span class="term"><code class="constant">view</code></span></dt> +<dd> + <p> + not implemented + </p> + </dd> +<dt><span class="term"><code class="constant">help</code></span></dt> +<dd> + <p> + not implemented + </p> + </dd> +<dt><span class="term"><code class="constant">?</code></span></dt> +<dd> + <p> + not implemented + </p> + </dd> +<dt><span class="term"><code class="constant">exit</code></span></dt> +<dd> + <p> + Exits the program. + </p> + </dd> +<dt><span class="term"><code class="constant">set</code> + <em class="replaceable"><code>keyword[<span class="optional">=value</span>]</code></em></span></dt> +<dd> + <p> + This command is used to change state information that affects + the lookups. Valid keywords are: + </p> +<div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><code class="constant">all</code></span></dt> +<dd> + <p> + Prints the current values of the frequently used + options to <span class="command"><strong>set</strong></span>. + Information about the current default + server and host is also printed. + </p> + </dd> +<dt><span class="term"><code class="constant">class=</code><em class="replaceable"><code>value</code></em></span></dt> +<dd> + <p> + Change the query class to one of: + </p> +<div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><code class="constant">IN</code></span></dt> +<dd> + <p> + the Internet class + </p> + </dd> +<dt><span class="term"><code class="constant">CH</code></span></dt> +<dd> + <p> + the Chaos class + </p> + </dd> +<dt><span class="term"><code class="constant">HS</code></span></dt> +<dd> + <p> + the Hesiod class + </p> + </dd> +<dt><span class="term"><code class="constant">ANY</code></span></dt> +<dd> + <p> + wildcard + </p> + </dd> +</dl></div> +<p> + The class specifies the protocol group of the information. + + </p> + <p> + (Default = IN; abbreviation = cl) + </p> + </dd> +<dt><span class="term"><code class="constant"><em class="replaceable"><code>[<span class="optional">no</span>]</code></em>debug</code></span></dt> +<dd> + <p> + Turn on or off the display of the full response packet and + any intermediate response packets when searching. + </p> + <p> + (Default = nodebug; abbreviation = [<span class="optional">no</span>]deb) + </p> + </dd> +<dt><span class="term"><code class="constant"><em class="replaceable"><code>[<span class="optional">no</span>]</code></em>d2</code></span></dt> +<dd> + <p> + Turn debugging mode on or off. This displays more about + what nslookup is doing. + </p> + <p> + (Default = nod2) + </p> + </dd> +<dt><span class="term"><code class="constant">domain=</code><em class="replaceable"><code>name</code></em></span></dt> +<dd> + <p> + Sets the search list to <em class="replaceable"><code>name</code></em>. + </p> + </dd> +<dt><span class="term"><code class="constant"><em class="replaceable"><code>[<span class="optional">no</span>]</code></em>search</code></span></dt> +<dd> + <p> + If the lookup request contains at least one period but + doesn't end with a trailing period, append the domain + names in the domain search list to the request until an + answer is received. + </p> + <p> + (Default = search) + </p> + </dd> +<dt><span class="term"><code class="constant">port=</code><em class="replaceable"><code>value</code></em></span></dt> +<dd> + <p> + Change the default TCP/UDP name server port to <em class="replaceable"><code>value</code></em>. + </p> + <p> + (Default = 53; abbreviation = po) + </p> + </dd> +<dt><span class="term"><code class="constant">querytype=</code><em class="replaceable"><code>value</code></em></span></dt> +<dd> + <p></p> + </dd> +<dt><span class="term"><code class="constant">type=</code><em class="replaceable"><code>value</code></em></span></dt> +<dd> + <p> + Change the type of the information query. + </p> + <p> + (Default = A; abbreviations = q, ty) + </p> + </dd> +<dt><span class="term"><code class="constant"><em class="replaceable"><code>[<span class="optional">no</span>]</code></em>recurse</code></span></dt> +<dd> + <p> + Tell the name server to query other servers if it does not + have the + information. + </p> + <p> + (Default = recurse; abbreviation = [no]rec) + </p> + </dd> +<dt><span class="term"><code class="constant">ndots=</code><em class="replaceable"><code>number</code></em></span></dt> +<dd> + <p> + Set the number of dots (label separators) in a domain + that will disable searching. Absolute names always + stop searching. + </p> + </dd> +<dt><span class="term"><code class="constant">retry=</code><em class="replaceable"><code>number</code></em></span></dt> +<dd> + <p> + Set the number of retries to number. + </p> + </dd> +<dt><span class="term"><code class="constant">timeout=</code><em class="replaceable"><code>number</code></em></span></dt> +<dd> + <p> + Change the initial timeout interval for waiting for a + reply to number seconds. + </p> + </dd> +<dt><span class="term"><code class="constant"><em class="replaceable"><code>[<span class="optional">no</span>]</code></em>vc</code></span></dt> +<dd> + <p> + Always use a virtual circuit when sending requests to the + server. + </p> + <p> + (Default = novc) + </p> + </dd> +<dt><span class="term"><code class="constant"><em class="replaceable"><code>[<span class="optional">no</span>]</code></em>fail</code></span></dt> +<dd> + <p> + Try the next nameserver if a nameserver responds with + SERVFAIL or a referral (nofail) or terminate query + (fail) on such a response. + </p> + <p> + (Default = nofail) + </p> + </dd> +</dl></div> +<p> + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.6.10"></a><h2>RETURN VALUES</h2> + <p> + <span class="command"><strong>nslookup</strong></span> returns with an exit status of 1 + if any query failed, and 0 otherwise. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.6.11"></a><h2>FILES</h2> + + <p><code class="filename">/etc/resolv.conf</code> + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.6.12"></a><h2>SEE ALSO</h2> + + <p><span class="citerefentry"> + <span class="refentrytitle">dig</span>(1) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">host</span>(1) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">named</span>(8) + </span>. + </p> + </div> +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.delv.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.dnssec-checkds.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top">delv </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">dnssec-checkds</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.nsupdate.html b/doc/arm/man.nsupdate.html new file mode 100644 index 0000000..5fa2f2a --- /dev/null +++ b/doc/arm/man.nsupdate.html @@ -0,0 +1,822 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>nsupdate</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.named-rrchecker.html" title="named-rrchecker"> +<link rel="next" href="man.rndc.html" title="rndc"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">nsupdate</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.named-rrchecker.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.rndc.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.nsupdate"></a><div class="titlepage"></div> + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">nsupdate</span> + — Dynamic DNS update utility + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">nsupdate</code> + [<code class="option">-d</code>] + [<code class="option">-D</code>] + [<code class="option">-i</code>] + [<code class="option">-L <em class="replaceable"><code>level</code></em></code>] + [ + [<code class="option">-g</code>] + | [<code class="option">-o</code>] + | [<code class="option">-l</code>] + | [<code class="option">-y <em class="replaceable"><code>[<span class="optional">hmac:</span>]keyname:secret</code></em></code>] + | [<code class="option">-k <em class="replaceable"><code>keyfile</code></em></code>] + ] + [<code class="option">-t <em class="replaceable"><code>timeout</code></em></code>] + [<code class="option">-u <em class="replaceable"><code>udptimeout</code></em></code>] + [<code class="option">-r <em class="replaceable"><code>udpretries</code></em></code>] + [<code class="option">-R <em class="replaceable"><code>randomdev</code></em></code>] + [<code class="option">-v</code>] + [<code class="option">-T</code>] + [<code class="option">-P</code>] + [<code class="option">-V</code>] + [filename] + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.26.7"></a><h2>DESCRIPTION</h2> + + <p><span class="command"><strong>nsupdate</strong></span> + is used to submit Dynamic DNS Update requests as defined in RFC 2136 + to a name server. + This allows resource records to be added or removed from a zone + without manually editing the zone file. + A single update request can contain requests to add or remove more than + one + resource record. + </p> + <p> + Zones that are under dynamic control via + <span class="command"><strong>nsupdate</strong></span> + or a DHCP server should not be edited by hand. + Manual edits could + conflict with dynamic updates and cause data to be lost. + </p> + <p> + The resource records that are dynamically added or removed with + <span class="command"><strong>nsupdate</strong></span> + have to be in the same zone. + Requests are sent to the zone's master server. + This is identified by the MNAME field of the zone's SOA record. + </p> + <p> + Transaction signatures can be used to authenticate the Dynamic + DNS updates. These use the TSIG resource record type described + in RFC 2845 or the SIG(0) record described in RFC 2535 and + RFC 2931 or GSS-TSIG as described in RFC 3645. + </p> + <p> + TSIG relies on + a shared secret that should only be known to + <span class="command"><strong>nsupdate</strong></span> and the name server. + For instance, suitable <span class="type">key</span> and + <span class="type">server</span> statements would be added to + <code class="filename">/etc/named.conf</code> so that the name server + can associate the appropriate secret key and algorithm with + the IP address of the client application that will be using + TSIG authentication. You can use <span class="command"><strong>ddns-confgen</strong></span> + to generate suitable configuration fragments. + <span class="command"><strong>nsupdate</strong></span> + uses the <code class="option">-y</code> or <code class="option">-k</code> options + to provide the TSIG shared secret. These options are mutually exclusive. + </p> + <p> + SIG(0) uses public key cryptography. + To use a SIG(0) key, the public key must be stored in a KEY + record in a zone served by the name server. + </p> + <p> + GSS-TSIG uses Kerberos credentials. Standard GSS-TSIG mode + is switched on with the <code class="option">-g</code> flag. A + non-standards-compliant variant of GSS-TSIG used by Windows + 2000 can be switched on with the <code class="option">-o</code> flag. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.26.8"></a><h2>OPTIONS</h2> + + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-d</span></dt> +<dd> + <p> + Debug mode. This provides tracing information about the + update requests that are made and the replies received + from the name server. + </p> + </dd> +<dt><span class="term">-D</span></dt> +<dd> + <p> + Extra debug mode. + </p> + </dd> +<dt><span class="term">-i</span></dt> +<dd> + <p> + Force interactive mode, even when standard input is not a terminal. + </p> + </dd> +<dt><span class="term">-k <em class="replaceable"><code>keyfile</code></em></span></dt> +<dd> + <p> + The file containing the TSIG authentication key. + Keyfiles may be in two formats: a single file containing + a <code class="filename">named.conf</code>-format <span class="command"><strong>key</strong></span> + statement, which may be generated automatically by + <span class="command"><strong>ddns-confgen</strong></span>, or a pair of files whose names are + of the format <code class="filename">K{name}.+157.+{random}.key</code> and + <code class="filename">K{name}.+157.+{random}.private</code>, which can be + generated by <span class="command"><strong>dnssec-keygen</strong></span>. + The <code class="option">-k</code> may also be used to specify a SIG(0) key used + to authenticate Dynamic DNS update requests. In this case, the key + specified is not an HMAC-MD5 key. + </p> + </dd> +<dt><span class="term">-l</span></dt> +<dd> + <p> + Local-host only mode. This sets the server address to + localhost (disabling the <span class="command"><strong>server</strong></span> so that the server + address cannot be overridden). Connections to the local server will + use a TSIG key found in <code class="filename">/var/run/named/session.key</code>, + which is automatically generated by <span class="command"><strong>named</strong></span> if any + local master zone has set <span class="command"><strong>update-policy</strong></span> to + <span class="command"><strong>local</strong></span>. The location of this key file can be + overridden with the <code class="option">-k</code> option. + </p> + </dd> +<dt><span class="term">-L <em class="replaceable"><code>level</code></em></span></dt> +<dd> + <p> + Set the logging debug level. If zero, logging is disabled. + </p> + </dd> +<dt><span class="term">-p <em class="replaceable"><code>port</code></em></span></dt> +<dd> + <p> + Set the port to use for connections to a name server. The + default is 53. + </p> + </dd> +<dt><span class="term">-P</span></dt> +<dd> + <p> + Print the list of private BIND-specific resource record + types whose format is understood + by <span class="command"><strong>nsupdate</strong></span>. See also + the <code class="option">-T</code> option. + </p> + </dd> +<dt><span class="term">-r <em class="replaceable"><code>udpretries</code></em></span></dt> +<dd> + <p> + The number of UDP retries. The default is 3. If zero, only + one update request will be made. + </p> + </dd> +<dt><span class="term">-R <em class="replaceable"><code>randomdev</code></em></span></dt> +<dd> + <p> + Where to obtain randomness. If the operating system + does not provide a <code class="filename">/dev/random</code> or + equivalent device, the default source of randomness is keyboard + input. <code class="filename">randomdev</code> specifies the name of + a character device or file containing random data to be used + instead of the default. The special value + <code class="filename">keyboard</code> indicates that keyboard input + should be used. This option may be specified multiple times. + </p> + </dd> +<dt><span class="term">-t <em class="replaceable"><code>timeout</code></em></span></dt> +<dd> + <p> + The maximum time an update request can take before it is + aborted. The default is 300 seconds. Zero can be used to + disable the timeout. + </p> + </dd> +<dt><span class="term">-T</span></dt> +<dd> + <p> + Print the list of IANA standard resource record types + whose format is understood by <span class="command"><strong>nsupdate</strong></span>. + <span class="command"><strong>nsupdate</strong></span> will exit after the lists are + printed. The <code class="option">-T</code> option can be combined + with the <code class="option">-P</code> option. + </p> + <p> + Other types can be entered using "TYPEXXXXX" where "XXXXX" is the + decimal value of the type with no leading zeros. The rdata, + if present, will be parsed using the UNKNOWN rdata format, + (<backslash> <hash> <space> <length> + <space> <hexstring>). + </p> + </dd> +<dt><span class="term">-u <em class="replaceable"><code>udptimeout</code></em></span></dt> +<dd> + <p> + The UDP retry interval. The default is 3 seconds. If zero, + the interval will be computed from the timeout interval and + number of UDP retries. + </p> + </dd> +<dt><span class="term">-v</span></dt> +<dd> + <p> + Use TCP even for small update requests. + By default, <span class="command"><strong>nsupdate</strong></span> + uses UDP to send update requests to the name server unless they are too + large to fit in a UDP request in which case TCP will be used. + TCP may be preferable when a batch of update requests is made. + </p> + </dd> +<dt><span class="term">-V</span></dt> +<dd> + <p> + Print the version number and exit. + </p> + </dd> +<dt><span class="term">-y <em class="replaceable"><code>[<span class="optional">hmac:</span>]keyname:secret</code></em></span></dt> +<dd> + <p> + Literal TSIG authentication key. + <em class="parameter"><code>keyname</code></em> is the name of the key, and + <em class="parameter"><code>secret</code></em> is the base64 encoded shared secret. + <em class="parameter"><code>hmac</code></em> is the name of the key algorithm; + valid choices are <code class="literal">hmac-md5</code>, + <code class="literal">hmac-sha1</code>, <code class="literal">hmac-sha224</code>, + <code class="literal">hmac-sha256</code>, <code class="literal">hmac-sha384</code>, or + <code class="literal">hmac-sha512</code>. If <em class="parameter"><code>hmac</code></em> + is not specified, the default is <code class="literal">hmac-md5</code> + or if MD5 was disabled <code class="literal">hmac-sha256</code>. + </p> + <p> + NOTE: Use of the <code class="option">-y</code> option is discouraged because the + shared secret is supplied as a command line argument in clear text. + This may be visible in the output from + <span class="citerefentry"> + <span class="refentrytitle">ps</span>(1) + </span> + or in a history file maintained by the user's shell. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.26.9"></a><h2>INPUT FORMAT</h2> + + <p><span class="command"><strong>nsupdate</strong></span> + reads input from + <em class="parameter"><code>filename</code></em> + or standard input. + Each command is supplied on exactly one line of input. + Some commands are for administrative purposes. + The others are either update instructions or prerequisite checks on the + contents of the zone. + These checks set conditions that some name or set of + resource records (RRset) either exists or is absent from the zone. + These conditions must be met if the entire update request is to succeed. + Updates will be rejected if the tests for the prerequisite conditions + fail. + </p> + <p> + Every update request consists of zero or more prerequisites + and zero or more updates. + This allows a suitably authenticated update request to proceed if some + specified resource records are present or missing from the zone. + A blank input line (or the <span class="command"><strong>send</strong></span> command) + causes the + accumulated commands to be sent as one Dynamic DNS update request to the + name server. + </p> + <p> + The command formats and their meaning are as follows: + </p> +<div class="variablelist"><dl class="variablelist"> +<dt><span class="term"> + <span class="command"><strong>server</strong></span> + {servername} + [port] + </span></dt> +<dd> + <p> + Sends all dynamic update requests to the name server + <em class="parameter"><code>servername</code></em>. + When no server statement is provided, + <span class="command"><strong>nsupdate</strong></span> + will send updates to the master server of the correct zone. + The MNAME field of that zone's SOA record will identify the + master + server for that zone. + <em class="parameter"><code>port</code></em> + is the port number on + <em class="parameter"><code>servername</code></em> + where the dynamic update requests get sent. + If no port number is specified, the default DNS port number of + 53 is + used. + </p> + </dd> +<dt><span class="term"> + <span class="command"><strong>local</strong></span> + {address} + [port] + </span></dt> +<dd> + <p> + Sends all dynamic update requests using the local + <em class="parameter"><code>address</code></em>. + + When no local statement is provided, + <span class="command"><strong>nsupdate</strong></span> + will send updates using an address and port chosen by the + system. + <em class="parameter"><code>port</code></em> + can additionally be used to make requests come from a specific + port. + If no port number is specified, the system will assign one. + </p> + </dd> +<dt><span class="term"> + <span class="command"><strong>zone</strong></span> + {zonename} + </span></dt> +<dd> + <p> + Specifies that all updates are to be made to the zone + <em class="parameter"><code>zonename</code></em>. + If no + <em class="parameter"><code>zone</code></em> + statement is provided, + <span class="command"><strong>nsupdate</strong></span> + will attempt determine the correct zone to update based on the + rest of the input. + </p> + </dd> +<dt><span class="term"> + <span class="command"><strong>class</strong></span> + {classname} + </span></dt> +<dd> + <p> + Specify the default class. + If no <em class="parameter"><code>class</code></em> is specified, the + default class is + <em class="parameter"><code>IN</code></em>. + </p> + </dd> +<dt><span class="term"> + <span class="command"><strong>ttl</strong></span> + {seconds} + </span></dt> +<dd> + <p> + Specify the default time to live for records to be added. + The value <em class="parameter"><code>none</code></em> will clear the default + ttl. + </p> + </dd> +<dt><span class="term"> + <span class="command"><strong>key</strong></span> + [hmac:] {keyname} + {secret} + </span></dt> +<dd> + <p> + Specifies that all updates are to be TSIG-signed using the + <em class="parameter"><code>keyname</code></em> <em class="parameter"><code>secret</code></em> pair. + If <em class="parameter"><code>hmac</code></em> is specified, then it sets the + signing algorithm in use; the default is + <code class="literal">hmac-md5</code> or if MD5 was disabled + <code class="literal">hmac-sha256</code>. The <span class="command"><strong>key</strong></span> + command overrides any key specified on the command line via + <code class="option">-y</code> or <code class="option">-k</code>. + </p> + </dd> +<dt><span class="term"> + <span class="command"><strong>gsstsig</strong></span> + </span></dt> +<dd> + <p> + Use GSS-TSIG to sign the updated. This is equivalent to + specifying <code class="option">-g</code> on the command line. + </p> + </dd> +<dt><span class="term"> + <span class="command"><strong>oldgsstsig</strong></span> + </span></dt> +<dd> + <p> + Use the Windows 2000 version of GSS-TSIG to sign the updated. + This is equivalent to specifying <code class="option">-o</code> on the + command line. + </p> + </dd> +<dt><span class="term"> + <span class="command"><strong>realm</strong></span> + {[<span class="optional">realm_name</span>]} + </span></dt> +<dd> + <p> + When using GSS-TSIG use <em class="parameter"><code>realm_name</code></em> rather + than the default realm in <code class="filename">krb5.conf</code>. If no + realm is specified the saved realm is cleared. + </p> + </dd> +<dt><span class="term"> + <span class="command"><strong>check-names</strong></span> + {[<span class="optional">yes_or_no</span>]} + </span></dt> +<dd> + <p> + Turn on or off check-names processing on records to + be added. Check-names has no effect on prerequisites + or records to be deleted. By default check-names + processing is on. If check-names processing fails + the record will not be added to the UPDATE message. + </p> + </dd> +<dt><span class="term"> + <span class="command"><strong>[<span class="optional">prereq</span>] nxdomain</strong></span> + {domain-name} + </span></dt> +<dd> + <p> + Requires that no resource record of any type exists with name + <em class="parameter"><code>domain-name</code></em>. + </p> + </dd> +<dt><span class="term"> + <span class="command"><strong>[<span class="optional">prereq</span>] yxdomain</strong></span> + {domain-name} + </span></dt> +<dd> + <p> + Requires that + <em class="parameter"><code>domain-name</code></em> + exists (has as at least one resource record, of any type). + </p> + </dd> +<dt><span class="term"> + <span class="command"><strong>[<span class="optional">prereq</span>] nxrrset</strong></span> + {domain-name} + [class] + {type} + </span></dt> +<dd> + <p> + Requires that no resource record exists of the specified + <em class="parameter"><code>type</code></em>, + <em class="parameter"><code>class</code></em> + and + <em class="parameter"><code>domain-name</code></em>. + If + <em class="parameter"><code>class</code></em> + is omitted, IN (internet) is assumed. + </p> + </dd> +<dt><span class="term"> + <span class="command"><strong>[<span class="optional">prereq</span>] yxrrset</strong></span> + {domain-name} + [class] + {type} + </span></dt> +<dd> + <p> + This requires that a resource record of the specified + <em class="parameter"><code>type</code></em>, + <em class="parameter"><code>class</code></em> + and + <em class="parameter"><code>domain-name</code></em> + must exist. + If + <em class="parameter"><code>class</code></em> + is omitted, IN (internet) is assumed. + </p> + </dd> +<dt><span class="term"> + <span class="command"><strong>[<span class="optional">prereq</span>] yxrrset</strong></span> + {domain-name} + [class] + {type} + {data...} + </span></dt> +<dd> + <p> + The + <em class="parameter"><code>data</code></em> + from each set of prerequisites of this form + sharing a common + <em class="parameter"><code>type</code></em>, + <em class="parameter"><code>class</code></em>, + and + <em class="parameter"><code>domain-name</code></em> + are combined to form a set of RRs. This set of RRs must + exactly match the set of RRs existing in the zone at the + given + <em class="parameter"><code>type</code></em>, + <em class="parameter"><code>class</code></em>, + and + <em class="parameter"><code>domain-name</code></em>. + The + <em class="parameter"><code>data</code></em> + are written in the standard text representation of the resource + record's + RDATA. + </p> + </dd> +<dt><span class="term"> + <span class="command"><strong>[<span class="optional">update</span>] del[<span class="optional">ete</span>]</strong></span> + {domain-name} + [ttl] + [class] + [type [data...]] + </span></dt> +<dd> + <p> + Deletes any resource records named + <em class="parameter"><code>domain-name</code></em>. + If + <em class="parameter"><code>type</code></em> + and + <em class="parameter"><code>data</code></em> + is provided, only matching resource records will be removed. + The internet class is assumed if + <em class="parameter"><code>class</code></em> + is not supplied. The + <em class="parameter"><code>ttl</code></em> + is ignored, and is only allowed for compatibility. + </p> + </dd> +<dt><span class="term"> + <span class="command"><strong>[<span class="optional">update</span>] add</strong></span> + {domain-name} + {ttl} + [class] + {type} + {data...} + </span></dt> +<dd> + <p> + Adds a new resource record with the specified + <em class="parameter"><code>ttl</code></em>, + <em class="parameter"><code>class</code></em> + and + <em class="parameter"><code>data</code></em>. + </p> + </dd> +<dt><span class="term"> + <span class="command"><strong>show</strong></span> + </span></dt> +<dd> + <p> + Displays the current message, containing all of the + prerequisites and + updates specified since the last send. + </p> + </dd> +<dt><span class="term"> + <span class="command"><strong>send</strong></span> + </span></dt> +<dd> + <p> + Sends the current message. This is equivalent to entering a + blank line. + </p> + </dd> +<dt><span class="term"> + <span class="command"><strong>answer</strong></span> + </span></dt> +<dd> + <p> + Displays the answer. + </p> + </dd> +<dt><span class="term"> + <span class="command"><strong>debug</strong></span> + </span></dt> +<dd> + <p> + Turn on debugging. + </p> + </dd> +<dt><span class="term"> + <span class="command"><strong>version</strong></span> + </span></dt> +<dd> + <p> + Print version number. + </p> + </dd> +<dt><span class="term"> + <span class="command"><strong>help</strong></span> + </span></dt> +<dd> + <p> + Print a list of commands. + </p> + </dd> +</dl></div> +<p> + </p> + + <p> + Lines beginning with a semicolon are comments and are ignored. + </p> + + </div> + + <div class="refsection"> +<a name="id-1.14.26.10"></a><h2>EXAMPLES</h2> + + <p> + The examples below show how + <span class="command"><strong>nsupdate</strong></span> + could be used to insert and delete resource records from the + <span class="type">example.com</span> + zone. + Notice that the input in each example contains a trailing blank line so + that + a group of commands are sent as one dynamic update request to the + master name server for + <span class="type">example.com</span>. + + </p> +<pre class="programlisting"> +# nsupdate +> update delete oldhost.example.com A +> update add newhost.example.com 86400 A 172.16.1.1 +> send +</pre> +<p> + </p> + <p> + Any A records for + <span class="type">oldhost.example.com</span> + are deleted. + And an A record for + <span class="type">newhost.example.com</span> + with IP address 172.16.1.1 is added. + The newly-added record has a 1 day TTL (86400 seconds). + </p> +<pre class="programlisting"> +# nsupdate +> prereq nxdomain nickname.example.com +> update add nickname.example.com 86400 CNAME somehost.example.com +> send +</pre> +<p> + </p> + <p> + The prerequisite condition gets the name server to check that there + are no resource records of any type for + <span class="type">nickname.example.com</span>. + + If there are, the update request fails. + If this name does not exist, a CNAME for it is added. + This ensures that when the CNAME is added, it cannot conflict with the + long-standing rule in RFC 1034 that a name must not exist as any other + record type if it exists as a CNAME. + (The rule has been updated for DNSSEC in RFC 2535 to allow CNAMEs to have + RRSIG, DNSKEY and NSEC records.) + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.26.11"></a><h2>FILES</h2> + + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><code class="constant">/etc/resolv.conf</code></span></dt> +<dd> + <p> + used to identify default name server + </p> + </dd> +<dt><span class="term"><code class="constant">/var/run/named/session.key</code></span></dt> +<dd> + <p> + sets the default TSIG key for use in local-only mode + </p> + </dd> +<dt><span class="term"><code class="constant">K{name}.+157.+{random}.key</code></span></dt> +<dd> + <p> + base-64 encoding of HMAC-MD5 key created by + <span class="citerefentry"> + <span class="refentrytitle">dnssec-keygen</span>(8) + </span>. + </p> + </dd> +<dt><span class="term"><code class="constant">K{name}.+157.+{random}.private</code></span></dt> +<dd> + <p> + base-64 encoding of HMAC-MD5 key created by + <span class="citerefentry"> + <span class="refentrytitle">dnssec-keygen</span>(8) + </span>. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.26.12"></a><h2>SEE ALSO</h2> + + <p> + <em class="citetitle">RFC 2136</em>, + <em class="citetitle">RFC 3007</em>, + <em class="citetitle">RFC 2104</em>, + <em class="citetitle">RFC 2845</em>, + <em class="citetitle">RFC 1034</em>, + <em class="citetitle">RFC 2535</em>, + <em class="citetitle">RFC 2931</em>, + <span class="citerefentry"> + <span class="refentrytitle">named</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">ddns-confgen</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">dnssec-keygen</span>(8) + </span>. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.26.13"></a><h2>BUGS</h2> + + <p> + The TSIG key is redundantly stored in two separate files. + This is a consequence of nsupdate using the DST library + for its cryptographic operations, and may change in future + releases. + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.named-rrchecker.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.rndc.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">named-rrchecker</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">rndc</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.pkcs11-destroy.html b/doc/arm/man.pkcs11-destroy.html new file mode 100644 index 0000000..d6dd468 --- /dev/null +++ b/doc/arm/man.pkcs11-destroy.html @@ -0,0 +1,167 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>pkcs11-destroy</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.nsec3hash.html" title="nsec3hash"> +<link rel="next" href="man.pkcs11-list.html" title="pkcs11-list"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">pkcs11-destroy</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.nsec3hash.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.pkcs11-list.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.pkcs11-destroy"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">pkcs11-destroy</span> + — destroy PKCS#11 objects + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">pkcs11-destroy</code> + [<code class="option">-m <em class="replaceable"><code>module</code></em></code>] + [<code class="option">-s <em class="replaceable"><code>slot</code></em></code>] + { + -i <em class="replaceable"><code>ID</code></em> + | -l <em class="replaceable"><code>label</code></em> + } + [<code class="option">-p <em class="replaceable"><code>PIN</code></em></code>] + [<code class="option">-w <em class="replaceable"><code>seconds</code></em></code>] + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.36.7"></a><h2>DESCRIPTION</h2> + + <p> + <span class="command"><strong>pkcs11-destroy</strong></span> destroys keys stored in a + PKCS#11 device, identified by their <code class="option">ID</code> or + <code class="option">label</code>. + </p> + <p> + Matching keys are displayed before being destroyed. By default, + there is a five second delay to allow the user to interrupt the + process before the destruction takes place. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.36.8"></a><h2>ARGUMENTS</h2> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-m <em class="replaceable"><code>module</code></em></span></dt> +<dd> + <p> + Specify the PKCS#11 provider module. This must be the full + path to a shared library object implementing the PKCS#11 API + for the device. + </p> + </dd> +<dt><span class="term">-s <em class="replaceable"><code>slot</code></em></span></dt> +<dd> + <p> + Open the session with the given PKCS#11 slot. The default is + slot 0. + </p> + </dd> +<dt><span class="term">-i <em class="replaceable"><code>ID</code></em></span></dt> +<dd> + <p> + Destroy keys with the given object ID. + </p> + </dd> +<dt><span class="term">-l <em class="replaceable"><code>label</code></em></span></dt> +<dd> + <p> + Destroy keys with the given label. + </p> + </dd> +<dt><span class="term">-p <em class="replaceable"><code>PIN</code></em></span></dt> +<dd> + <p> + Specify the PIN for the device. If no PIN is provided on the + command line, <span class="command"><strong>pkcs11-destroy</strong></span> will prompt for it. + </p> + </dd> +<dt><span class="term">-w <em class="replaceable"><code>seconds</code></em></span></dt> +<dd> + <p> + Specify how long to pause before carrying out key destruction. + The default is five seconds. If set to <code class="literal">0</code>, + destruction will be immediate. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.36.9"></a><h2>SEE ALSO</h2> + + <p> + <span class="citerefentry"> + <span class="refentrytitle">pkcs11-keygen</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">pkcs11-list</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">pkcs11-tokens</span>(8) + </span> + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.nsec3hash.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.pkcs11-list.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">nsec3hash</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">pkcs11-list</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.pkcs11-keygen.html b/doc/arm/man.pkcs11-keygen.html new file mode 100644 index 0000000..be38e0d --- /dev/null +++ b/doc/arm/man.pkcs11-keygen.html @@ -0,0 +1,205 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>pkcs11-keygen</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.pkcs11-list.html" title="pkcs11-list"> +<link rel="next" href="man.pkcs11-tokens.html" title="pkcs11-tokens"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">pkcs11-keygen</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.pkcs11-list.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.pkcs11-tokens.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.pkcs11-keygen"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">pkcs11-keygen</span> + — generate keys on a PKCS#11 device + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">pkcs11-keygen</code> + {-a <em class="replaceable"><code>algorithm</code></em>} + [<code class="option">-b <em class="replaceable"><code>keysize</code></em></code>] + [<code class="option">-e</code>] + [<code class="option">-i <em class="replaceable"><code>id</code></em></code>] + [<code class="option">-m <em class="replaceable"><code>module</code></em></code>] + [<code class="option">-P</code>] + [<code class="option">-p <em class="replaceable"><code>PIN</code></em></code>] + [<code class="option">-q</code>] + [<code class="option">-S</code>] + [<code class="option">-s <em class="replaceable"><code>slot</code></em></code>] + {label} + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.38.7"></a><h2>DESCRIPTION</h2> + + <p> + <span class="command"><strong>pkcs11-keygen</strong></span> causes a PKCS#11 device to generate + a new key pair with the given <code class="option">label</code> (which must be + unique) and with <code class="option">keysize</code> bits of prime. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.38.8"></a><h2>ARGUMENTS</h2> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-a <em class="replaceable"><code>algorithm</code></em></span></dt> +<dd> + <p> + Specify the key algorithm class: Supported classes are RSA, + DSA, DH, ECC and ECX. In addition to these strings, the + <code class="option">algorithm</code> can be specified as a DNSSEC + signing algorithm that will be used with this key; for + example, NSEC3RSASHA1 maps to RSA, ECDSAP256SHA256 maps + to ECC, and ED25519 to ECX. The default class is "RSA". + </p> + </dd> +<dt><span class="term">-b <em class="replaceable"><code>keysize</code></em></span></dt> +<dd> + <p> + Create the key pair with <code class="option">keysize</code> bits of + prime. For ECC keys, the only valid values are 256 and 384, + and the default is 256. For ECX kyes, the only valid values + are 256 and 456, and the default is 256. + </p> + </dd> +<dt><span class="term">-e</span></dt> +<dd> + <p> + For RSA keys only, use a large exponent. + </p> + </dd> +<dt><span class="term">-i <em class="replaceable"><code>id</code></em></span></dt> +<dd> + <p> + Create key objects with id. The id is either + an unsigned short 2 byte or an unsigned long 4 byte number. + </p> + </dd> +<dt><span class="term">-m <em class="replaceable"><code>module</code></em></span></dt> +<dd> + <p> + Specify the PKCS#11 provider module. This must be the full + path to a shared library object implementing the PKCS#11 API + for the device. + </p> + </dd> +<dt><span class="term">-P</span></dt> +<dd> + <p> + Set the new private key to be non-sensitive and extractable. + The allows the private key data to be read from the PKCS#11 + device. The default is for private keys to be sensitive and + non-extractable. + </p> + </dd> +<dt><span class="term">-p <em class="replaceable"><code>PIN</code></em></span></dt> +<dd> + <p> + Specify the PIN for the device. If no PIN is provided on + the command line, <span class="command"><strong>pkcs11-keygen</strong></span> will + prompt for it. + </p> + </dd> +<dt><span class="term">-q</span></dt> +<dd> + <p> + Quiet mode: suppress unnecessary output. + </p> + </dd> +<dt><span class="term">-S</span></dt> +<dd> + <p> + For Diffie-Hellman (DH) keys only, use a special prime of + 768, 1024 or 1536 bit size and base (aka generator) 2. + If not specified, bit size will default to 1024. + </p> + </dd> +<dt><span class="term">-s <em class="replaceable"><code>slot</code></em></span></dt> +<dd> + <p> + Open the session with the given PKCS#11 slot. The default is + slot 0. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.38.9"></a><h2>SEE ALSO</h2> + + <p> + <span class="citerefentry"> + <span class="refentrytitle">pkcs11-destroy</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">pkcs11-list</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">pkcs11-tokens</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">dnssec-keyfromlabel</span>(8) + </span> + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.pkcs11-list.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.pkcs11-tokens.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">pkcs11-list</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">pkcs11-tokens</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.pkcs11-list.html b/doc/arm/man.pkcs11-list.html new file mode 100644 index 0000000..e095875 --- /dev/null +++ b/doc/arm/man.pkcs11-list.html @@ -0,0 +1,163 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>pkcs11-list</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.pkcs11-destroy.html" title="pkcs11-destroy"> +<link rel="next" href="man.pkcs11-keygen.html" title="pkcs11-keygen"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">pkcs11-list</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.pkcs11-destroy.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.pkcs11-keygen.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.pkcs11-list"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">pkcs11-list</span> + — list PKCS#11 objects + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">pkcs11-list</code> + [<code class="option">-P</code>] + [<code class="option">-m <em class="replaceable"><code>module</code></em></code>] + [<code class="option">-s <em class="replaceable"><code>slot</code></em></code>] + [-i <em class="replaceable"><code>ID</code></em>] + [-l <em class="replaceable"><code>label</code></em>] + [<code class="option">-p <em class="replaceable"><code>PIN</code></em></code>] + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.37.7"></a><h2>DESCRIPTION</h2> + + <p> + <span class="command"><strong>pkcs11-list</strong></span> + lists the PKCS#11 objects with <code class="option">ID</code> or + <code class="option">label</code> or by default all objects. + The object class, label, and ID are displayed for all + keys. For private or secret keys, the extractability + attribute is also displayed, as either <code class="literal">true</code>, + <code class="literal">false</code>, or <code class="literal">never</code>. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.37.8"></a><h2>ARGUMENTS</h2> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-P</span></dt> +<dd> + <p> + List only the public objects. (Note that on some PKCS#11 + devices, all objects are private.) + </p> + </dd> +<dt><span class="term">-m <em class="replaceable"><code>module</code></em></span></dt> +<dd> + <p> + Specify the PKCS#11 provider module. This must be the full + path to a shared library object implementing the PKCS#11 API + for the device. + </p> + </dd> +<dt><span class="term">-s <em class="replaceable"><code>slot</code></em></span></dt> +<dd> + <p> + Open the session with the given PKCS#11 slot. The default is + slot 0. + </p> + </dd> +<dt><span class="term">-i <em class="replaceable"><code>ID</code></em></span></dt> +<dd> + <p> + List only key objects with the given object ID. + </p> + </dd> +<dt><span class="term">-l <em class="replaceable"><code>label</code></em></span></dt> +<dd> + <p> + List only key objects with the given label. + </p> + </dd> +<dt><span class="term">-p <em class="replaceable"><code>PIN</code></em></span></dt> +<dd> + <p> + Specify the PIN for the device. If no PIN is provided on the + command line, <span class="command"><strong>pkcs11-list</strong></span> will prompt for it. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.37.9"></a><h2>SEE ALSO</h2> + + <p> + <span class="citerefentry"> + <span class="refentrytitle">pkcs11-destroy</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">pkcs11-keygen</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">pkcs11-tokens</span>(8) + </span> + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.pkcs11-destroy.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.pkcs11-keygen.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">pkcs11-destroy</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">pkcs11-keygen</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.pkcs11-tokens.html b/doc/arm/man.pkcs11-tokens.html new file mode 100644 index 0000000..fee6a3d --- /dev/null +++ b/doc/arm/man.pkcs11-tokens.html @@ -0,0 +1,124 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>pkcs11-tokens</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.pkcs11-keygen.html" title="pkcs11-keygen"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">pkcs11-tokens</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.pkcs11-keygen.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> </td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.pkcs11-tokens"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">pkcs11-tokens</span> + — list PKCS#11 available tokens + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">pkcs11-tokens</code> + [<code class="option">-m <em class="replaceable"><code>module</code></em></code>] + [<code class="option">-v</code>] + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.39.7"></a><h2>DESCRIPTION</h2> + + <p> + <span class="command"><strong>pkcs11-tokens</strong></span> + lists the PKCS#11 available tokens with defaults from the slot/token + scan performed at application initialization. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.39.8"></a><h2>ARGUMENTS</h2> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-m <em class="replaceable"><code>module</code></em></span></dt> +<dd> + <p> + Specify the PKCS#11 provider module. This must be the full + path to a shared library object implementing the PKCS#11 API + for the device. + </p> + </dd> +<dt><span class="term">-v</span></dt> +<dd> + <p> + Make the PKCS#11 libisc initialization verbose. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.39.9"></a><h2>SEE ALSO</h2> + + <p> + <span class="citerefentry"> + <span class="refentrytitle">pkcs11-destroy</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">pkcs11-keygen</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">pkcs11-list</span>(8) + </span> + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.pkcs11-keygen.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> </td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">pkcs11-keygen</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> </td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.rndc-confgen.html b/doc/arm/man.rndc-confgen.html new file mode 100644 index 0000000..a5cc9d2 --- /dev/null +++ b/doc/arm/man.rndc-confgen.html @@ -0,0 +1,282 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>rndc-confgen</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.rndc.conf.html" title="rndc.conf"> +<link rel="next" href="man.ddns-confgen.html" title="ddns-confgen"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">rndc-confgen</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.rndc.conf.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.ddns-confgen.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.rndc-confgen"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">rndc-confgen</span> + — rndc key generation tool + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">rndc-confgen</code> + [<code class="option">-a</code>] + [<code class="option">-A <em class="replaceable"><code>algorithm</code></em></code>] + [<code class="option">-b <em class="replaceable"><code>keysize</code></em></code>] + [<code class="option">-c <em class="replaceable"><code>keyfile</code></em></code>] + [<code class="option">-h</code>] + [<code class="option">-k <em class="replaceable"><code>keyname</code></em></code>] + [<code class="option">-p <em class="replaceable"><code>port</code></em></code>] + [<code class="option">-r <em class="replaceable"><code>randomfile</code></em></code>] + [<code class="option">-s <em class="replaceable"><code>address</code></em></code>] + [<code class="option">-t <em class="replaceable"><code>chrootdir</code></em></code>] + [<code class="option">-u <em class="replaceable"><code>user</code></em></code>] + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.29.7"></a><h2>DESCRIPTION</h2> + + <p><span class="command"><strong>rndc-confgen</strong></span> + generates configuration files + for <span class="command"><strong>rndc</strong></span>. It can be used as a + convenient alternative to writing the + <code class="filename">rndc.conf</code> file + and the corresponding <span class="command"><strong>controls</strong></span> + and <span class="command"><strong>key</strong></span> + statements in <code class="filename">named.conf</code> by hand. + Alternatively, it can be run with the <span class="command"><strong>-a</strong></span> + option to set up a <code class="filename">rndc.key</code> file and + avoid the need for a <code class="filename">rndc.conf</code> file + and a <span class="command"><strong>controls</strong></span> statement altogether. + </p> + + </div> + + <div class="refsection"> +<a name="id-1.14.29.8"></a><h2>OPTIONS</h2> + + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-a</span></dt> +<dd> + <p> + Do automatic <span class="command"><strong>rndc</strong></span> configuration. + This creates a file <code class="filename">rndc.key</code> + in <code class="filename">/etc</code> (or whatever + <code class="varname">sysconfdir</code> + was specified as when <acronym class="acronym">BIND</acronym> was + built) + that is read by both <span class="command"><strong>rndc</strong></span> + and <span class="command"><strong>named</strong></span> on startup. The + <code class="filename">rndc.key</code> file defines a default + command channel and authentication key allowing + <span class="command"><strong>rndc</strong></span> to communicate with + <span class="command"><strong>named</strong></span> on the local host + with no further configuration. + </p> + <p> + Running <span class="command"><strong>rndc-confgen -a</strong></span> allows + BIND 9 and <span class="command"><strong>rndc</strong></span> to be used as + drop-in + replacements for BIND 8 and <span class="command"><strong>ndc</strong></span>, + with no changes to the existing BIND 8 + <code class="filename">named.conf</code> file. + </p> + <p> + If a more elaborate configuration than that + generated by <span class="command"><strong>rndc-confgen -a</strong></span> + is required, for example if rndc is to be used remotely, + you should run <span class="command"><strong>rndc-confgen</strong></span> without + the + <span class="command"><strong>-a</strong></span> option and set up a + <code class="filename">rndc.conf</code> and + <code class="filename">named.conf</code> + as directed. + </p> + </dd> +<dt><span class="term">-A <em class="replaceable"><code>algorithm</code></em></span></dt> +<dd> + <p> + Specifies the algorithm to use for the TSIG key. Available + choices are: hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256, + hmac-sha384 and hmac-sha512. The default is hmac-md5 or + if MD5 was disabled hmac-sha256. + </p> + </dd> +<dt><span class="term">-b <em class="replaceable"><code>keysize</code></em></span></dt> +<dd> + <p> + Specifies the size of the authentication key in bits. + Must be between 1 and 512 bits; the default is the + hash size. + </p> + </dd> +<dt><span class="term">-c <em class="replaceable"><code>keyfile</code></em></span></dt> +<dd> + <p> + Used with the <span class="command"><strong>-a</strong></span> option to specify + an alternate location for <code class="filename">rndc.key</code>. + </p> + </dd> +<dt><span class="term">-h</span></dt> +<dd> + <p> + Prints a short summary of the options and arguments to + <span class="command"><strong>rndc-confgen</strong></span>. + </p> + </dd> +<dt><span class="term">-k <em class="replaceable"><code>keyname</code></em></span></dt> +<dd> + <p> + Specifies the key name of the rndc authentication key. + This must be a valid domain name. + The default is <code class="constant">rndc-key</code>. + </p> + </dd> +<dt><span class="term">-p <em class="replaceable"><code>port</code></em></span></dt> +<dd> + <p> + Specifies the command channel port where <span class="command"><strong>named</strong></span> + listens for connections from <span class="command"><strong>rndc</strong></span>. + The default is 953. + </p> + </dd> +<dt><span class="term">-r <em class="replaceable"><code>randomfile</code></em></span></dt> +<dd> + <p> + Specifies a source of random data for generating the + authorization. If the operating + system does not provide a <code class="filename">/dev/random</code> + or equivalent device, the default source of randomness + is keyboard input. <code class="filename">randomdev</code> + specifies + the name of a character device or file containing random + data to be used instead of the default. The special value + <code class="filename">keyboard</code> indicates that keyboard + input should be used. + </p> + </dd> +<dt><span class="term">-s <em class="replaceable"><code>address</code></em></span></dt> +<dd> + <p> + Specifies the IP address where <span class="command"><strong>named</strong></span> + listens for command channel connections from + <span class="command"><strong>rndc</strong></span>. The default is the loopback + address 127.0.0.1. + </p> + </dd> +<dt><span class="term">-t <em class="replaceable"><code>chrootdir</code></em></span></dt> +<dd> + <p> + Used with the <span class="command"><strong>-a</strong></span> option to specify + a directory where <span class="command"><strong>named</strong></span> will run + chrooted. An additional copy of the <code class="filename">rndc.key</code> + will be written relative to this directory so that + it will be found by the chrooted <span class="command"><strong>named</strong></span>. + </p> + </dd> +<dt><span class="term">-u <em class="replaceable"><code>user</code></em></span></dt> +<dd> + <p> + Used with the <span class="command"><strong>-a</strong></span> option to set the + owner + of the <code class="filename">rndc.key</code> file generated. + If + <span class="command"><strong>-t</strong></span> is also specified only the file + in + the chroot area has its owner changed. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.29.9"></a><h2>EXAMPLES</h2> + + <p> + To allow <span class="command"><strong>rndc</strong></span> to be used with + no manual configuration, run + </p> + <p><strong class="userinput"><code>rndc-confgen -a</code></strong> + </p> + <p> + To print a sample <code class="filename">rndc.conf</code> file and + corresponding <span class="command"><strong>controls</strong></span> and <span class="command"><strong>key</strong></span> + statements to be manually inserted into <code class="filename">named.conf</code>, + run + </p> + <p><strong class="userinput"><code>rndc-confgen</code></strong> + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.29.10"></a><h2>SEE ALSO</h2> + + <p><span class="citerefentry"> + <span class="refentrytitle">rndc</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">rndc.conf</span>(5) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">named</span>(8) + </span>, + <em class="citetitle">BIND 9 Administrator Reference Manual</em>. + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.rndc.conf.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.ddns-confgen.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<code class="filename">rndc.conf</code> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">ddns-confgen</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.rndc.conf.html b/doc/arm/man.rndc.conf.html new file mode 100644 index 0000000..65889d4 --- /dev/null +++ b/doc/arm/man.rndc.conf.html @@ -0,0 +1,273 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>rndc.conf</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.rndc.html" title="rndc"> +<link rel="next" href="man.rndc-confgen.html" title="rndc-confgen"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><code class="filename">rndc.conf</code></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.rndc.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.rndc-confgen.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.rndc.conf"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <code class="filename">rndc.conf</code> + — rndc configuration file + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">rndc.conf</code> + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.28.7"></a><h2>DESCRIPTION</h2> + + <p><code class="filename">rndc.conf</code> is the configuration file + for <span class="command"><strong>rndc</strong></span>, the BIND 9 name server control + utility. This file has a similar structure and syntax to + <code class="filename">named.conf</code>. Statements are enclosed + in braces and terminated with a semi-colon. Clauses in + the statements are also semi-colon terminated. The usual + comment styles are supported: + </p> + <p> + C style: /* */ + </p> + <p> + C++ style: // to end of line + </p> + <p> + Unix style: # to end of line + </p> + <p><code class="filename">rndc.conf</code> is much simpler than + <code class="filename">named.conf</code>. The file uses three + statements: an options statement, a server statement + and a key statement. + </p> + <p> + The <code class="option">options</code> statement contains five clauses. + The <code class="option">default-server</code> clause is followed by the + name or address of a name server. This host will be used when + no name server is given as an argument to + <span class="command"><strong>rndc</strong></span>. The <code class="option">default-key</code> + clause is followed by the name of a key which is identified by + a <code class="option">key</code> statement. If no + <code class="option">keyid</code> is provided on the rndc command line, + and no <code class="option">key</code> clause is found in a matching + <code class="option">server</code> statement, this default key will be + used to authenticate the server's commands and responses. The + <code class="option">default-port</code> clause is followed by the port + to connect to on the remote name server. If no + <code class="option">port</code> option is provided on the rndc command + line, and no <code class="option">port</code> clause is found in a + matching <code class="option">server</code> statement, this default port + will be used to connect. + The <code class="option">default-source-address</code> and + <code class="option">default-source-address-v6</code> clauses which + can be used to set the IPv4 and IPv6 source addresses + respectively. + </p> + <p> + After the <code class="option">server</code> keyword, the server + statement includes a string which is the hostname or address + for a name server. The statement has three possible clauses: + <code class="option">key</code>, <code class="option">port</code> and + <code class="option">addresses</code>. The key name must match the + name of a key statement in the file. The port number + specifies the port to connect to. If an <code class="option">addresses</code> + clause is supplied these addresses will be used instead of + the server name. Each address can take an optional port. + If an <code class="option">source-address</code> or <code class="option">source-address-v6</code> + of supplied then these will be used to specify the IPv4 and IPv6 + source addresses respectively. + </p> + <p> + The <code class="option">key</code> statement begins with an identifying + string, the name of the key. The statement has two clauses. + <code class="option">algorithm</code> identifies the authentication algorithm + for <span class="command"><strong>rndc</strong></span> to use; currently only HMAC-MD5 + (for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256 + (default), HMAC-SHA384 and HMAC-SHA512 are + supported. This is followed by a secret clause which contains + the base-64 encoding of the algorithm's authentication key. The + base-64 string is enclosed in double quotes. + </p> + <p> + There are two common ways to generate the base-64 string for the + secret. The BIND 9 program <span class="command"><strong>rndc-confgen</strong></span> + can + be used to generate a random key, or the + <span class="command"><strong>mmencode</strong></span> program, also known as + <span class="command"><strong>mimencode</strong></span>, can be used to generate a + base-64 + string from known input. <span class="command"><strong>mmencode</strong></span> does + not + ship with BIND 9 but is available on many systems. See the + EXAMPLE section for sample command lines for each. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.28.8"></a><h2>EXAMPLE</h2> + + + <pre class="programlisting"> + options { + default-server localhost; + default-key samplekey; + }; +</pre> +<p> + </p> + <pre class="programlisting"> + server localhost { + key samplekey; + }; +</pre> +<p> + </p> + <pre class="programlisting"> + server testserver { + key testkey; + addresses { localhost port 5353; }; + }; +</pre> +<p> + </p> + <pre class="programlisting"> + key samplekey { + algorithm hmac-sha256; + secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz"; + }; +</pre> +<p> + </p> + <pre class="programlisting"> + key testkey { + algorithm hmac-sha256; + secret "R3HI8P6BKw9ZwXwN3VZKuQ=="; + }; + </pre> +<p> + </p> + + <p> + In the above example, <span class="command"><strong>rndc</strong></span> will by + default use + the server at localhost (127.0.0.1) and the key called samplekey. + Commands to the localhost server will use the samplekey key, which + must also be defined in the server's configuration file with the + same name and secret. The key statement indicates that samplekey + uses the HMAC-SHA256 algorithm and its secret clause contains the + base-64 encoding of the HMAC-SHA256 secret enclosed in double quotes. + </p> + <p> + If <span class="command"><strong>rndc -s testserver</strong></span> is used then <span class="command"><strong>rndc</strong></span> will + connect to server on localhost port 5353 using the key testkey. + </p> + <p> + To generate a random secret with <span class="command"><strong>rndc-confgen</strong></span>: + </p> + <p><strong class="userinput"><code>rndc-confgen</code></strong> + </p> + <p> + A complete <code class="filename">rndc.conf</code> file, including + the + randomly generated key, will be written to the standard + output. Commented-out <code class="option">key</code> and + <code class="option">controls</code> statements for + <code class="filename">named.conf</code> are also printed. + </p> + <p> + To generate a base-64 secret with <span class="command"><strong>mmencode</strong></span>: + </p> + <p><strong class="userinput"><code>echo "known plaintext for a secret" | mmencode</code></strong> + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.28.9"></a><h2>NAME SERVER CONFIGURATION</h2> + + <p> + The name server must be configured to accept rndc connections and + to recognize the key specified in the <code class="filename">rndc.conf</code> + file, using the controls statement in <code class="filename">named.conf</code>. + See the sections on the <code class="option">controls</code> statement in the + BIND 9 Administrator Reference Manual for details. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.28.10"></a><h2>SEE ALSO</h2> + + <p><span class="citerefentry"> + <span class="refentrytitle">rndc</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">rndc-confgen</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">mmencode</span>(1) + </span>, + <em class="citetitle">BIND 9 Administrator Reference Manual</em>. + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.rndc.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.rndc-confgen.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">rndc</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">rndc-confgen</span> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/man.rndc.html b/doc/arm/man.rndc.html new file mode 100644 index 0000000..993e7f4 --- /dev/null +++ b/doc/arm/man.rndc.html @@ -0,0 +1,899 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>rndc</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages"> +<link rel="prev" href="man.nsupdate.html" title="nsupdate"> +<link rel="next" href="man.rndc.conf.html" title="rndc.conf"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">rndc</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.nsupdate.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.rndc.conf.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry"> +<a name="man.rndc"></a><div class="titlepage"></div> + + + + + + <div class="refnamediv"> +<h2>Name</h2> +<p> + <span class="application">rndc</span> + — name server control utility + </p> +</div> + + + + <div class="refsynopsisdiv"> +<h2>Synopsis</h2> + <div class="cmdsynopsis"><p> + <code class="command">rndc</code> + [<code class="option">-b <em class="replaceable"><code>source-address</code></em></code>] + [<code class="option">-c <em class="replaceable"><code>config-file</code></em></code>] + [<code class="option">-k <em class="replaceable"><code>key-file</code></em></code>] + [<code class="option">-s <em class="replaceable"><code>server</code></em></code>] + [<code class="option">-p <em class="replaceable"><code>port</code></em></code>] + [<code class="option">-q</code>] + [<code class="option">-r</code>] + [<code class="option">-V</code>] + [<code class="option">-y <em class="replaceable"><code>key_id</code></em></code>] + {command} + </p></div> + </div> + + <div class="refsection"> +<a name="id-1.14.27.7"></a><h2>DESCRIPTION</h2> + + <p><span class="command"><strong>rndc</strong></span> + controls the operation of a name + server. It supersedes the <span class="command"><strong>ndc</strong></span> utility + that was provided in old BIND releases. If + <span class="command"><strong>rndc</strong></span> is invoked with no command line + options or arguments, it prints a short summary of the + supported commands and the available options and their + arguments. + </p> + <p><span class="command"><strong>rndc</strong></span> + communicates with the name server over a TCP connection, sending + commands authenticated with digital signatures. In the current + versions of + <span class="command"><strong>rndc</strong></span> and <span class="command"><strong>named</strong></span>, + the only supported authentication algorithms are HMAC-MD5 + (for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256 + (default), HMAC-SHA384 and HMAC-SHA512. + They use a shared secret on each end of the connection. + This provides TSIG-style authentication for the command + request and the name server's response. All commands sent + over the channel must be signed by a key_id known to the + server. + </p> + <p><span class="command"><strong>rndc</strong></span> + reads a configuration file to + determine how to contact the name server and decide what + algorithm and key it should use. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.27.8"></a><h2>OPTIONS</h2> + + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-b <em class="replaceable"><code>source-address</code></em></span></dt> +<dd> + <p> + Use <em class="replaceable"><code>source-address</code></em> + as the source address for the connection to the server. + Multiple instances are permitted to allow setting of both + the IPv4 and IPv6 source addresses. + </p> + </dd> +<dt><span class="term">-c <em class="replaceable"><code>config-file</code></em></span></dt> +<dd> + <p> + Use <em class="replaceable"><code>config-file</code></em> + as the configuration file instead of the default, + <code class="filename">/etc/rndc.conf</code>. + </p> + </dd> +<dt><span class="term">-k <em class="replaceable"><code>key-file</code></em></span></dt> +<dd> + <p> + Use <em class="replaceable"><code>key-file</code></em> + as the key file instead of the default, + <code class="filename">/etc/rndc.key</code>. The key in + <code class="filename">/etc/rndc.key</code> will be used to + authenticate + commands sent to the server if the <em class="replaceable"><code>config-file</code></em> + does not exist. + </p> + </dd> +<dt><span class="term">-s <em class="replaceable"><code>server</code></em></span></dt> +<dd> + <p><em class="replaceable"><code>server</code></em> is + the name or address of the server which matches a + server statement in the configuration file for + <span class="command"><strong>rndc</strong></span>. If no server is supplied on the + command line, the host named by the default-server clause + in the options statement of the <span class="command"><strong>rndc</strong></span> + configuration file will be used. + </p> + </dd> +<dt><span class="term">-p <em class="replaceable"><code>port</code></em></span></dt> +<dd> + <p> + Send commands to TCP port + <em class="replaceable"><code>port</code></em> + instead + of BIND 9's default control channel port, 953. + </p> + </dd> +<dt><span class="term">-q</span></dt> +<dd> + <p> + Quiet mode: Message text returned by the server + will not be printed except when there is an error. + </p> + </dd> +<dt><span class="term">-r</span></dt> +<dd> + <p> + Instructs <span class="command"><strong>rndc</strong></span> to print the result code + returned by <span class="command"><strong>named</strong></span> after executing the + requested command (e.g., ISC_R_SUCCESS, ISC_R_FAILURE, etc). + </p> + </dd> +<dt><span class="term">-V</span></dt> +<dd> + <p> + Enable verbose logging. + </p> + </dd> +<dt><span class="term">-y <em class="replaceable"><code>key_id</code></em></span></dt> +<dd> + <p> + Use the key <em class="replaceable"><code>key_id</code></em> + from the configuration file. + <em class="replaceable"><code>key_id</code></em> + must be + known by <span class="command"><strong>named</strong></span> with the same algorithm and secret string + in order for control message validation to succeed. + If no <em class="replaceable"><code>key_id</code></em> + is specified, <span class="command"><strong>rndc</strong></span> will first look + for a key clause in the server statement of the server + being used, or if no server statement is present for that + host, then the default-key clause of the options statement. + Note that the configuration file contains shared secrets + which are used to send authenticated control commands + to name servers. It should therefore not have general read + or write access. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.27.9"></a><h2>COMMANDS</h2> + + <p> + A list of commands supported by <span class="command"><strong>rndc</strong></span> can + be seen by running <span class="command"><strong>rndc</strong></span> without arguments. + </p> + <p> + Currently supported commands are: + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><strong class="userinput"><code>addzone <em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>] <em class="replaceable"><code>configuration</code></em> </code></strong></span></dt> +<dd> + <p> + Add a zone while the server is running. This + command requires the + <span class="command"><strong>allow-new-zones</strong></span> option to be set + to <strong class="userinput"><code>yes</code></strong>. The + <em class="replaceable"><code>configuration</code></em> string + specified on the command line is the zone + configuration text that would ordinarily be + placed in <code class="filename">named.conf</code>. + </p> + <p> + The configuration is saved in a file called + <code class="filename"><em class="replaceable"><code>name</code></em>.nzf</code>, + where <em class="replaceable"><code>name</code></em> is the + name of the view, or if it contains characters + that are incompatible with use as a file name, a + cryptographic hash generated from the name + of the view. + When <span class="command"><strong>named</strong></span> is + restarted, the file will be loaded into the view + configuration, so that zones that were added + can persist after a restart. + </p> + <p> + This sample <span class="command"><strong>addzone</strong></span> command + would add the zone <code class="literal">example.com</code> + to the default view: + </p> + <p> +<code class="prompt">$ </code><strong class="userinput"><code>rndc addzone example.com '{ type master; file "example.com.db"; };'</code></strong> + </p> + <p> + (Note the brackets and semi-colon around the zone + configuration text.) + </p> + <p> + See also <span class="command"><strong>rndc delzone</strong></span> and <span class="command"><strong>rndc modzone</strong></span>. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>delzone [<span class="optional">-clean</span>] <em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>] </code></strong></span></dt> +<dd> + <p> + Delete a zone while the server is running. + </p> + <p> + If the <code class="option">-clean</code> argument is specified, + the zone's master file (and journal file, if any) + will be deleted along with the zone. Without the + <code class="option">-clean</code> option, zone files must + be cleaned up by hand. (If the zone is of + type "slave" or "stub", the files needing to + be cleaned up will be reported in the output + of the <span class="command"><strong>rndc delzone</strong></span> command.) + </p> + <p> + If the zone was originally added via + <span class="command"><strong>rndc addzone</strong></span>, then it will be + removed permanently. However, if it was originally + configured in <code class="filename">named.conf</code>, then + that original configuration is still in place; when + the server is restarted or reconfigured, the zone will + come back. To remove it permanently, it must also be + removed from <code class="filename">named.conf</code> + </p> + <p> + See also <span class="command"><strong>rndc addzone</strong></span> and <span class="command"><strong>rndc modzone</strong></span>. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>dnstap ( -reopen | -roll [<span class="optional"><em class="replaceable"><code>number</code></em></span>] )</code></strong></span></dt> +<dd> + <p> + Close and re-open DNSTAP output files. + <span class="command"><strong>rndc dnstap -reopen</strong></span> allows the output + file to be renamed externally, so + that <span class="command"><strong>named</strong></span> can truncate and re-open it. + <span class="command"><strong>rndc dnstap -roll</strong></span> causes the output file + to be rolled automatically, similar to log files; the most + recent output file has ".0" appended to its name; the + previous most recent output file is moved to ".1", and so on. + If <em class="replaceable"><code>number</code></em> is specified, then the + number of backup log files is limited to that number. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>dumpdb [<span class="optional">-all|-cache|-zones|-adb|-bad|-fail</span>] [<span class="optional"><em class="replaceable"><code>view ...</code></em></span>]</code></strong></span></dt> +<dd> + <p> + Dump the server's caches (default) and/or zones to + the dump file for the specified views. If no view + is specified, all views are dumped. + (See the <span class="command"><strong>dump-file</strong></span> option in + the BIND 9 Administrator Reference Manual.) + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>flush</code></strong></span></dt> +<dd> + <p> + Flushes the server's cache. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>flushname</code></strong> <em class="replaceable"><code>name</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>] </span></dt> +<dd> + <p> + Flushes the given name from the view's DNS cache + and, if applicable, from the view's nameserver address + database, bad server cache and SERVFAIL cache. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>flushtree</code></strong> <em class="replaceable"><code>name</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>] </span></dt> +<dd> + <p> + Flushes the given name, and all of its subdomains, + from the view's DNS cache, address database, + bad server cache, and SERVFAIL cache. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>freeze [<span class="optional"><em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</span>]</code></strong></span></dt> +<dd> + <p> + Suspend updates to a dynamic zone. If no zone is + specified, then all zones are suspended. This allows + manual edits to be made to a zone normally updated by + dynamic update. It also causes changes in the + journal file to be synced into the master file. + All dynamic update attempts will be refused while + the zone is frozen. + </p> + <p> + See also <span class="command"><strong>rndc thaw</strong></span>. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>halt [<span class="optional">-p</span>]</code></strong></span></dt> +<dd> + <p> + Stop the server immediately. Recent changes + made through dynamic update or IXFR are not saved to + the master files, but will be rolled forward from the + journal files when the server is restarted. + If <code class="option">-p</code> is specified <span class="command"><strong>named</strong></span>'s process id is returned. + This allows an external process to determine when <span class="command"><strong>named</strong></span> + had completed halting. + </p> + <p> + See also <span class="command"><strong>rndc stop</strong></span>. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>loadkeys <em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</code></strong></span></dt> +<dd> + <p> + Fetch all DNSSEC keys for the given zone + from the key directory. If they are within + their publication period, merge them into the + zone's DNSKEY RRset. Unlike <span class="command"><strong>rndc + sign</strong></span>, however, the zone is not + immediately re-signed by the new keys, but is + allowed to incrementally re-sign over time. + </p> + <p> + This command requires that the + <span class="command"><strong>auto-dnssec</strong></span> zone option + be set to <code class="literal">maintain</code>, + and also requires the zone to be configured to + allow dynamic DNS. + (See "Dynamic Update Policies" in the Administrator + Reference Manual for more details.) + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>managed-keys <em class="replaceable"><code>(status | refresh | sync)</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</code></strong></span></dt> +<dd> + <p> + When run with the "status" keyword, print the current + status of the managed-keys database for the specified + view, or for all views if none is specified. When run + with the "refresh" keyword, force an immediate refresh + of all the managed-keys in the specified view, or all + views. When run with the "sync" keyword, force an + immediate dump of the managed-keys database to disk (in + the file <code class="filename">managed-keys.bind</code> or + (<code class="filename"><em class="replaceable"><code>viewname</code></em>.mkeys</code>). + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>modzone <em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>] <em class="replaceable"><code>configuration</code></em> </code></strong></span></dt> +<dd> + <p> + Modify the configuration of a zone while the server + is running. This command requires the + <span class="command"><strong>allow-new-zones</strong></span> option to be + set to <strong class="userinput"><code>yes</code></strong>. As with + <span class="command"><strong>addzone</strong></span>, the + <em class="replaceable"><code>configuration</code></em> string + specified on the command line is the zone + configuration text that would ordinarily be + placed in <code class="filename">named.conf</code>. + </p> + <p> + If the zone was originally added via + <span class="command"><strong>rndc addzone</strong></span>, the configuration + changes will be recorded permanently and will still be + in effect after the server is restarted or reconfigured. + However, if it was originally configured in + <code class="filename">named.conf</code>, then that original + configuration is still in place; when the server is + restarted or reconfigured, the zone will revert to + its original configuration. To make the changes + permanent, it must also be modified in + <code class="filename">named.conf</code> + </p> + <p> + See also <span class="command"><strong>rndc addzone</strong></span> and <span class="command"><strong>rndc delzone</strong></span>. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>notify <em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</code></strong></span></dt> +<dd> + <p> + Resend NOTIFY messages for the zone. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>notrace</code></strong></span></dt> +<dd> + <p> + Sets the server's debugging level to 0. + </p> + <p> + See also <span class="command"><strong>rndc trace</strong></span>. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>nta + [<span class="optional">( -class <em class="replaceable"><code>class</code></em> | -dump | -force | -remove | -lifetime <em class="replaceable"><code>duration</code></em>)</span>] + <em class="replaceable"><code>domain</code></em> + [<span class="optional"><em class="replaceable"><code>view</code></em></span>] + </code></strong></span></dt> +<dd> + <p> + Sets a DNSSEC negative trust anchor (NTA) + for <code class="option">domain</code>, with a lifetime of + <code class="option">duration</code>. The default lifetime is + configured in <code class="filename">named.conf</code> via the + <code class="option">nta-lifetime</code> option, and defaults to + one hour. The lifetime cannot exceed one week. + </p> + <p> + A negative trust anchor selectively disables + DNSSEC validation for zones that are known to be + failing because of misconfiguration rather than + an attack. When data to be validated is + at or below an active NTA (and above any other + configured trust anchors), <span class="command"><strong>named</strong></span> will + abort the DNSSEC validation process and treat the data as + insecure rather than bogus. This continues until the + NTA's lifetime is elapsed. + </p> + <p> + NTAs persist across restarts of the <span class="command"><strong>named</strong></span> server. + The NTAs for a view are saved in a file called + <code class="filename"><em class="replaceable"><code>name</code></em>.nta</code>, + where <em class="replaceable"><code>name</code></em> is the + name of the view, or if it contains characters + that are incompatible with use as a file name, a + cryptographic hash generated from the name + of the view. + </p> + <p> + An existing NTA can be removed by using the + <code class="option">-remove</code> option. + </p> + <p> + An NTA's lifetime can be specified with the + <code class="option">-lifetime</code> option. TTL-style + suffixes can be used to specify the lifetime in + seconds, minutes, or hours. If the specified NTA + already exists, its lifetime will be updated to the + new value. Setting <code class="option">lifetime</code> to zero + is equivalent to <code class="option">-remove</code>. + </p> + <p> + If the <code class="option">-dump</code> is used, any other arguments + are ignored, and a list of existing NTAs is printed + (note that this may include NTAs that are expired but + have not yet been cleaned up). + </p> + <p> + Normally, <span class="command"><strong>named</strong></span> will periodically + test to see whether data below an NTA can now be + validated (see the <code class="option">nta-recheck</code> option + in the Administrator Reference Manual for details). + If data can be validated, then the NTA is regarded as + no longer necessary, and will be allowed to expire + early. The <code class="option">-force</code> overrides this + behavior and forces an NTA to persist for its entire + lifetime, regardless of whether data could be + validated if the NTA were not present. + </p> + <p> + The view class can be specified with <code class="option">-class</code>. + The default is class <strong class="userinput"><code>IN</code></strong>, which is + the only class for which DNSSEC is currently supported. + </p> + <p> + All of these options can be shortened, i.e., to + <code class="option">-l</code>, <code class="option">-r</code>, <code class="option">-d</code>, + <code class="option">-f</code>, and <code class="option">-c</code>. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>querylog</code></strong> [<span class="optional"> on | off </span>] </span></dt> +<dd> + <p> + Enable or disable query logging. (For backward + compatibility, this command can also be used without + an argument to toggle query logging on and off.) + </p> + <p> + Query logging can also be enabled + by explicitly directing the <span class="command"><strong>queries</strong></span> + <span class="command"><strong>category</strong></span> to a + <span class="command"><strong>channel</strong></span> in the + <span class="command"><strong>logging</strong></span> section of + <code class="filename">named.conf</code> or by specifying + <span class="command"><strong>querylog yes;</strong></span> in the + <span class="command"><strong>options</strong></span> section of + <code class="filename">named.conf</code>. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>reconfig</code></strong></span></dt> +<dd> + <p> + Reload the configuration file and load new zones, + but do not reload existing zone files even if they + have changed. + This is faster than a full <span class="command"><strong>reload</strong></span> when there + is a large number of zones because it avoids the need + to examine the + modification times of the zones files. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>recursing</code></strong></span></dt> +<dd> + <p> + Dump the list of queries <span class="command"><strong>named</strong></span> is currently + recursing on, and the list of domains to which iterative + queries are currently being sent. (The second list includes + the number of fetches currently active for the given domain, + and how many have been passed or dropped because of the + <code class="option">fetches-per-zone</code> option.) + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>refresh <em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</code></strong></span></dt> +<dd> + <p> + Schedule zone maintenance for the given zone. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>reload</code></strong></span></dt> +<dd> + <p> + Reload configuration file and zones. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>reload <em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</code></strong></span></dt> +<dd> + <p> + Reload the given zone. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>retransfer <em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</code></strong></span></dt> +<dd> + <p> + Retransfer the given slave zone from the master server. + </p> + <p> + If the zone is configured to use + <span class="command"><strong>inline-signing</strong></span>, the signed + version of the zone is discarded; after the + retransfer of the unsigned version is complete, the + signed version will be regenerated with all new + signatures. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>scan</code></strong></span></dt> +<dd> + <p> + Scan the list of available network interfaces + for changes, without performing a full + <span class="command"><strong>reconfig</strong></span> or waiting for the + <span class="command"><strong>interface-interval</strong></span> timer. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>secroots [<span class="optional">-</span>] [<span class="optional"><em class="replaceable"><code>view ...</code></em></span>]</code></strong></span></dt> +<dd> + <p> + Dump the server's security roots and negative trust anchors + for the specified views. If no view is specified, all views + are dumped. + </p> + <p> + If the first argument is "-", then the output is + returned via the <span class="command"><strong>rndc</strong></span> response channel + and printed to the standard output. + Otherwise, it is written to the secroots dump file, which + defaults to <code class="filename">named.secroots</code>, but can be + overridden via the <code class="option">secroots-file</code> option in + <code class="filename">named.conf</code>. + </p> + <p> + See also <span class="command"><strong>rndc managed-keys</strong></span>. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>showzone <em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>] </code></strong></span></dt> +<dd> + <p> + Print the configuration of a running zone. + </p> + <p> + See also <span class="command"><strong>rndc zonestatus</strong></span>. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>sign <em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</code></strong></span></dt> +<dd> + <p> + Fetch all DNSSEC keys for the given zone + from the key directory (see the + <span class="command"><strong>key-directory</strong></span> option in + the BIND 9 Administrator Reference Manual). If they are within + their publication period, merge them into the + zone's DNSKEY RRset. If the DNSKEY RRset + is changed, then the zone is automatically + re-signed with the new key set. + </p> + <p> + This command requires that the + <span class="command"><strong>auto-dnssec</strong></span> zone option be set + to <code class="literal">allow</code> or + <code class="literal">maintain</code>, + and also requires the zone to be configured to + allow dynamic DNS. + (See "Dynamic Update Policies" in the Administrator + Reference Manual for more details.) + </p> + <p> + See also <span class="command"><strong>rndc loadkeys</strong></span>. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>signing [<span class="optional">( -list | -clear <em class="replaceable"><code>keyid/algorithm</code></em> | -clear <code class="literal">all</code> | -nsec3param ( <em class="replaceable"><code>parameters</code></em> | <code class="literal">none</code> ) | -serial <em class="replaceable"><code>value</code></em> ) </span>] <em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>] </code></strong></span></dt> +<dd> + <p> + List, edit, or remove the DNSSEC signing state records + for the specified zone. The status of ongoing DNSSEC + operations (such as signing or generating + NSEC3 chains) is stored in the zone in the form + of DNS resource records of type + <span class="command"><strong>sig-signing-type</strong></span>. + <span class="command"><strong>rndc signing -list</strong></span> converts + these records into a human-readable form, + indicating which keys are currently signing + or have finished signing the zone, and which NSEC3 + chains are being created or removed. + </p> + <p> + <span class="command"><strong>rndc signing -clear</strong></span> can remove + a single key (specified in the same format that + <span class="command"><strong>rndc signing -list</strong></span> uses to + display it), or all keys. In either case, only + completed keys are removed; any record indicating + that a key has not yet finished signing the zone + will be retained. + </p> + <p> + <span class="command"><strong>rndc signing -nsec3param</strong></span> sets + the NSEC3 parameters for a zone. This is the + only supported mechanism for using NSEC3 with + <span class="command"><strong>inline-signing</strong></span> zones. + Parameters are specified in the same format as + an NSEC3PARAM resource record: hash algorithm, + flags, iterations, and salt, in that order. + </p> + <p> + Currently, the only defined value for hash algorithm + is <code class="literal">1</code>, representing SHA-1. + The <code class="option">flags</code> may be set to + <code class="literal">0</code> or <code class="literal">1</code>, + depending on whether you wish to set the opt-out + bit in the NSEC3 chain. <code class="option">iterations</code> + defines the number of additional times to apply + the algorithm when generating an NSEC3 hash. The + <code class="option">salt</code> is a string of data expressed + in hexadecimal, a hyphen (`-') if no salt is + to be used, or the keyword <code class="literal">auto</code>, + which causes <span class="command"><strong>named</strong></span> to generate a + random 64-bit salt. + </p> + <p> + So, for example, to create an NSEC3 chain using + the SHA-1 hash algorithm, no opt-out flag, + 10 iterations, and a salt value of "FFFF", use: + <span class="command"><strong>rndc signing -nsec3param 1 0 10 FFFF <em class="replaceable"><code>zone</code></em></strong></span>. + To set the opt-out flag, 15 iterations, and no + salt, use: + <span class="command"><strong>rndc signing -nsec3param 1 1 15 - <em class="replaceable"><code>zone</code></em></strong></span>. + </p> + <p> + <span class="command"><strong>rndc signing -nsec3param none</strong></span> + removes an existing NSEC3 chain and replaces it + with NSEC. + </p> + <p> + <span class="command"><strong>rndc signing -serial value</strong></span> sets + the serial number of the zone to value. If the value + would cause the serial number to go backwards it will + be rejected. The primary use is to set the serial on + inline signed zones. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>stats</code></strong></span></dt> +<dd> + <p> + Write server statistics to the statistics file. + (See the <span class="command"><strong>statistics-file</strong></span> option in + the BIND 9 Administrator Reference Manual.) + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>status</code></strong></span></dt> +<dd> + <p> + Display status of the server. + Note that the number of zones includes the internal <span class="command"><strong>bind/CH</strong></span> zone + and the default <span class="command"><strong>./IN</strong></span> + hint zone if there is not an + explicit root zone configured. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>stop [<span class="optional">-p</span>]</code></strong></span></dt> +<dd> + <p> + Stop the server, making sure any recent changes + made through dynamic update or IXFR are first saved to + the master files of the updated zones. + If <code class="option">-p</code> is specified <span class="command"><strong>named</strong></span>'s process id is returned. + This allows an external process to determine when <span class="command"><strong>named</strong></span> + had completed stopping. + </p> + <p>See also <span class="command"><strong>rndc halt</strong></span>.</p> + </dd> +<dt><span class="term"><strong class="userinput"><code>sync [<span class="optional">-clean</span>] [<span class="optional"><em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</span>]</code></strong></span></dt> +<dd> + <p> + Sync changes in the journal file for a dynamic zone + to the master file. If the "-clean" option is + specified, the journal file is also removed. If + no zone is specified, then all zones are synced. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>thaw [<span class="optional"><em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</span>]</code></strong></span></dt> +<dd> + <p> + Enable updates to a frozen dynamic zone. If no + zone is specified, then all frozen zones are + enabled. This causes the server to reload the zone + from disk, and re-enables dynamic updates after the + load has completed. After a zone is thawed, + dynamic updates will no longer be refused. If + the zone has changed and the + <span class="command"><strong>ixfr-from-differences</strong></span> option is + in use, then the journal file will be updated to + reflect changes in the zone. Otherwise, if the + zone has changed, any existing journal file will be + removed. + </p> + <p>See also <span class="command"><strong>rndc freeze</strong></span>.</p> + </dd> +<dt><span class="term"><strong class="userinput"><code>trace</code></strong></span></dt> +<dd> + <p> + Increment the servers debugging level by one. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>trace <em class="replaceable"><code>level</code></em></code></strong></span></dt> +<dd> + <p> + Sets the server's debugging level to an explicit + value. + </p> + <p> + See also <span class="command"><strong>rndc notrace</strong></span>. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>tsig-delete</code></strong> <em class="replaceable"><code>keyname</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span></dt> +<dd> + <p> + Delete a given TKEY-negotiated key from the server. + (This does not apply to statically configured TSIG + keys.) + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>tsig-list</code></strong></span></dt> +<dd> + <p> + List the names of all TSIG keys currently configured + for use by <span class="command"><strong>named</strong></span> in each view. The + list both statically configured keys and dynamic + TKEY-negotiated keys. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>validation ( on | off | status ) [<span class="optional"><em class="replaceable"><code>view ...</code></em></span>] </code></strong></span></dt> +<dd> + <p> + Enable, disable, or check the current status of + DNSSEC validation. + Note <span class="command"><strong>dnssec-enable</strong></span> also needs to be + set to <strong class="userinput"><code>yes</code></strong> or + <strong class="userinput"><code>auto</code></strong> to be effective. + It defaults to enabled. + </p> + </dd> +<dt><span class="term"><strong class="userinput"><code>zonestatus <em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</code></strong></span></dt> +<dd> + <p> + Displays the current status of the given zone, + including the master file name and any include + files from which it was loaded, when it was most + recently loaded, the current serial number, the + number of nodes, whether the zone supports + dynamic updates, whether the zone is DNSSEC + signed, whether it uses automatic DNSSEC key + management or inline signing, and the scheduled + refresh or expiry times for the zone. + </p> + <p> + See also <span class="command"><strong>rndc showzone</strong></span>. + </p> + </dd> +</dl></div> + </div> + + <div class="refsection"> +<a name="id-1.14.27.10"></a><h2>LIMITATIONS</h2> + + <p> + There is currently no way to provide the shared secret for a + <code class="option">key_id</code> without using the configuration file. + </p> + <p> + Several error messages could be clearer. + </p> + </div> + + <div class="refsection"> +<a name="id-1.14.27.11"></a><h2>SEE ALSO</h2> + + <p><span class="citerefentry"> + <span class="refentrytitle">rndc.conf</span>(5) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">rndc-confgen</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">named</span>(8) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">named.conf</span>(5) + </span>, + <span class="citerefentry"> + <span class="refentrytitle">ndc</span>(8) + </span>, + <em class="citetitle">BIND 9 Administrator Reference Manual</em>. + </p> + </div> + +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.nsupdate.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.rndc.conf.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">nsupdate</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <code class="filename">rndc.conf</code> +</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> diff --git a/doc/arm/managed-keys.grammar.xml b/doc/arm/managed-keys.grammar.xml new file mode 100644 index 0000000..d79f27f --- /dev/null +++ b/doc/arm/managed-keys.grammar.xml @@ -0,0 +1,17 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Generated by doc/misc/docbook-options.pl --> + +<programlisting> +<command>managed-keys</command> { <replaceable>string</replaceable> <replaceable>string</replaceable> <replaceable>integer</replaceable> + <replaceable>integer</replaceable> <replaceable>integer</replaceable> <replaceable>quoted_string</replaceable>; ... }; +</programlisting> diff --git a/doc/arm/managed-keys.xml b/doc/arm/managed-keys.xml new file mode 100644 index 0000000..ba45a6c --- /dev/null +++ b/doc/arm/managed-keys.xml @@ -0,0 +1,95 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Converted by db4-upgrade version 1.0 --> +<section xmlns:db="http://docbook.org/ns/docbook" version="5.0" xml:id="rfc5011.support"><info><title>Dynamic Trust Anchor Management</title></info> + + <para> + BIND is able to maintain DNSSEC trust anchors using RFC 5011 key + management. This feature allows <command>named</command> to keep track + of changes to critical DNSSEC keys without any need for the operator to + make changes to configuration files. + </para> + + <section><info><title>Validating Resolver</title></info> + + <!-- TODO: command tag is overloaded for configuration and executables --> + <para>To configure a validating resolver to use RFC 5011 to + maintain a trust anchor, configure the trust anchor using a + <command>managed-keys</command> statement. Information about + this can be found in + <xref linkend="managed-keys"/>.</para> + <!-- TODO: managed-keys examples +also in DNSSEC section above here in ARM --> + </section> + <section><info><title>Authoritative Server</title></info> + + <para>To set up an authoritative zone for RFC 5011 trust anchor + maintenance, generate two (or more) key signing keys (KSKs) for + the zone. Sign the zone with one of them; this is the "active" + KSK. All KSKs which do not sign the zone are "stand-by" + keys.</para> + <para>Any validating resolver which is configured to use the + active KSK as an RFC 5011-managed trust anchor will take note + of the stand-by KSKs in the zone's DNSKEY RRset, and store them + for future reference. The resolver will recheck the zone + periodically, and after 30 days, if the new key is still there, + then the key will be accepted by the resolver as a valid trust + anchor for the zone. Any time after this 30-day acceptance + timer has completed, the active KSK can be revoked, and the + zone can be "rolled over" to the newly accepted key.</para> + <para>The easiest way to place a stand-by key in a zone is to + use the "smart signing" features of + <command>dnssec-keygen</command> and + <command>dnssec-signzone</command>. If a key with a publication + date in the past, but an activation date which is unset or in + the future, " + <command>dnssec-signzone -S</command>" will include the DNSKEY + record in the zone, but will not sign with it:</para> + <screen> +$ <userinput>dnssec-keygen -K keys -f KSK -P now -A now+2y example.net</userinput> +$ <userinput>dnssec-signzone -S -K keys example.net</userinput> +</screen> + <para>To revoke a key, the new command + <command>dnssec-revoke</command> has been added. This adds the + REVOKED bit to the key flags and re-generates the + <filename>K*.key</filename> and + <filename>K*.private</filename> files.</para> + <para>After revoking the active key, the zone must be signed + with both the revoked KSK and the new active KSK. (Smart + signing takes care of this automatically.)</para> + <para>Once a key has been revoked and used to sign the DNSKEY + RRset in which it appears, that key will never again be + accepted as a valid trust anchor by the resolver. However, + validation can proceed using the new active key (which had been + accepted by the resolver when it was a stand-by key).</para> + <para>See RFC 5011 for more details on key rollover + scenarios.</para> + <para>When a key has been revoked, its key ID changes, + increasing by 128, and wrapping around at 65535. So, for + example, the key "<filename>Kexample.com.+005+10000</filename>" becomes + "<filename>Kexample.com.+005+10128</filename>".</para> + <para>If two keys have IDs exactly 128 apart, and one is + revoked, then the two key IDs will collide, causing several + problems. To prevent this, + <command>dnssec-keygen</command> will not generate a new key if + another key is present which may collide. This checking will + only occur if the new keys are written to the same directory + which holds all other keys in use for that zone.</para> + <para>Older versions of BIND 9 did not have this precaution. + Exercise caution if using key revocation on keys that were + generated by previous releases, or if using keys stored in + multiple directories or on multiple machines.</para> + <para>It is expected that a future release of BIND 9 will + address this problem in a different way, by storing revoked + keys with their original unrevoked key IDs.</para> + </section> +</section> diff --git a/doc/arm/master.zoneopt.xml b/doc/arm/master.zoneopt.xml new file mode 100644 index 0000000..85df9bd --- /dev/null +++ b/doc/arm/master.zoneopt.xml @@ -0,0 +1,69 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Generated by doc/misc/docbook-zoneopt.pl --> +<programlisting> +<command>zone</command> <replaceable>string</replaceable> [ <replaceable>class</replaceable> ] { + <command>type</command> ( master | primary ); + <command>allow-query</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>allow-query-on</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>allow-transfer</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>allow-update</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>also-notify</command> [ port <replaceable>integer</replaceable> ] [ dscp <replaceable>integer</replaceable> ] { ( <replaceable>masters</replaceable> | <replaceable>ipv4_address</replaceable> [ port <replaceable>integer</replaceable> ] | <replaceable>ipv6_address</replaceable> [ port <replaceable>integer</replaceable> ] ) [ key <replaceable>string</replaceable> ]; ... }; + <command>alt-transfer-source</command> ( <replaceable>ipv4_address</replaceable> | * ) [ port ( <replaceable>integer</replaceable> | * ) ] [ dscp <replaceable>integer</replaceable> ]; + <command>alt-transfer-source-v6</command> ( <replaceable>ipv6_address</replaceable> | * ) [ port ( <replaceable>integer</replaceable> | * ) ] [ dscp <replaceable>integer</replaceable> ]; + <command>auto-dnssec</command> ( allow | maintain | off ); + <command>check-dup-records</command> ( fail | warn | ignore ); + <command>check-integrity</command> <replaceable>boolean</replaceable>; + <command>check-mx</command> ( fail | warn | ignore ); + <command>check-mx-cname</command> ( fail | warn | ignore ); + <command>check-names</command> ( fail | warn | ignore ); + <command>check-sibling</command> <replaceable>boolean</replaceable>; + <command>check-spf</command> ( warn | ignore ); + <command>check-srv-cname</command> ( fail | warn | ignore ); + <command>check-wildcard</command> <replaceable>boolean</replaceable>; + <command>database</command> <replaceable>string</replaceable>; + <command>dialup</command> ( notify | notify-passive | passive | refresh | <replaceable>boolean</replaceable> ); + <command>dlz</command> <replaceable>string</replaceable>; + <command>dnssec-dnskey-kskonly</command> <replaceable>boolean</replaceable>; + <command>dnssec-loadkeys-interval</command> <replaceable>integer</replaceable>; + <command>dnssec-secure-to-insecure</command> <replaceable>boolean</replaceable>; + <command>dnssec-update-mode</command> ( maintain | no-resign ); + <command>file</command> <replaceable>quoted_string</replaceable>; + <command>forward</command> ( first | only ); + <command>forwarders</command> [ port <replaceable>integer</replaceable> ] [ dscp <replaceable>integer</replaceable> ] { ( <replaceable>ipv4_address</replaceable> | <replaceable>ipv6_address</replaceable> ) [ port <replaceable>integer</replaceable> ] [ dscp <replaceable>integer</replaceable> ]; ... }; + <command>inline-signing</command> <replaceable>boolean</replaceable>; + <command>ixfr-from-differences</command> <replaceable>boolean</replaceable>; + <command>journal</command> <replaceable>quoted_string</replaceable>; + <command>key-directory</command> <replaceable>quoted_string</replaceable>; + <command>masterfile-format</command> ( map | raw | text ); + <command>masterfile-style</command> ( full | relative ); + <command>max-journal-size</command> ( unlimited | <replaceable>sizeval</replaceable> ); + <command>max-records</command> <replaceable>integer</replaceable>; + <command>max-transfer-idle-out</command> <replaceable>integer</replaceable>; + <command>max-transfer-time-out</command> <replaceable>integer</replaceable>; + <command>max-zone-ttl</command> ( unlimited | <replaceable>ttlval</replaceable> ); + <command>notify</command> ( explicit | master-only | <replaceable>boolean</replaceable> ); + <command>notify-delay</command> <replaceable>integer</replaceable>; + <command>notify-source</command> ( <replaceable>ipv4_address</replaceable> | * ) [ port ( <replaceable>integer</replaceable> | * ) ] [ dscp <replaceable>integer</replaceable> ]; + <command>notify-source-v6</command> ( <replaceable>ipv6_address</replaceable> | * ) [ port ( <replaceable>integer</replaceable> | * ) ] [ dscp <replaceable>integer</replaceable> ]; + <command>notify-to-soa</command> <replaceable>boolean</replaceable>; + <command>serial-update-method</command> ( date | increment | unixtime ); + <command>sig-signing-nodes</command> <replaceable>integer</replaceable>; + <command>sig-signing-signatures</command> <replaceable>integer</replaceable>; + <command>sig-signing-type</command> <replaceable>integer</replaceable>; + <command>sig-validity-interval</command> <replaceable>integer</replaceable> [ <replaceable>integer</replaceable> ]; + <command>update-check-ksk</command> <replaceable>boolean</replaceable>; + <command>update-policy</command> ( local | { ( deny | grant ) <replaceable>string</replaceable> ( 6to4-self | external | krb5-self | krb5-selfsub | krb5-subdomain | ms-self | ms-selfsub | ms-subdomain | name | self | selfsub | selfwild | subdomain | tcp-self | wildcard | zonesub ) [ <replaceable>string</replaceable> ] <replaceable>rrtypelist</replaceable>; ... }; + <command>zero-no-soa-ttl</command> <replaceable>boolean</replaceable>; + <command>zone-statistics</command> ( full | terse | none | <replaceable>boolean</replaceable> ); +}; +</programlisting> diff --git a/doc/arm/masters.grammar.xml b/doc/arm/masters.grammar.xml new file mode 100644 index 0000000..658fdfc --- /dev/null +++ b/doc/arm/masters.grammar.xml @@ -0,0 +1,19 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Generated by doc/misc/docbook-options.pl --> + +<programlisting> +<command>masters</command> <replaceable>string</replaceable> [ port <replaceable>integer</replaceable> ] [ dscp + <replaceable>integer</replaceable> ] { ( <replaceable>masters</replaceable> | <replaceable>ipv4_address</replaceable> [ + <command>port</command> <replaceable>integer</replaceable> ] | <replaceable>ipv6_address</replaceable> [ port + <replaceable>integer</replaceable> ] ) [ key <replaceable>string</replaceable> ]; ... }; +</programlisting> diff --git a/doc/arm/notes-wrapper.xml b/doc/arm/notes-wrapper.xml new file mode 100644 index 0000000..2a8f6d8 --- /dev/null +++ b/doc/arm/notes-wrapper.xml @@ -0,0 +1,18 @@ +<!DOCTYPE book [ +<!ENTITY mdash "—">]> +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Converted by db4-upgrade version 1.0 --> +<article xmlns:db="http://docbook.org/ns/docbook" version="5.0"><info><title/></info> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="notes.xml"/> +</article> diff --git a/doc/arm/notes.conf b/doc/arm/notes.conf new file mode 100644 index 0000000..f8dd832 --- /dev/null +++ b/doc/arm/notes.conf @@ -0,0 +1,3 @@ +TexInputs: ../tex// +TexStyle: notestyle +XslParam: ../xsl/notes-param.xsl diff --git a/doc/arm/notes.html b/doc/arm/notes.html new file mode 100644 index 0000000..78cc2e2 --- /dev/null +++ b/doc/arm/notes.html @@ -0,0 +1,291 @@ +<!-- + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. +--> +<!-- $Id$ --> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title></title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article"> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="id-1.2"></a>Release Notes for BIND Version 9.11.5-P4</h2></div></div></div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="relnotes_intro"></a>Introduction</h3></div></div></div> + <p> + This document summarizes changes since the last production + release on the BIND 9.11 (Extended Support Version) branch. + Please see the <code class="filename">CHANGES</code> file for a further + list of bug fixes and other changes. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="relnotes_download"></a>Download</h3></div></div></div> + <p> + The latest versions of BIND 9 software can always be found at + <a class="link" href="http://www.isc.org/downloads/" target="_top">http://www.isc.org/downloads/</a>. + There you will find additional information about each release, + source code, and pre-compiled versions for Microsoft Windows + operating systems. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="relnotes_license"></a>License Change</h3></div></div></div> + <p> + With the release of BIND 9.11.0, ISC changed to the open + source license for BIND from the ISC license to the Mozilla + Public License (MPL 2.0). + </p> + <p> + The MPL-2.0 license requires that if you make changes to + licensed software (e.g. BIND) and distribute them outside + your organization, that you publish those changes under that + same license. It does not require that you publish or disclose + anything other than the changes you made to our software. + </p> + <p> + This requirement will not affect anyone who is using BIND, with + or without modifications, without redistributing it, nor anyone + redistributing it without changes. Therefore, this change will be + without consequence for most individuals and organizations who are + using BIND. + </p> + <p> + Those unsure whether or not the license change affects their + use of BIND, or who wish to discuss how to comply with the + license may contact ISC at <a class="link" href="https://www.isc.org/mission/contact/" target="_top"> + https://www.isc.org/mission/contact/</a>. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="win_support"></a>Legacy Windows No Longer Supported</h3></div></div></div> + <p> + As of BIND 9.11.2, Windows XP and Windows 2003 are no longer supported + platforms for BIND; "XP" binaries are no longer available for download + from ISC. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="relnotes_security"></a>Security Fixes</h3></div></div></div> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <p> + <span class="command"><strong>named</strong></span> could crash during recursive processing + of DNAME records when <span class="command"><strong>deny-answer-aliases</strong></span> was + in use. This flaw is disclosed in CVE-2018-5740. [GL #387] + </p> + </li> +<li class="listitem"> + <p> + When recursion is enabled but the <span class="command"><strong>allow-recursion</strong></span> + and <span class="command"><strong>allow-query-cache</strong></span> ACLs are not specified, they + should be limited to local networks, but they were inadvertently set + to match the default <span class="command"><strong>allow-query</strong></span>, thus allowing + remote queries. This flaw is disclosed in CVE-2018-5738. [GL #309] + </p> + </li> +<li class="listitem"> + <p> + Code change #4964, intended to prevent double signatures + when deleting an inactive zone DNSKEY in some situations, + introduced a new problem during zone processing in which + some delegation glue RRsets are incorrectly identified + as needing RRSIGs, which are then created for them using + the current active ZSK for the zone. In some, but not all + cases, the newly-signed RRsets are added to the zone's + NSEC/NSEC3 chain, but incompletely -- this can result in + a broken chain, affecting validation of proof of nonexistence + for records in the zone. [GL #771] + </p> + </li> +<li class="listitem"> + <p> + <span class="command"><strong>named</strong></span> could crash if it managed a DNSSEC + security root with <span class="command"><strong>managed-keys</strong></span> and the + authoritative zone rolled the key to an algorithm not supported + by BIND 9. This flaw is disclosed in CVE-2018-5745. [GL #780] + </p> + </li> +<li class="listitem"> + <p> + <span class="command"><strong>named</strong></span> leaked memory when processing a + request with multiple Key Tag EDNS options present. ISC + would like to thank Toshifumi Sakaguchi for bringing this + to our attention. This flaw is disclosed in CVE-2018-5744. + [GL #772] + </p> + </li> +<li class="listitem"> + <p> + Zone transfer controls for writable DLZ zones were not + effective as the <span class="command"><strong>allowzonexfr</strong></span> method was + not being called for such zones. This flaw is disclosed in + CVE-2019-6465. [GL #790] + </p> + </li> +</ul></div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="relnotes_features"></a>New Features</h3></div></div></div> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <p> + <span class="command"><strong>named</strong></span> now supports the "root key sentinel" + mechanism. This enables validating resolvers to indicate + which trust anchors are configured for the root, so that + information about root key rollover status can be gathered. + To disable this feature, add + <span class="command"><strong>root-key-sentinel no;</strong></span> to + <code class="filename">named.conf</code>. + </p> + </li> +<li class="listitem"> + <p> + Added the ability not to return a DNS COOKIE option when one + is present in the request. To prevent a cookie being returned, + add <span class="command"><strong>answer-cookie no;</strong></span> to + <code class="filename">named.conf</code>. [GL #173] + </p> + <p> + <span class="command"><strong>answer-cookie no</strong></span> is only intended as a + temporary measure, for use when <span class="command"><strong>named</strong></span> + shares an IP address with other servers that do not yet + support DNS COOKIE. A mismatch between servers on the + same address is not expected to cause operational problems, + but the option to disable COOKIE responses so that all + servers have the same behavior is provided out of an + abundance of caution. DNS COOKIE is an important security + mechanism, and should not be disabled unless absolutely + necessary. + </p> + </li> +<li class="listitem"> + <p> + Two new update policy rule types have been added + <span class="command"><strong>krb5-selfsub</strong></span> and <span class="command"><strong>ms-selfsub</strong></span> + which allow machines with Kerberos principals to update + the name space at or below the machine names identified + in the respective principals. + </p> + </li> +</ul></div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="relnotes_removed"></a>Removed Features</h3></div></div></div> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> + <span class="command"><strong>named</strong></span> will now log a warning if the old + BIND now can be compiled against libidn2 library to add + IDNA2008 support. Previously BIND only supported IDNA2003 + using (now obsolete) idnkit-1 library. + </p> + </li></ul></div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="relnotes_changes"></a>Feature Changes</h3></div></div></div> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <p> + <span class="command"><strong>dig +noidnin</strong></span> can be used to disable IDN + processing on the input domain name, when BIND is compiled + with IDN support. + </p> + </li> +<li class="listitem"> + <p> + Multiple <span class="command"><strong>cookie-secret</strong></span> clause are now + supported. The first <span class="command"><strong>cookie-secret</strong></span> in + <code class="filename">named.conf</code> is used to generate new + server cookies. Any others are used to accept old server + cookies or those generated by other servers using the + matching <span class="command"><strong>cookie-secret</strong></span>. + </p> + </li> +<li class="listitem"> + <p> + The <span class="command"><strong>rndc nta</strong></span> command could not differentiate + between views of the same name but different class; this + has been corrected with the addition of a <span class="command"><strong>-class</strong></span> + option. [GL #105] + </p> + </li> +</ul></div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="relnotes_bugs"></a>Bug Fixes</h3></div></div></div> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <p> + When a negative trust anchor was added to multiple views + using <span class="command"><strong>rndc nta</strong></span>, the text returned via + <span class="command"><strong>rndc</strong></span> was incorrectly truncated after the + first line, making it appear that only one NTA had been + added. This has been fixed. [GL #105] + </p> + </li> +<li class="listitem"> + <p> + <span class="command"><strong>named</strong></span> now rejects excessively large + incremental (IXFR) zone transfers in order to prevent + possible corruption of journal files which could cause + <span class="command"><strong>named</strong></span> to abort when loading zones. [GL #339] + </p> + </li> +<li class="listitem"> + <p> + <span class="command"><strong>rndc reload</strong></span> could cause <span class="command"><strong>named</strong></span> + to leak memory if it was invoked before the zone loading actions + from a previous <span class="command"><strong>rndc reload</strong></span> command were + completed. [RT #47076] + </p> + </li> +</ul></div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="end_of_life"></a>End of Life</h3></div></div></div> + <p> + BIND 9.11 (Extended Support Version) will be supported until at + least December, 2021. + See <a class="link" href="https://www.isc.org/downloads/software-support-policy/" target="_top">https://www.isc.org/downloads/software-support-policy/</a> for details of ISC's software support policy. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="relnotes_thanks"></a>Thank You</h3></div></div></div> + + <p> + Thank you to everyone who assisted us in making this release possible. + If you would like to contribute to ISC to assist us in continuing to + make quality open source software, please visit our donations page at + <a class="link" href="http://www.isc.org/donate/" target="_top">http://www.isc.org/donate/</a>. + </p> + </div> +</div> +</div></body> +</html> diff --git a/doc/arm/notes.pdf b/doc/arm/notes.pdf Binary files differnew file mode 100644 index 0000000..84c7265 --- /dev/null +++ b/doc/arm/notes.pdf diff --git a/doc/arm/notes.txt b/doc/arm/notes.txt new file mode 100644 index 0000000..3db2e78 --- /dev/null +++ b/doc/arm/notes.txt @@ -0,0 +1,150 @@ +Release Notes for BIND Version 9.11.5-P4 + +Introduction + +This document summarizes changes since the last production release on the +BIND 9.11 (Extended Support Version) branch. Please see the CHANGES file +for a further list of bug fixes and other changes. + +Download + +The latest versions of BIND 9 software can always be found at http:// +www.isc.org/downloads/. There you will find additional information about +each release, source code, and pre-compiled versions for Microsoft Windows +operating systems. + +License Change + +With the release of BIND 9.11.0, ISC changed to the open source license +for BIND from the ISC license to the Mozilla Public License (MPL 2.0). + +The MPL-2.0 license requires that if you make changes to licensed software +(e.g. BIND) and distribute them outside your organization, that you +publish those changes under that same license. It does not require that +you publish or disclose anything other than the changes you made to our +software. + +This requirement will not affect anyone who is using BIND, with or without +modifications, without redistributing it, nor anyone redistributing it +without changes. Therefore, this change will be without consequence for +most individuals and organizations who are using BIND. + +Those unsure whether or not the license change affects their use of BIND, +or who wish to discuss how to comply with the license may contact ISC at +https://www.isc.org/mission/contact/. + +Legacy Windows No Longer Supported + +As of BIND 9.11.2, Windows XP and Windows 2003 are no longer supported +platforms for BIND; "XP" binaries are no longer available for download +from ISC. + +Security Fixes + + * named could crash during recursive processing of DNAME records when + deny-answer-aliases was in use. This flaw is disclosed in + CVE-2018-5740. [GL #387] + + * When recursion is enabled but the allow-recursion and + allow-query-cache ACLs are not specified, they should be limited to + local networks, but they were inadvertently set to match the default + allow-query, thus allowing remote queries. This flaw is disclosed in + CVE-2018-5738. [GL #309] + + * Code change #4964, intended to prevent double signatures when deleting + an inactive zone DNSKEY in some situations, introduced a new problem + during zone processing in which some delegation glue RRsets are + incorrectly identified as needing RRSIGs, which are then created for + them using the current active ZSK for the zone. In some, but not all + cases, the newly-signed RRsets are added to the zone's NSEC/NSEC3 + chain, but incompletely -- this can result in a broken chain, + affecting validation of proof of nonexistence for records in the zone. + [GL #771] + + * named could crash if it managed a DNSSEC security root with + managed-keys and the authoritative zone rolled the key to an algorithm + not supported by BIND 9. This flaw is disclosed in CVE-2018-5745. [GL + #780] + + * named leaked memory when processing a request with multiple Key Tag + EDNS options present. ISC would like to thank Toshifumi Sakaguchi for + bringing this to our attention. This flaw is disclosed in + CVE-2018-5744. [GL #772] + + * Zone transfer controls for writable DLZ zones were not effective as + the allowzonexfr method was not being called for such zones. This flaw + is disclosed in CVE-2019-6465. [GL #790] + +New Features + + * named now supports the "root key sentinel" mechanism. This enables + validating resolvers to indicate which trust anchors are configured + for the root, so that information about root key rollover status can + be gathered. To disable this feature, add root-key-sentinel no; to + named.conf. + + * Added the ability not to return a DNS COOKIE option when one is + present in the request. To prevent a cookie being returned, add + answer-cookie no; to named.conf. [GL #173] + + answer-cookie no is only intended as a temporary measure, for use when + named shares an IP address with other servers that do not yet support + DNS COOKIE. A mismatch between servers on the same address is not + expected to cause operational problems, but the option to disable + COOKIE responses so that all servers have the same behavior is + provided out of an abundance of caution. DNS COOKIE is an important + security mechanism, and should not be disabled unless absolutely + necessary. + + * Two new update policy rule types have been added krb5-selfsub and + ms-selfsub which allow machines with Kerberos principals to update the + name space at or below the machine names identified in the respective + principals. + +Removed Features + + * named will now log a warning if the old BIND now can be compiled + against libidn2 library to add IDNA2008 support. Previously BIND only + supported IDNA2003 using (now obsolete) idnkit-1 library. + +Feature Changes + + * dig +noidnin can be used to disable IDN processing on the input domain + name, when BIND is compiled with IDN support. + + * Multiple cookie-secret clause are now supported. The first + cookie-secret in named.conf is used to generate new server cookies. + Any others are used to accept old server cookies or those generated by + other servers using the matching cookie-secret. + + * The rndc nta command could not differentiate between views of the same + name but different class; this has been corrected with the addition of + a -class option. [GL #105] + +Bug Fixes + + * When a negative trust anchor was added to multiple views using rndc + nta, the text returned via rndc was incorrectly truncated after the + first line, making it appear that only one NTA had been added. This + has been fixed. [GL #105] + + * named now rejects excessively large incremental (IXFR) zone transfers + in order to prevent possible corruption of journal files which could + cause named to abort when loading zones. [GL #339] + + * rndc reload could cause named to leak memory if it was invoked before + the zone loading actions from a previous rndc reload command were + completed. [RT #47076] + +End of Life + +BIND 9.11 (Extended Support Version) will be supported until at least +December, 2021. See https://www.isc.org/downloads/software-support-policy/ +for details of ISC's software support policy. + +Thank You + +Thank you to everyone who assisted us in making this release possible. If +you would like to contribute to ISC to assist us in continuing to make +quality open source software, please visit our donations page at http:// +www.isc.org/donate/. diff --git a/doc/arm/notes.xml b/doc/arm/notes.xml new file mode 100644 index 0000000..029d9ef --- /dev/null +++ b/doc/arm/notes.xml @@ -0,0 +1,271 @@ +<!DOCTYPE book [ +<!ENTITY Scaron "Š"> +<!ENTITY ccaron "č"> +<!ENTITY aacute "á"> +<!ENTITY mdash "—"> +<!ENTITY ouml "ö">]> +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<section xmlns:db="http://docbook.org/ns/docbook" version="5.0"><info/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="noteversion.xml"/> + <section xml:id="relnotes_intro"><info><title>Introduction</title></info> + <para> + This document summarizes changes since the last production + release on the BIND 9.11 (Extended Support Version) branch. + Please see the <filename>CHANGES</filename> file for a further + list of bug fixes and other changes. + </para> + </section> + + <section xml:id="relnotes_download"><info><title>Download</title></info> + <para> + The latest versions of BIND 9 software can always be found at + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.isc.org/downloads/">http://www.isc.org/downloads/</link>. + There you will find additional information about each release, + source code, and pre-compiled versions for Microsoft Windows + operating systems. + </para> + </section> + + <section xml:id="relnotes_license"><info><title>License Change</title></info> + <para> + With the release of BIND 9.11.0, ISC changed to the open + source license for BIND from the ISC license to the Mozilla + Public License (MPL 2.0). + </para> + <para> + The MPL-2.0 license requires that if you make changes to + licensed software (e.g. BIND) and distribute them outside + your organization, that you publish those changes under that + same license. It does not require that you publish or disclose + anything other than the changes you made to our software. + </para> + <para> + This requirement will not affect anyone who is using BIND, with + or without modifications, without redistributing it, nor anyone + redistributing it without changes. Therefore, this change will be + without consequence for most individuals and organizations who are + using BIND. + </para> + <para> + Those unsure whether or not the license change affects their + use of BIND, or who wish to discuss how to comply with the + license may contact ISC at <link + xmlns:xlink="http://www.w3.org/1999/xlink" + xlink:href="https://www.isc.org/mission/contact/"> + https://www.isc.org/mission/contact/</link>. + </para> + </section> + + <section xml:id="win_support"><info><title>Legacy Windows No Longer Supported</title></info> + <para> + As of BIND 9.11.2, Windows XP and Windows 2003 are no longer supported + platforms for BIND; "XP" binaries are no longer available for download + from ISC. + </para> + </section> + + <section xml:id="relnotes_security"><info><title>Security Fixes</title></info> + <itemizedlist> + <listitem> + <para> + <command>named</command> could crash during recursive processing + of DNAME records when <command>deny-answer-aliases</command> was + in use. This flaw is disclosed in CVE-2018-5740. [GL #387] + </para> + </listitem> + <listitem> + <para> + When recursion is enabled but the <command>allow-recursion</command> + and <command>allow-query-cache</command> ACLs are not specified, they + should be limited to local networks, but they were inadvertently set + to match the default <command>allow-query</command>, thus allowing + remote queries. This flaw is disclosed in CVE-2018-5738. [GL #309] + </para> + </listitem> + <listitem> + <para> + Code change #4964, intended to prevent double signatures + when deleting an inactive zone DNSKEY in some situations, + introduced a new problem during zone processing in which + some delegation glue RRsets are incorrectly identified + as needing RRSIGs, which are then created for them using + the current active ZSK for the zone. In some, but not all + cases, the newly-signed RRsets are added to the zone's + NSEC/NSEC3 chain, but incompletely -- this can result in + a broken chain, affecting validation of proof of nonexistence + for records in the zone. [GL #771] + </para> + </listitem> + <listitem> + <para> + <command>named</command> could crash if it managed a DNSSEC + security root with <command>managed-keys</command> and the + authoritative zone rolled the key to an algorithm not supported + by BIND 9. This flaw is disclosed in CVE-2018-5745. [GL #780] + </para> + </listitem> + <listitem> + <para> + <command>named</command> leaked memory when processing a + request with multiple Key Tag EDNS options present. ISC + would like to thank Toshifumi Sakaguchi for bringing this + to our attention. This flaw is disclosed in CVE-2018-5744. + [GL #772] + </para> + </listitem> + <listitem> + <para> + Zone transfer controls for writable DLZ zones were not + effective as the <command>allowzonexfr</command> method was + not being called for such zones. This flaw is disclosed in + CVE-2019-6465. [GL #790] + </para> + </listitem> + </itemizedlist> + </section> + + <section xml:id="relnotes_features"><info><title>New Features</title></info> + <itemizedlist> + <listitem> + <para> + <command>named</command> now supports the "root key sentinel" + mechanism. This enables validating resolvers to indicate + which trust anchors are configured for the root, so that + information about root key rollover status can be gathered. + To disable this feature, add + <command>root-key-sentinel no;</command> to + <filename>named.conf</filename>. + </para> + </listitem> + <listitem> + <para> + Added the ability not to return a DNS COOKIE option when one + is present in the request. To prevent a cookie being returned, + add <command>answer-cookie no;</command> to + <filename>named.conf</filename>. [GL #173] + </para> + <para> + <command>answer-cookie no</command> is only intended as a + temporary measure, for use when <command>named</command> + shares an IP address with other servers that do not yet + support DNS COOKIE. A mismatch between servers on the + same address is not expected to cause operational problems, + but the option to disable COOKIE responses so that all + servers have the same behavior is provided out of an + abundance of caution. DNS COOKIE is an important security + mechanism, and should not be disabled unless absolutely + necessary. + </para> + </listitem> + <listitem> + <para> + Two new update policy rule types have been added + <command>krb5-selfsub</command> and <command>ms-selfsub</command> + which allow machines with Kerberos principals to update + the name space at or below the machine names identified + in the respective principals. + </para> + </listitem> + </itemizedlist> + </section> + + <section xml:id="relnotes_removed"><info><title>Removed Features</title></info> + <itemizedlist> + <listitem> + <para> + <command>named</command> will now log a warning if the old + BIND now can be compiled against libidn2 library to add + IDNA2008 support. Previously BIND only supported IDNA2003 + using (now obsolete) idnkit-1 library. + </para> + </listitem> + </itemizedlist> + </section> + + <section xml:id="relnotes_changes"><info><title>Feature Changes</title></info> + <itemizedlist> + <listitem> + <para> + <command>dig +noidnin</command> can be used to disable IDN + processing on the input domain name, when BIND is compiled + with IDN support. + </para> + </listitem> + <listitem> + <para> + Multiple <command>cookie-secret</command> clause are now + supported. The first <command>cookie-secret</command> in + <filename>named.conf</filename> is used to generate new + server cookies. Any others are used to accept old server + cookies or those generated by other servers using the + matching <command>cookie-secret</command>. + </para> + </listitem> + <listitem> + <para> + The <command>rndc nta</command> command could not differentiate + between views of the same name but different class; this + has been corrected with the addition of a <command>-class</command> + option. [GL #105] + </para> + </listitem> + </itemizedlist> + </section> + + <section xml:id="relnotes_bugs"><info><title>Bug Fixes</title></info> + <itemizedlist> + <listitem> + <para> + When a negative trust anchor was added to multiple views + using <command>rndc nta</command>, the text returned via + <command>rndc</command> was incorrectly truncated after the + first line, making it appear that only one NTA had been + added. This has been fixed. [GL #105] + </para> + </listitem> + <listitem> + <para> + <command>named</command> now rejects excessively large + incremental (IXFR) zone transfers in order to prevent + possible corruption of journal files which could cause + <command>named</command> to abort when loading zones. [GL #339] + </para> + </listitem> + <listitem> + <para> + <command>rndc reload</command> could cause <command>named</command> + to leak memory if it was invoked before the zone loading actions + from a previous <command>rndc reload</command> command were + completed. [RT #47076] + </para> + </listitem> + </itemizedlist> + </section> + + <section xml:id="end_of_life"><info><title>End of Life</title></info> + <para> + BIND 9.11 (Extended Support Version) will be supported until at + least December, 2021. + See <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.isc.org/downloads/software-support-policy/">https://www.isc.org/downloads/software-support-policy/</link> for details of ISC's software support policy. + </para> + </section> + <section xml:id="relnotes_thanks"><info><title>Thank You</title></info> + + <para> + Thank you to everyone who assisted us in making this release possible. + If you would like to contribute to ISC to assist us in continuing to + make quality open source software, please visit our donations page at + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.isc.org/donate/">http://www.isc.org/donate/</link>. + </para> + </section> +</section> diff --git a/doc/arm/noteversion.xml.in b/doc/arm/noteversion.xml.in new file mode 100644 index 0000000..14bbba4 --- /dev/null +++ b/doc/arm/noteversion.xml.in @@ -0,0 +1,12 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<title>Release Notes for BIND Version @BIND9_VERSION@</title> diff --git a/doc/arm/options.grammar.xml b/doc/arm/options.grammar.xml new file mode 100644 index 0000000..16d332a --- /dev/null +++ b/doc/arm/options.grammar.xml @@ -0,0 +1,289 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Generated by doc/misc/docbook-options.pl --> + +<programlisting> +<command>options</command> { + <command>acache-cleaning-interval</command> <replaceable>integer</replaceable>; + <command>acache-enable</command> <replaceable>boolean</replaceable>; + <command>additional-from-auth</command> <replaceable>boolean</replaceable>; + <command>additional-from-cache</command> <replaceable>boolean</replaceable>; + <command>allow-new-zones</command> <replaceable>boolean</replaceable>; + <command>allow-notify</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>allow-query</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>allow-query-cache</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>allow-query-cache-on</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>allow-query-on</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>allow-recursion</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>allow-recursion-on</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>allow-transfer</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>allow-update</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>allow-update-forwarding</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>also-notify</command> [ port <replaceable>integer</replaceable> ] [ dscp <replaceable>integer</replaceable> ] { ( <replaceable>masters</replaceable> | + <replaceable>ipv4_address</replaceable> [ port <replaceable>integer</replaceable> ] | <replaceable>ipv6_address</replaceable> [ port + <replaceable>integer</replaceable> ] ) [ key <replaceable>string</replaceable> ]; ... }; + <command>alt-transfer-source</command> ( <replaceable>ipv4_address</replaceable> | * ) [ port ( <replaceable>integer</replaceable> | * ) + ] [ dscp <replaceable>integer</replaceable> ]; + <command>alt-transfer-source-v6</command> ( <replaceable>ipv6_address</replaceable> | * ) [ port ( <replaceable>integer</replaceable> | + * ) ] [ dscp <replaceable>integer</replaceable> ]; + <command>answer-cookie</command> <replaceable>boolean</replaceable>; + <command>attach-cache</command> <replaceable>string</replaceable>; + <command>auth-nxdomain</command> <replaceable>boolean</replaceable>; // default changed + <command>auto-dnssec</command> ( allow | maintain | off ); + <command>automatic-interface-scan</command> <replaceable>boolean</replaceable>; + <command>avoid-v4-udp-ports</command> { <replaceable>portrange</replaceable>; ... }; + <command>avoid-v6-udp-ports</command> { <replaceable>portrange</replaceable>; ... }; + <command>bindkeys-file</command> <replaceable>quoted_string</replaceable>; + <command>blackhole</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>cache-file</command> <replaceable>quoted_string</replaceable>; + <command>catalog-zones</command> { zone <replaceable>quoted_string</replaceable> [ default-masters [ port + <replaceable>integer</replaceable> ] [ dscp <replaceable>integer</replaceable> ] { ( <replaceable>masters</replaceable> | <replaceable>ipv4_address</replaceable> [ + <command>port</command> <replaceable>integer</replaceable> ] | <replaceable>ipv6_address</replaceable> [ port <replaceable>integer</replaceable> ] ) [ key + <replaceable>string</replaceable> ]; ... } ] [ zone-directory <replaceable>quoted_string</replaceable> ] [ + <command>in-memory</command> <replaceable>boolean</replaceable> ] [ min-update-interval <replaceable>integer</replaceable> ]; ... }; + <command>check-dup-records</command> ( fail | warn | ignore ); + <command>check-integrity</command> <replaceable>boolean</replaceable>; + <command>check-mx</command> ( fail | warn | ignore ); + <command>check-mx-cname</command> ( fail | warn | ignore ); + <command>check-names</command> ( master | slave | response + ) ( fail | warn | ignore ); + <command>check-sibling</command> <replaceable>boolean</replaceable>; + <command>check-spf</command> ( warn | ignore ); + <command>check-srv-cname</command> ( fail | warn | ignore ); + <command>check-wildcard</command> <replaceable>boolean</replaceable>; + <command>cleaning-interval</command> <replaceable>integer</replaceable>; + <command>clients-per-query</command> <replaceable>integer</replaceable>; + <command>cookie-algorithm</command> ( aes | sha1 | sha256 ); + <command>cookie-secret</command> <replaceable>string</replaceable>; + <command>coresize</command> ( default | unlimited | <replaceable>sizeval</replaceable> ); + <command>datasize</command> ( default | unlimited | <replaceable>sizeval</replaceable> ); + <command>deny-answer-addresses</command> { <replaceable>address_match_element</replaceable>; ... } [ + <command>except-from</command> { <replaceable>quoted_string</replaceable>; ... } ]; + <command>deny-answer-aliases</command> { <replaceable>quoted_string</replaceable>; ... } [ except-from { + <replaceable>quoted_string</replaceable>; ... } ]; + <command>dialup</command> ( notify | notify-passive | passive | refresh | <replaceable>boolean</replaceable> ); + <command>directory</command> <replaceable>quoted_string</replaceable>; + <command>disable-algorithms</command> <replaceable>string</replaceable> { <replaceable>string</replaceable>; + ... }; + <command>disable-ds-digests</command> <replaceable>string</replaceable> { <replaceable>string</replaceable>; + ... }; + <command>disable-empty-zone</command> <replaceable>string</replaceable>; + <command>dns64</command> <replaceable>netprefix</replaceable> { + <command>break-dnssec</command> <replaceable>boolean</replaceable>; + <command>clients</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>exclude</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>mapped</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>recursive-only</command> <replaceable>boolean</replaceable>; + <command>suffix</command> <replaceable>ipv6_address</replaceable>; + }; + <command>dns64-contact</command> <replaceable>string</replaceable>; + <command>dns64-server</command> <replaceable>string</replaceable>; + <command>dnssec-accept-expired</command> <replaceable>boolean</replaceable>; + <command>dnssec-dnskey-kskonly</command> <replaceable>boolean</replaceable>; + <command>dnssec-enable</command> <replaceable>boolean</replaceable>; + <command>dnssec-loadkeys-interval</command> <replaceable>integer</replaceable>; + <command>dnssec-lookaside</command> ( <replaceable>string</replaceable> trust-anchor + <replaceable>string</replaceable> | auto | no ); + <command>dnssec-must-be-secure</command> <replaceable>string</replaceable> <replaceable>boolean</replaceable>; + <command>dnssec-secure-to-insecure</command> <replaceable>boolean</replaceable>; + <command>dnssec-update-mode</command> ( maintain | no-resign ); + <command>dnssec-validation</command> ( yes | no | auto ); + <command>dnstap</command> { ( all | auth | client | forwarder | + <command>resolver</command> ) [ ( query | response ) ]; ... }; + <command>dnstap-identity</command> ( <replaceable>quoted_string</replaceable> | none | + <command>hostname</command> ); + <command>dnstap-output</command> ( file | unix ) <replaceable>quoted_string</replaceable>; + <command>dnstap-version</command> ( <replaceable>quoted_string</replaceable> | none ); + <command>dscp</command> <replaceable>integer</replaceable>; + <command>dual-stack-servers</command> [ port <replaceable>integer</replaceable> ] { ( <replaceable>quoted_string</replaceable> [ port + <replaceable>integer</replaceable> ] [ dscp <replaceable>integer</replaceable> ] | <replaceable>ipv4_address</replaceable> [ port + <replaceable>integer</replaceable> ] [ dscp <replaceable>integer</replaceable> ] | <replaceable>ipv6_address</replaceable> [ port + <replaceable>integer</replaceable> ] [ dscp <replaceable>integer</replaceable> ] ); ... }; + <command>dump-file</command> <replaceable>quoted_string</replaceable>; + <command>edns-udp-size</command> <replaceable>integer</replaceable>; + <command>empty-contact</command> <replaceable>string</replaceable>; + <command>empty-server</command> <replaceable>string</replaceable>; + <command>empty-zones-enable</command> <replaceable>boolean</replaceable>; + <command>fetch-quota-params</command> <replaceable>integer</replaceable> <replaceable>fixedpoint</replaceable> <replaceable>fixedpoint</replaceable> <replaceable>fixedpoint</replaceable>; + <command>fetches-per-server</command> <replaceable>integer</replaceable> [ ( drop | fail ) ]; + <command>fetches-per-zone</command> <replaceable>integer</replaceable> [ ( drop | fail ) ]; + <command>files</command> ( default | unlimited | <replaceable>sizeval</replaceable> ); + <command>filter-aaaa</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>filter-aaaa-on-v4</command> ( break-dnssec | <replaceable>boolean</replaceable> ); + <command>filter-aaaa-on-v6</command> ( break-dnssec | <replaceable>boolean</replaceable> ); + <command>flush-zones-on-shutdown</command> <replaceable>boolean</replaceable>; + <command>forward</command> ( first | only ); + <command>forwarders</command> [ port <replaceable>integer</replaceable> ] [ dscp <replaceable>integer</replaceable> ] { ( <replaceable>ipv4_address</replaceable> + | <replaceable>ipv6_address</replaceable> ) [ port <replaceable>integer</replaceable> ] [ dscp <replaceable>integer</replaceable> ]; ... }; + <command>fstrm-set-buffer-hint</command> <replaceable>integer</replaceable>; + <command>fstrm-set-flush-timeout</command> <replaceable>integer</replaceable>; + <command>fstrm-set-input-queue-size</command> <replaceable>integer</replaceable>; + <command>fstrm-set-output-notify-threshold</command> <replaceable>integer</replaceable>; + <command>fstrm-set-output-queue-model</command> ( mpsc | spsc ); + <command>fstrm-set-output-queue-size</command> <replaceable>integer</replaceable>; + <command>fstrm-set-reopen-interval</command> <replaceable>integer</replaceable>; + <command>geoip-directory</command> ( <replaceable>quoted_string</replaceable> | none ); + <command>geoip-use-ecs</command> <replaceable>boolean</replaceable>; + <command>heartbeat-interval</command> <replaceable>integer</replaceable>; + <command>hostname</command> ( <replaceable>quoted_string</replaceable> | none ); + <command>inline-signing</command> <replaceable>boolean</replaceable>; + <command>interface-interval</command> <replaceable>integer</replaceable>; + <command>ixfr-from-differences</command> ( master | slave | <replaceable>boolean</replaceable> ); + <command>keep-response-order</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>key-directory</command> <replaceable>quoted_string</replaceable>; + <command>lame-ttl</command> <replaceable>ttlval</replaceable>; + <command>listen-on</command> [ port <replaceable>integer</replaceable> ] [ dscp + <replaceable>integer</replaceable> ] { + <replaceable>address_match_element</replaceable>; ... }; + <command>listen-on-v6</command> [ port <replaceable>integer</replaceable> ] [ dscp + <replaceable>integer</replaceable> ] { + <replaceable>address_match_element</replaceable>; ... }; + <command>lmdb-mapsize</command> <replaceable>sizeval</replaceable>; + <command>lock-file</command> ( <replaceable>quoted_string</replaceable> | none ); + <command>managed-keys-directory</command> <replaceable>quoted_string</replaceable>; + <command>masterfile-format</command> ( map | raw | text ); + <command>masterfile-style</command> ( full | relative ); + <command>match-mapped-addresses</command> <replaceable>boolean</replaceable>; + <command>max-acache-size</command> ( unlimited | <replaceable>sizeval</replaceable> ); + <command>max-cache-size</command> ( default | unlimited | <replaceable>sizeval</replaceable> | <replaceable>percentage</replaceable> ); + <command>max-cache-ttl</command> <replaceable>integer</replaceable>; + <command>max-clients-per-query</command> <replaceable>integer</replaceable>; + <command>max-journal-size</command> ( unlimited | <replaceable>sizeval</replaceable> ); + <command>max-ncache-ttl</command> <replaceable>integer</replaceable>; + <command>max-records</command> <replaceable>integer</replaceable>; + <command>max-recursion-depth</command> <replaceable>integer</replaceable>; + <command>max-recursion-queries</command> <replaceable>integer</replaceable>; + <command>max-refresh-time</command> <replaceable>integer</replaceable>; + <command>max-retry-time</command> <replaceable>integer</replaceable>; + <command>max-rsa-exponent-size</command> <replaceable>integer</replaceable>; + <command>max-transfer-idle-in</command> <replaceable>integer</replaceable>; + <command>max-transfer-idle-out</command> <replaceable>integer</replaceable>; + <command>max-transfer-time-in</command> <replaceable>integer</replaceable>; + <command>max-transfer-time-out</command> <replaceable>integer</replaceable>; + <command>max-udp-size</command> <replaceable>integer</replaceable>; + <command>max-zone-ttl</command> ( unlimited | <replaceable>ttlval</replaceable> ); + <command>memstatistics</command> <replaceable>boolean</replaceable>; + <command>memstatistics-file</command> <replaceable>quoted_string</replaceable>; + <command>message-compression</command> <replaceable>boolean</replaceable>; + <command>min-refresh-time</command> <replaceable>integer</replaceable>; + <command>min-retry-time</command> <replaceable>integer</replaceable>; + <command>minimal-any</command> <replaceable>boolean</replaceable>; + <command>minimal-responses</command> ( no-auth | no-auth-recursive | <replaceable>boolean</replaceable> ); + <command>multi-master</command> <replaceable>boolean</replaceable>; + <command>no-case-compress</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>nocookie-udp-size</command> <replaceable>integer</replaceable>; + <command>notify</command> ( explicit | master-only | <replaceable>boolean</replaceable> ); + <command>notify-delay</command> <replaceable>integer</replaceable>; + <command>notify-rate</command> <replaceable>integer</replaceable>; + <command>notify-source</command> ( <replaceable>ipv4_address</replaceable> | * ) [ port ( <replaceable>integer</replaceable> | * ) ] [ + <command>dscp</command> <replaceable>integer</replaceable> ]; + <command>notify-source-v6</command> ( <replaceable>ipv6_address</replaceable> | * ) [ port ( <replaceable>integer</replaceable> | * ) ] + [ dscp <replaceable>integer</replaceable> ]; + <command>notify-to-soa</command> <replaceable>boolean</replaceable>; + <command>nta-lifetime</command> <replaceable>ttlval</replaceable>; + <command>nta-recheck</command> <replaceable>ttlval</replaceable>; + <command>nxdomain-redirect</command> <replaceable>string</replaceable>; + <command>pid-file</command> ( <replaceable>quoted_string</replaceable> | none ); + <command>port</command> <replaceable>integer</replaceable>; + <command>preferred-glue</command> <replaceable>string</replaceable>; + <command>prefetch</command> <replaceable>integer</replaceable> [ <replaceable>integer</replaceable> ]; + <command>provide-ixfr</command> <replaceable>boolean</replaceable>; + <command>query-source</command> ( ( [ address ] ( <replaceable>ipv4_address</replaceable> | * ) [ port ( + <replaceable>integer</replaceable> | * ) ] ) | ( [ [ address ] ( <replaceable>ipv4_address</replaceable> | * ) ] + <command>port</command> ( <replaceable>integer</replaceable> | * ) ) ) [ dscp <replaceable>integer</replaceable> ]; + <command>query-source-v6</command> ( ( [ address ] ( <replaceable>ipv6_address</replaceable> | * ) [ port ( + <replaceable>integer</replaceable> | * ) ] ) | ( [ [ address ] ( <replaceable>ipv6_address</replaceable> | * ) ] + <command>port</command> ( <replaceable>integer</replaceable> | * ) ) ) [ dscp <replaceable>integer</replaceable> ]; + <command>querylog</command> <replaceable>boolean</replaceable>; + <command>random-device</command> <replaceable>quoted_string</replaceable>; + <command>rate-limit</command> { + <command>all-per-second</command> <replaceable>integer</replaceable>; + <command>errors-per-second</command> <replaceable>integer</replaceable>; + <command>exempt-clients</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>ipv4-prefix-length</command> <replaceable>integer</replaceable>; + <command>ipv6-prefix-length</command> <replaceable>integer</replaceable>; + <command>log-only</command> <replaceable>boolean</replaceable>; + <command>max-table-size</command> <replaceable>integer</replaceable>; + <command>min-table-size</command> <replaceable>integer</replaceable>; + <command>nodata-per-second</command> <replaceable>integer</replaceable>; + <command>nxdomains-per-second</command> <replaceable>integer</replaceable>; + <command>qps-scale</command> <replaceable>integer</replaceable>; + <command>referrals-per-second</command> <replaceable>integer</replaceable>; + <command>responses-per-second</command> <replaceable>integer</replaceable>; + <command>slip</command> <replaceable>integer</replaceable>; + <command>window</command> <replaceable>integer</replaceable>; + }; + <command>recursing-file</command> <replaceable>quoted_string</replaceable>; + <command>recursion</command> <replaceable>boolean</replaceable>; + <command>recursive-clients</command> <replaceable>integer</replaceable>; + <command>request-expire</command> <replaceable>boolean</replaceable>; + <command>request-ixfr</command> <replaceable>boolean</replaceable>; + <command>request-nsid</command> <replaceable>boolean</replaceable>; + <command>require-server-cookie</command> <replaceable>boolean</replaceable>; + <command>reserved-sockets</command> <replaceable>integer</replaceable>; + <command>resolver-query-timeout</command> <replaceable>integer</replaceable>; + <command>response-policy</command> { zone <replaceable>quoted_string</replaceable> [ log <replaceable>boolean</replaceable> ] [ + <command>max-policy-ttl</command> <replaceable>integer</replaceable> ] [ policy ( cname | disabled | drop | + <command>given</command> | no-op | nodata | nxdomain | passthru | tcp-only + <replaceable>quoted_string</replaceable> ) ] [ recursive-only <replaceable>boolean</replaceable> ]; ... } [ + <command>break-dnssec</command> <replaceable>boolean</replaceable> ] [ max-policy-ttl <replaceable>integer</replaceable> ] [ + <command>min-ns-dots</command> <replaceable>integer</replaceable> ] [ nsip-wait-recurse <replaceable>boolean</replaceable> ] [ + <command>qname-wait-recurse</command> <replaceable>boolean</replaceable> ] [ recursive-only <replaceable>boolean</replaceable> ]; + <command>root-delegation-only</command> [ exclude { <replaceable>quoted_string</replaceable>; ... } ]; + <command>root-key-sentinel</command> <replaceable>boolean</replaceable>; + <command>rrset-order</command> { [ class <replaceable>string</replaceable> ] [ type <replaceable>string</replaceable> ] [ name + <replaceable>quoted_string</replaceable> ] <replaceable>string</replaceable> <replaceable>string</replaceable>; ... }; + <command>secroots-file</command> <replaceable>quoted_string</replaceable>; + <command>send-cookie</command> <replaceable>boolean</replaceable>; + <command>serial-query-rate</command> <replaceable>integer</replaceable>; + <command>serial-update-method</command> ( date | increment | unixtime ); + <command>server-id</command> ( <replaceable>quoted_string</replaceable> | none | hostname ); + <command>servfail-ttl</command> <replaceable>ttlval</replaceable>; + <command>session-keyalg</command> <replaceable>string</replaceable>; + <command>session-keyfile</command> ( <replaceable>quoted_string</replaceable> | none ); + <command>session-keyname</command> <replaceable>string</replaceable>; + <command>sig-signing-nodes</command> <replaceable>integer</replaceable>; + <command>sig-signing-signatures</command> <replaceable>integer</replaceable>; + <command>sig-signing-type</command> <replaceable>integer</replaceable>; + <command>sig-validity-interval</command> <replaceable>integer</replaceable> [ <replaceable>integer</replaceable> ]; + <command>sortlist</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>stacksize</command> ( default | unlimited | <replaceable>sizeval</replaceable> ); + <command>startup-notify-rate</command> <replaceable>integer</replaceable>; + <command>statistics-file</command> <replaceable>quoted_string</replaceable>; + <command>tcp-clients</command> <replaceable>integer</replaceable>; + <command>tcp-listen-queue</command> <replaceable>integer</replaceable>; + <command>tkey-dhkey</command> <replaceable>quoted_string</replaceable> <replaceable>integer</replaceable>; + <command>tkey-domain</command> <replaceable>quoted_string</replaceable>; + <command>tkey-gssapi-credential</command> <replaceable>quoted_string</replaceable>; + <command>tkey-gssapi-keytab</command> <replaceable>quoted_string</replaceable>; + <command>transfer-format</command> ( many-answers | one-answer ); + <command>transfer-message-size</command> <replaceable>integer</replaceable>; + <command>transfer-source</command> ( <replaceable>ipv4_address</replaceable> | * ) [ port ( <replaceable>integer</replaceable> | * ) ] [ + <command>dscp</command> <replaceable>integer</replaceable> ]; + <command>transfer-source-v6</command> ( <replaceable>ipv6_address</replaceable> | * ) [ port ( <replaceable>integer</replaceable> | * ) + ] [ dscp <replaceable>integer</replaceable> ]; + <command>transfers-in</command> <replaceable>integer</replaceable>; + <command>transfers-out</command> <replaceable>integer</replaceable>; + <command>transfers-per-ns</command> <replaceable>integer</replaceable>; + <command>trust-anchor-telemetry</command> <replaceable>boolean</replaceable>; // experimental + <command>try-tcp-refresh</command> <replaceable>boolean</replaceable>; + <command>update-check-ksk</command> <replaceable>boolean</replaceable>; + <command>use-alt-transfer-source</command> <replaceable>boolean</replaceable>; + <command>use-v4-udp-ports</command> { <replaceable>portrange</replaceable>; ... }; + <command>use-v6-udp-ports</command> { <replaceable>portrange</replaceable>; ... }; + <command>v6-bias</command> <replaceable>integer</replaceable>; + <command>version</command> ( <replaceable>quoted_string</replaceable> | none ); + <command>zero-no-soa-ttl</command> <replaceable>boolean</replaceable>; + <command>zero-no-soa-ttl-cache</command> <replaceable>boolean</replaceable>; + <command>zone-statistics</command> ( full | terse | none | <replaceable>boolean</replaceable> ); +}; +</programlisting> diff --git a/doc/arm/pkcs11.xml b/doc/arm/pkcs11.xml new file mode 100644 index 0000000..973845f --- /dev/null +++ b/doc/arm/pkcs11.xml @@ -0,0 +1,631 @@ +<!DOCTYPE book [ +<!ENTITY mdash "—">]> +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Converted by db4-upgrade version 1.0 --> +<section xmlns:db="http://docbook.org/ns/docbook" version="5.0" xml:id="pkcs11"><info><title>PKCS#11 (Cryptoki) support</title></info> + + <para> + PKCS#11 (Public Key Cryptography Standard #11) defines a + platform-independent API for the control of hardware security + modules (HSMs) and other cryptographic support devices. + </para> + <para> + BIND 9 is known to work with three HSMs: The AEP Keyper, which has + been tested with Debian Linux, Solaris x86 and Windows Server 2003; + the Thales nShield, tested with Debian Linux; and the Sun SCA 6000 + cryptographic acceleration board, tested with Solaris x86. In + addition, BIND can be used with all current versions of SoftHSM, + a software-based HSM simulator library produced by the OpenDNSSEC + project. + </para> + <para> + PKCS#11 makes use of a "provider library": a dynamically loadable + library which provides a low-level PKCS#11 interface to drive the HSM + hardware. The PKCS#11 provider library comes from the HSM vendor, and + it is specific to the HSM to be controlled. + </para> + <para> + There are two available mechanisms for PKCS#11 support in BIND 9: + OpenSSL-based PKCS#11 and native PKCS#11. When using the first + mechanism, BIND uses a modified version of OpenSSL, which loads + the provider library and operates the HSM indirectly; any + cryptographic operations not supported by the HSM can be carried + out by OpenSSL instead. The second mechanism enables BIND to bypass + OpenSSL completely; BIND loads the provider library itself, and uses + the PKCS#11 API to drive the HSM directly. + </para> + <section><info><title>Prerequisites</title></info> + + <para> + See the documentation provided by your HSM vendor for + information about installing, initializing, testing and + troubleshooting the HSM. + </para> + </section> + <section><info><title>Native PKCS#11</title></info> + + <para> + Native PKCS#11 mode will only work with an HSM capable of carrying + out <emphasis>every</emphasis> cryptographic operation BIND 9 may + need. The HSM's provider library must have a complete implementation + of the PKCS#11 API, so that all these functions are accessible. As of + this writing, only the Thales nShield HSM and SoftHSMv2 can be used + in this fashion. For other HSMs, including the AEP Keyper, Sun SCA + 6000 and older versions of SoftHSM, use OpenSSL-based PKCS#11. + (Note: Eventually, when more HSMs become capable of supporting + native PKCS#11, it is expected that OpenSSL-based PKCS#11 will + be deprecated.) + </para> + <para> + To build BIND with native PKCS#11, configure as follows: + </para> + <screen> +$ <userinput>cd bind9</userinput> +$ <userinput>./configure --enable-native-pkcs11 \ + --with-pkcs11=<replaceable>provider-library-path</replaceable></userinput> + </screen> + <para> + This will cause all BIND tools, including <command>named</command> + and the <command>dnssec-*</command> and <command>pkcs11-*</command> + tools, to use the PKCS#11 provider library specified in + <replaceable>provider-library-path</replaceable> for cryptography. + (The provider library path can be overridden using the + <option>-E</option> in <command>named</command> and the + <command>dnssec-*</command> tools, or the <option>-m</option> in + the <command>pkcs11-*</command> tools.) + </para> + <section><info><title>Building SoftHSMv2</title></info> + + <para> + SoftHSMv2, the latest development version of SoftHSM, is available + from + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://github.com/opendnssec/SoftHSMv2"> + https://github.com/opendnssec/SoftHSMv2 + </link>. + It is a software library developed by the OpenDNSSEC project + (<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.opendnssec.org"> + http://www.opendnssec.org + </link>) + which provides a PKCS#11 interface to a virtual HSM, implemented in + the form of a SQLite3 database on the local filesystem. It provides + less security than a true HSM, but it allows you to experiment with + native PKCS#11 when an HSM is not available. SoftHSMv2 can be + configured to use either OpenSSL or the Botan library to perform + cryptographic functions, but when using it for native PKCS#11 in + BIND, OpenSSL is required. + </para> + <para> + By default, the SoftHSMv2 configuration file is + <replaceable>prefix</replaceable>/etc/softhsm2.conf (where + <replaceable>prefix</replaceable> is configured at compile time). + This location can be overridden by the SOFTHSM2_CONF environment + variable. The SoftHSMv2 cryptographic store must be installed and + initialized before using it with BIND. + </para> + <screen> +$ <userinput> cd SoftHSMv2 </userinput> +$ <userinput> configure --with-crypto-backend=openssl --prefix=/opt/pkcs11/usr --enable-gost </userinput> +$ <userinput> make </userinput> +$ <userinput> make install </userinput> +$ <userinput> /opt/pkcs11/usr/bin/softhsm-util --init-token 0 --slot 0 --label softhsmv2 </userinput> + </screen> + </section> + </section> + <section><info><title>OpenSSL-based PKCS#11</title></info> + + <para> + OpenSSL-based PKCS#11 mode uses a modified version of the + OpenSSL library; stock OpenSSL does not fully support PKCS#11. + ISC provides a patch to OpenSSL to correct this. This patch is + based on work originally done by the OpenSolaris project; it has been + modified by ISC to provide new features such as PIN management and + key-by-reference. + </para> + <para> + There are two "flavors" of PKCS#11 support provided by + the patched OpenSSL, one of which must be chosen at + configuration time. The correct choice depends on the HSM + hardware: + </para> + <itemizedlist> + <listitem> + <para> + Use 'crypto-accelerator' with HSMs that have hardware + cryptographic acceleration features, such as the SCA 6000 + board. This causes OpenSSL to run all supported + cryptographic operations in the HSM. + </para> + </listitem> + <listitem> + <para> + Use 'sign-only' with HSMs that are designed to + function primarily as secure key storage devices, but lack + hardware acceleration. These devices are highly secure, but + are not necessarily any faster at cryptography than the + system CPU — often, they are slower. It is therefore + most efficient to use them only for those cryptographic + functions that require access to the secured private key, + such as zone signing, and to use the system CPU for all + other computationally-intensive operations. The AEP Keyper + is an example of such a device. + </para> + </listitem> + </itemizedlist> + <para> + The modified OpenSSL code is included in the BIND 9 release, + in the form of a context diff against the latest versions of + OpenSSL. OpenSSL 0.9.8, 1.0.0, 1.0.1 and 1.0.2 are supported; + there are separate diffs for each version. In the examples to + follow, we use OpenSSL 0.9.8, but the same methods work with + OpenSSL 1.0.0 through 1.0.2. + </para> + <note><simpara> + The OpenSSL patches as of this writing (January 2016) + support versions 0.9.8zh, 1.0.0t, 1.0.1q and 1.0.2f. + ISC will provide updated patches as new versions of OpenSSL + are released. The version number in the following examples + is expected to change. + </simpara></note> + <para> + Before building BIND 9 with PKCS#11 support, it will be + necessary to build OpenSSL with the patch in place, and configure + it with the path to your HSM's PKCS#11 provider library. + </para> + <section><info><title>Patching OpenSSL</title></info> + + <screen> +$ <userinput>wget <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="">http://www.openssl.org/source/openssl-0.9.8zc.tar.gz</link></userinput> + </screen> + <para>Extract the tarball:</para> + <screen> +$ <userinput>tar zxf openssl-0.9.8zc.tar.gz</userinput> +</screen> + <para>Apply the patch from the BIND 9 release:</para> + <screen> +$ <userinput>patch -p1 -d openssl-0.9.8zc \ + < bind9/bin/pkcs11/openssl-0.9.8zc-patch</userinput> +</screen> + <note><simpara> + The patch file may not be compatible with the + "patch" utility on all operating systems. You may need to + install GNU patch. + </simpara></note> + <para> + When building OpenSSL, place it in a non-standard + location so that it does not interfere with OpenSSL libraries + elsewhere on the system. In the following examples, we choose + to install into "/opt/pkcs11/usr". We will use this location + when we configure BIND 9. + </para> + <para> + Later, when building BIND 9, the location of the custom-built + OpenSSL library will need to be specified via configure. + </para> + </section> + <section><info><title>Building OpenSSL for the AEP Keyper on Linux</title></info> + <!-- Example 1 --> + + <para> + The AEP Keyper is a highly secure key storage device, + but does not provide hardware cryptographic acceleration. It + can carry out cryptographic operations, but it is probably + slower than your system's CPU. Therefore, we choose the + 'sign-only' flavor when building OpenSSL. + </para> + <para> + The Keyper-specific PKCS#11 provider library is + delivered with the Keyper software. In this example, we place + it /opt/pkcs11/usr/lib: + </para> + <screen> +$ <userinput>cp pkcs11.GCC4.0.2.so.4.05 /opt/pkcs11/usr/lib/libpkcs11.so</userinput> +</screen> + <para> + The Keyper library requires threads, so we + must specify -pthread. + </para> + <screen> +$ <userinput>cd openssl-0.9.8zc</userinput> +$ <userinput>./Configure linux-x86_64 -pthread \ + --pk11-libname=/opt/pkcs11/usr/lib/libpkcs11.so \ + --pk11-flavor=sign-only \ + --prefix=/opt/pkcs11/usr</userinput> +</screen> + <para> + After configuring, run "<command>make</command>" + and "<command>make test</command>". If "<command>make + test</command>" fails with "pthread_atfork() not found", you forgot to + add the -pthread above. + </para> + </section> + <section><info><title>Building OpenSSL for the SCA 6000 on Solaris</title></info> + <!-- Example 2 --> + + <para> + The SCA-6000 PKCS#11 provider is installed as a system + library, libpkcs11. It is a true crypto accelerator, up to 4 + times faster than any CPU, so the flavor shall be + 'crypto-accelerator'. + </para> + <para> + In this example, we are building on Solaris x86 on an + AMD64 system. + </para> + <screen> +$ <userinput>cd openssl-0.9.8zc</userinput> +$ <userinput>./Configure solaris64-x86_64-cc \ + --pk11-libname=/usr/lib/64/libpkcs11.so \ + --pk11-flavor=crypto-accelerator \ + --prefix=/opt/pkcs11/usr</userinput> +</screen> + <para> + (For a 32-bit build, use "solaris-x86-cc" and /usr/lib/libpkcs11.so.) + </para> + <para> + After configuring, run + <command>make</command> and + <command>make test</command>. + </para> + </section> + <section><info><title>Building OpenSSL for SoftHSM</title></info> + <!-- Example 3 --> + + <para> + SoftHSM (version 1) is a software library developed by the + OpenDNSSEC project + (<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.opendnssec.org"> + http://www.opendnssec.org + </link>) + which provides a + PKCS#11 interface to a virtual HSM, implemented in the form of + a SQLite3 database on the local filesystem. SoftHSM uses + the Botan library to perform cryptographic functions. Though + less secure than a true HSM, it can allow you to experiment + with PKCS#11 when an HSM is not available. + </para> + <para> + The SoftHSM cryptographic store must be installed and + initialized before using it with OpenSSL, and the SOFTHSM_CONF + environment variable must always point to the SoftHSM configuration + file: + </para> + <screen> +$ <userinput> cd softhsm-1.3.7 </userinput> +$ <userinput> configure --prefix=/opt/pkcs11/usr </userinput> +$ <userinput> make </userinput> +$ <userinput> make install </userinput> +$ <userinput> export SOFTHSM_CONF=/opt/pkcs11/softhsm.conf </userinput> +$ <userinput> echo "0:/opt/pkcs11/softhsm.db" > $SOFTHSM_CONF </userinput> +$ <userinput> /opt/pkcs11/usr/bin/softhsm --init-token 0 --slot 0 --label softhsm </userinput> +</screen> + <para> + SoftHSM can perform all cryptographic operations, but + since it only uses your system CPU, there is no advantage to using + it for anything but signing. Therefore, we choose the 'sign-only' + flavor when building OpenSSL. + </para> + <screen> +$ <userinput>cd openssl-0.9.8zc</userinput> +$ <userinput>./Configure linux-x86_64 -pthread \ + --pk11-libname=/opt/pkcs11/usr/lib/libsofthsm.so \ + --pk11-flavor=sign-only \ + --prefix=/opt/pkcs11/usr</userinput> +</screen> + <para> + After configuring, run "<command>make</command>" + and "<command>make test</command>". + </para> + </section> + <para> + Once you have built OpenSSL, run + "<command>apps/openssl engine pkcs11</command>" to confirm + that PKCS#11 support was compiled in correctly. The output + should be one of the following lines, depending on the flavor + selected: + </para> + <screen> + (pkcs11) PKCS #11 engine support (sign only) +</screen> + <para>Or:</para> + <screen> + (pkcs11) PKCS #11 engine support (crypto accelerator) +</screen> + <para> + Next, run + "<command>apps/openssl engine pkcs11 -t</command>". This will + attempt to initialize the PKCS#11 engine. If it is able to + do so successfully, it will report + <quote><literal>[ available ]</literal></quote>. + </para> + <para> + If the output is correct, run + "<command>make install</command>" which will install the + modified OpenSSL suite to <filename>/opt/pkcs11/usr</filename>. + </para> + <section><info><title>Configuring BIND 9 for Linux with the AEP Keyper</title></info> + <!-- Example 4 --> + + <para> + To link with the PKCS#11 provider, threads must be + enabled in the BIND 9 build. + </para> + <screen> +$ <userinput>cd ../bind9</userinput> +$ <userinput>./configure --enable-threads \ + --with-openssl=/opt/pkcs11/usr \ + --with-pkcs11=/opt/pkcs11/usr/lib/libpkcs11.so</userinput> +</screen> + </section> + <section><info><title>Configuring BIND 9 for Solaris with the SCA 6000</title></info> + <!-- Example 5 --> + + <para> + To link with the PKCS#11 provider, threads must be + enabled in the BIND 9 build. + </para> + <screen> +$ <userinput>cd ../bind9</userinput> +$ <userinput>./configure CC="cc -xarch=amd64" --enable-threads \ + --with-openssl=/opt/pkcs11/usr \ + --with-pkcs11=/usr/lib/64/libpkcs11.so</userinput> +</screen> + <para>(For a 32-bit build, omit CC="cc -xarch=amd64".)</para> + <para> + If configure complains about OpenSSL not working, you + may have a 32/64-bit architecture mismatch. Or, you may have + incorrectly specified the path to OpenSSL (it should be the + same as the --prefix argument to the OpenSSL + Configure). + </para> + </section> + <section><info><title>Configuring BIND 9 for SoftHSM</title></info> + <!-- Example 6 --> + + <screen> +$ <userinput>cd ../bind9</userinput> +$ <userinput>./configure --enable-threads \ + --with-openssl=/opt/pkcs11/usr \ + --with-pkcs11=/opt/pkcs11/usr/lib/libsofthsm.so</userinput> +</screen> + </section> + <para> + After configuring, run + "<command>make</command>", + "<command>make test</command>" and + "<command>make install</command>". + </para> + <para> + (Note: If "make test" fails in the "pkcs11" system test, you may + have forgotten to set the SOFTHSM_CONF environment variable.) + </para> + </section> + <section><info><title>PKCS#11 Tools</title></info> + + <para> + BIND 9 includes a minimal set of tools to operate the + HSM, including + <command>pkcs11-keygen</command> to generate a new key pair + within the HSM, + <command>pkcs11-list</command> to list objects currently + available, + <command>pkcs11-destroy</command> to remove objects, and + <command>pkcs11-tokens</command> to list available tokens. + </para> + <para> + In UNIX/Linux builds, these tools are built only if BIND + 9 is configured with the --with-pkcs11 option. (Note: If + --with-pkcs11 is set to "yes", rather than to the path of the + PKCS#11 provider, then the tools will be built but the + provider will be left undefined. Use the -m option or the + PKCS11_PROVIDER environment variable to specify the path to the + provider.) + </para> + </section> + <section><info><title>Using the HSM</title></info> + + <para> + For OpenSSL-based PKCS#11, we must first set up the runtime + environment so the OpenSSL and PKCS#11 libraries can be loaded: + </para> + <screen> +$ <userinput>export LD_LIBRARY_PATH=/opt/pkcs11/usr/lib:${LD_LIBRARY_PATH}</userinput> +</screen> + <para> + This causes <command>named</command> and other binaries to load + the OpenSSL library from <filename>/opt/pkcs11/usr/lib</filename> + rather than from the default location. This step is not necessary + when using native PKCS#11. + </para> + <para> + Some HSMs require other environment variables to be set. + For example, when operating an AEP Keyper, it is necessary to + specify the location of the "machine" file, which stores + information about the Keyper for use by the provider + library. If the machine file is in + <filename>/opt/Keyper/PKCS11Provider/machine</filename>, + use: + </para> + <screen> +$ <userinput>export KEYPER_LIBRARY_PATH=/opt/Keyper/PKCS11Provider</userinput> +</screen> + <para> + Such environment variables must be set whenever running + any tool that uses the HSM, including + <command>pkcs11-keygen</command>, + <command>pkcs11-list</command>, + <command>pkcs11-destroy</command>, + <command>dnssec-keyfromlabel</command>, + <command>dnssec-signzone</command>, + <command>dnssec-keygen</command>, and + <command>named</command>. + </para> + <para> + We can now create and use keys in the HSM. In this case, + we will create a 2048 bit key and give it the label + "sample-ksk": + </para> + <screen> +$ <userinput>pkcs11-keygen -b 2048 -l sample-ksk</userinput> +</screen> + <para>To confirm that the key exists:</para> + <screen> +$ <userinput>pkcs11-list</userinput> +Enter PIN: +object[0]: handle 2147483658 class 3 label[8] 'sample-ksk' id[0] +object[1]: handle 2147483657 class 2 label[8] 'sample-ksk' id[0] +</screen> + <para> + Before using this key to sign a zone, we must create a + pair of BIND 9 key files. The "dnssec-keyfromlabel" utility + does this. In this case, we will be using the HSM key + "sample-ksk" as the key-signing key for "example.net": + </para> + <screen> +$ <userinput>dnssec-keyfromlabel -l sample-ksk -f KSK example.net</userinput> +</screen> + <para> + The resulting K*.key and K*.private files can now be used + to sign the zone. Unlike normal K* files, which contain both + public and private key data, these files will contain only the + public key data, plus an identifier for the private key which + remains stored within the HSM. Signing with the private key takes + place inside the HSM. + </para> + <para> + If you wish to generate a second key in the HSM for use + as a zone-signing key, follow the same procedure above, using a + different keylabel, a smaller key size, and omitting "-f KSK" + from the dnssec-keyfromlabel arguments: + </para> + <para> + (Note: When using OpenSSL-based PKCS#11 the label is an arbitrary + string which identifies the key. With native PKCS#11, the label is + a PKCS#11 URI string which may include other details about the key + and the HSM, including its PIN. See + <xref linkend="man.dnssec-keyfromlabel"/> for details.) + </para> + <screen> +$ <userinput>pkcs11-keygen -b 1024 -l sample-zsk</userinput> +$ <userinput>dnssec-keyfromlabel -l sample-zsk example.net</userinput> +</screen> + <para> + Alternatively, you may prefer to generate a conventional + on-disk key, using dnssec-keygen: + </para> + <screen> +$ <userinput>dnssec-keygen example.net</userinput> +</screen> + <para> + This provides less security than an HSM key, but since + HSMs can be slow or cumbersome to use for security reasons, it + may be more efficient to reserve HSM keys for use in the less + frequent key-signing operation. The zone-signing key can be + rolled more frequently, if you wish, to compensate for a + reduction in key security. (Note: When using native PKCS#11, + there is no speed advantage to using on-disk keys, as cryptographic + operations will be done by the HSM regardless.) + </para> + <para> + Now you can sign the zone. (Note: If not using the -S + option to <command>dnssec-signzone</command>, it will be + necessary to add the contents of both <filename>K*.key</filename> + files to the zone master file before signing it.) + </para> + <screen> +$ <userinput>dnssec-signzone -S example.net</userinput> +Enter PIN: +Verifying the zone using the following algorithms: +NSEC3RSASHA1. +Zone signing complete: +Algorithm: NSEC3RSASHA1: ZSKs: 1, KSKs: 1 active, 0 revoked, 0 stand-by +example.net.signed +</screen> + </section> + <section><info><title>Specifying the engine on the command line</title></info> + + <para> + When using OpenSSL-based PKCS#11, the "engine" to be used by + OpenSSL can be specified in <command>named</command> and all of + the BIND <command>dnssec-*</command> tools by using the "-E + <engine>" command line option. If BIND 9 is built with + the --with-pkcs11 option, this option defaults to "pkcs11". + Specifying the engine will generally not be necessary unless + for some reason you wish to use a different OpenSSL + engine. + </para> + <para> + If you wish to disable use of the "pkcs11" engine — + for troubleshooting purposes, or because the HSM is unavailable + — set the engine to the empty string. For example: + </para> + <screen> +$ <userinput>dnssec-signzone -E '' -S example.net</userinput> +</screen> + <para> + This causes + <command>dnssec-signzone</command> to run as if it were compiled + without the --with-pkcs11 option. + </para> + <para> + When built with native PKCS#11 mode, the "engine" option has a + different meaning: it specifies the path to the PKCS#11 provider + library. This may be useful when testing a new provider library. + </para> + </section> + <section><info><title>Running named with automatic zone re-signing</title></info> + + <para> + If you want <command>named</command> to dynamically re-sign zones + using HSM keys, and/or to to sign new records inserted via nsupdate, + then <command>named</command> must have access to the HSM PIN. In OpenSSL-based PKCS#11, + this is accomplished by placing the PIN into the openssl.cnf file + (in the above examples, + <filename>/opt/pkcs11/usr/ssl/openssl.cnf</filename>). + </para> + <para> + The location of the openssl.cnf file can be overridden by + setting the OPENSSL_CONF environment variable before running + <command>named</command>. + </para> + <para>Sample openssl.cnf:</para> + <programlisting> + openssl_conf = openssl_def + [ openssl_def ] + engines = engine_section + [ engine_section ] + pkcs11 = pkcs11_section + [ pkcs11_section ] + PIN = <replaceable><PLACE PIN HERE></replaceable> +</programlisting> + <para> + This will also allow the dnssec-* tools to access the HSM + without PIN entry. (The pkcs11-* tools access the HSM directly, + not via OpenSSL, so a PIN will still be required to use + them.) + </para> + <para> + In native PKCS#11 mode, the PIN can be provided in a file specified + as an attribute of the key's label. For example, if a key had the label + <userinput>pkcs11:object=local-zsk;pin-source=/etc/hsmpin</userinput>, + then the PIN would be read from the file + <filename>/etc/hsmpin</filename>. + </para> + <warning> + <para> + Placing the HSM's PIN in a text file in this manner may reduce the + security advantage of using an HSM. Be sure this is what you want to + do before configuring the system in this way. + </para> + </warning> + </section> +</section> diff --git a/doc/arm/pkgversion.xml.in b/doc/arm/pkgversion.xml.in new file mode 100644 index 0000000..74abbfc --- /dev/null +++ b/doc/arm/pkgversion.xml.in @@ -0,0 +1,12 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + + <para>This version of the manual corresponds to BIND version @PACKAGE_VERSION@.</para> diff --git a/doc/arm/redirect.zoneopt.xml b/doc/arm/redirect.zoneopt.xml new file mode 100644 index 0000000..335cfa0 --- /dev/null +++ b/doc/arm/redirect.zoneopt.xml @@ -0,0 +1,27 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Generated by doc/misc/docbook-zoneopt.pl --> +<programlisting> +<command>zone</command> <replaceable>string</replaceable> [ <replaceable>class</replaceable> ] { + <command>type</command> redirect; + <command>allow-query</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>allow-query-on</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>dlz</command> <replaceable>string</replaceable>; + <command>file</command> <replaceable>quoted_string</replaceable>; + <command>masterfile-format</command> ( map | raw | text ); + <command>masterfile-style</command> ( full | relative ); + <command>masters</command> [ port <replaceable>integer</replaceable> ] [ dscp <replaceable>integer</replaceable> ] { ( <replaceable>masters</replaceable> | <replaceable>ipv4_address</replaceable> [ port <replaceable>integer</replaceable> ] | <replaceable>ipv6_address</replaceable> [ port <replaceable>integer</replaceable> ] ) [ key <replaceable>string</replaceable> ]; ... }; + <command>max-records</command> <replaceable>integer</replaceable>; + <command>max-zone-ttl</command> ( unlimited | <replaceable>ttlval</replaceable> ); + <command>zone-statistics</command> ( full | terse | none | <replaceable>boolean</replaceable> ); +}; +</programlisting> diff --git a/doc/arm/releaseinfo.xml.in b/doc/arm/releaseinfo.xml.in new file mode 100644 index 0000000..fa7a3cd --- /dev/null +++ b/doc/arm/releaseinfo.xml.in @@ -0,0 +1,12 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<releaseinfo>BIND Version @BIND9_VERSION@</releaseinfo> diff --git a/doc/arm/server.grammar.xml b/doc/arm/server.grammar.xml new file mode 100644 index 0000000..7dfefda --- /dev/null +++ b/doc/arm/server.grammar.xml @@ -0,0 +1,45 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Generated by doc/misc/docbook-options.pl --> + +<programlisting> +<command>server</command> <replaceable>netprefix</replaceable> { + <command>bogus</command> <replaceable>boolean</replaceable>; + <command>edns</command> <replaceable>boolean</replaceable>; + <command>edns-udp-size</command> <replaceable>integer</replaceable>; + <command>edns-version</command> <replaceable>integer</replaceable>; + <command>keys</command> <replaceable>server_key</replaceable>; + <command>max-udp-size</command> <replaceable>integer</replaceable>; + <command>notify-source</command> ( <replaceable>ipv4_address</replaceable> | * ) [ port ( <replaceable>integer</replaceable> | * ) ] [ + <command>dscp</command> <replaceable>integer</replaceable> ]; + <command>notify-source-v6</command> ( <replaceable>ipv6_address</replaceable> | * ) [ port ( <replaceable>integer</replaceable> | * ) ] + [ dscp <replaceable>integer</replaceable> ]; + <command>provide-ixfr</command> <replaceable>boolean</replaceable>; + <command>query-source</command> ( ( [ address ] ( <replaceable>ipv4_address</replaceable> | * ) [ port ( + <replaceable>integer</replaceable> | * ) ] ) | ( [ [ address ] ( <replaceable>ipv4_address</replaceable> | * ) ] + <command>port</command> ( <replaceable>integer</replaceable> | * ) ) ) [ dscp <replaceable>integer</replaceable> ]; + <command>query-source-v6</command> ( ( [ address ] ( <replaceable>ipv6_address</replaceable> | * ) [ port ( + <replaceable>integer</replaceable> | * ) ] ) | ( [ [ address ] ( <replaceable>ipv6_address</replaceable> | * ) ] + <command>port</command> ( <replaceable>integer</replaceable> | * ) ) ) [ dscp <replaceable>integer</replaceable> ]; + <command>request-expire</command> <replaceable>boolean</replaceable>; + <command>request-ixfr</command> <replaceable>boolean</replaceable>; + <command>request-nsid</command> <replaceable>boolean</replaceable>; + <command>send-cookie</command> <replaceable>boolean</replaceable>; + <command>tcp-only</command> <replaceable>boolean</replaceable>; + <command>transfer-format</command> ( many-answers | one-answer ); + <command>transfer-source</command> ( <replaceable>ipv4_address</replaceable> | * ) [ port ( <replaceable>integer</replaceable> | * ) ] [ + <command>dscp</command> <replaceable>integer</replaceable> ]; + <command>transfer-source-v6</command> ( <replaceable>ipv6_address</replaceable> | * ) [ port ( <replaceable>integer</replaceable> | * ) + ] [ dscp <replaceable>integer</replaceable> ]; + <command>transfers</command> <replaceable>integer</replaceable>; +}; +</programlisting> diff --git a/doc/arm/slave.zoneopt.xml b/doc/arm/slave.zoneopt.xml new file mode 100644 index 0000000..10d08d6 --- /dev/null +++ b/doc/arm/slave.zoneopt.xml @@ -0,0 +1,72 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Generated by doc/misc/docbook-zoneopt.pl --> +<programlisting> +<command>zone</command> <replaceable>string</replaceable> [ <replaceable>class</replaceable> ] { + <command>type</command> ( slave | secondary ); + <command>allow-notify</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>allow-query</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>allow-query-on</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>allow-transfer</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>allow-update-forwarding</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>also-notify</command> [ port <replaceable>integer</replaceable> ] [ dscp <replaceable>integer</replaceable> ] { ( <replaceable>masters</replaceable> | <replaceable>ipv4_address</replaceable> [ port <replaceable>integer</replaceable> ] | <replaceable>ipv6_address</replaceable> [ port <replaceable>integer</replaceable> ] ) [ key <replaceable>string</replaceable> ]; ... }; + <command>alt-transfer-source</command> ( <replaceable>ipv4_address</replaceable> | * ) [ port ( <replaceable>integer</replaceable> | * ) ] [ dscp <replaceable>integer</replaceable> ]; + <command>alt-transfer-source-v6</command> ( <replaceable>ipv6_address</replaceable> | * ) [ port ( <replaceable>integer</replaceable> | * ) ] [ dscp <replaceable>integer</replaceable> ]; + <command>auto-dnssec</command> ( allow | maintain | off ); + <command>check-names</command> ( fail | warn | ignore ); + <command>database</command> <replaceable>string</replaceable>; + <command>dialup</command> ( notify | notify-passive | passive | refresh | <replaceable>boolean</replaceable> ); + <command>dlz</command> <replaceable>string</replaceable>; + <command>dnssec-dnskey-kskonly</command> <replaceable>boolean</replaceable>; + <command>dnssec-loadkeys-interval</command> <replaceable>integer</replaceable>; + <command>dnssec-update-mode</command> ( maintain | no-resign ); + <command>file</command> <replaceable>quoted_string</replaceable>; + <command>forward</command> ( first | only ); + <command>forwarders</command> [ port <replaceable>integer</replaceable> ] [ dscp <replaceable>integer</replaceable> ] { ( <replaceable>ipv4_address</replaceable> | <replaceable>ipv6_address</replaceable> ) [ port <replaceable>integer</replaceable> ] [ dscp <replaceable>integer</replaceable> ]; ... }; + <command>inline-signing</command> <replaceable>boolean</replaceable>; + <command>ixfr-from-differences</command> <replaceable>boolean</replaceable>; + <command>journal</command> <replaceable>quoted_string</replaceable>; + <command>key-directory</command> <replaceable>quoted_string</replaceable>; + <command>masterfile-format</command> ( map | raw | text ); + <command>masterfile-style</command> ( full | relative ); + <command>masters</command> [ port <replaceable>integer</replaceable> ] [ dscp <replaceable>integer</replaceable> ] { ( <replaceable>masters</replaceable> | <replaceable>ipv4_address</replaceable> [ port <replaceable>integer</replaceable> ] | <replaceable>ipv6_address</replaceable> [ port <replaceable>integer</replaceable> ] ) [ key <replaceable>string</replaceable> ]; ... }; + <command>max-journal-size</command> ( unlimited | <replaceable>sizeval</replaceable> ); + <command>max-records</command> <replaceable>integer</replaceable>; + <command>max-refresh-time</command> <replaceable>integer</replaceable>; + <command>max-retry-time</command> <replaceable>integer</replaceable>; + <command>max-transfer-idle-in</command> <replaceable>integer</replaceable>; + <command>max-transfer-idle-out</command> <replaceable>integer</replaceable>; + <command>max-transfer-time-in</command> <replaceable>integer</replaceable>; + <command>max-transfer-time-out</command> <replaceable>integer</replaceable>; + <command>min-refresh-time</command> <replaceable>integer</replaceable>; + <command>min-retry-time</command> <replaceable>integer</replaceable>; + <command>multi-master</command> <replaceable>boolean</replaceable>; + <command>notify</command> ( explicit | master-only | <replaceable>boolean</replaceable> ); + <command>notify-delay</command> <replaceable>integer</replaceable>; + <command>notify-source</command> ( <replaceable>ipv4_address</replaceable> | * ) [ port ( <replaceable>integer</replaceable> | * ) ] [ dscp <replaceable>integer</replaceable> ]; + <command>notify-source-v6</command> ( <replaceable>ipv6_address</replaceable> | * ) [ port ( <replaceable>integer</replaceable> | * ) ] [ dscp <replaceable>integer</replaceable> ]; + <command>notify-to-soa</command> <replaceable>boolean</replaceable>; + <command>request-expire</command> <replaceable>boolean</replaceable>; + <command>request-ixfr</command> <replaceable>boolean</replaceable>; + <command>sig-signing-nodes</command> <replaceable>integer</replaceable>; + <command>sig-signing-signatures</command> <replaceable>integer</replaceable>; + <command>sig-signing-type</command> <replaceable>integer</replaceable>; + <command>sig-validity-interval</command> <replaceable>integer</replaceable> [ <replaceable>integer</replaceable> ]; + <command>transfer-source</command> ( <replaceable>ipv4_address</replaceable> | * ) [ port ( <replaceable>integer</replaceable> | * ) ] [ dscp <replaceable>integer</replaceable> ]; + <command>transfer-source-v6</command> ( <replaceable>ipv6_address</replaceable> | * ) [ port ( <replaceable>integer</replaceable> | * ) ] [ dscp <replaceable>integer</replaceable> ]; + <command>try-tcp-refresh</command> <replaceable>boolean</replaceable>; + <command>update-check-ksk</command> <replaceable>boolean</replaceable>; + <command>use-alt-transfer-source</command> <replaceable>boolean</replaceable>; + <command>zero-no-soa-ttl</command> <replaceable>boolean</replaceable>; + <command>zone-statistics</command> ( full | terse | none | <replaceable>boolean</replaceable> ); +}; +</programlisting> diff --git a/doc/arm/static-stub.zoneopt.xml b/doc/arm/static-stub.zoneopt.xml new file mode 100644 index 0000000..84e9bb0 --- /dev/null +++ b/doc/arm/static-stub.zoneopt.xml @@ -0,0 +1,25 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Generated by doc/misc/docbook-zoneopt.pl --> +<programlisting> +<command>zone</command> <replaceable>string</replaceable> [ <replaceable>class</replaceable> ] { + <command>type</command> static-stub; + <command>allow-query</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>allow-query-on</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>forward</command> ( first | only ); + <command>forwarders</command> [ port <replaceable>integer</replaceable> ] [ dscp <replaceable>integer</replaceable> ] { ( <replaceable>ipv4_address</replaceable> | <replaceable>ipv6_address</replaceable> ) [ port <replaceable>integer</replaceable> ] [ dscp <replaceable>integer</replaceable> ]; ... }; + <command>max-records</command> <replaceable>integer</replaceable>; + <command>server-addresses</command> { ( <replaceable>ipv4_address</replaceable> | <replaceable>ipv6_address</replaceable> ) [ port <replaceable>integer</replaceable> ]; ... }; + <command>server-names</command> { <replaceable>quoted_string</replaceable>; ... }; + <command>zone-statistics</command> ( full | terse | none | <replaceable>boolean</replaceable> ); +}; +</programlisting> diff --git a/doc/arm/statistics-channels.grammar.xml b/doc/arm/statistics-channels.grammar.xml new file mode 100644 index 0000000..d2c381d --- /dev/null +++ b/doc/arm/statistics-channels.grammar.xml @@ -0,0 +1,21 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Generated by doc/misc/docbook-options.pl --> + +<programlisting> +<command>statistics-channels</command> { + <command>inet</command> ( <replaceable>ipv4_address</replaceable> | <replaceable>ipv6_address</replaceable> | + * ) [ port ( <replaceable>integer</replaceable> | * ) ] [ + <command>allow</command> { <replaceable>address_match_element</replaceable>; ... + } ]; +}; +</programlisting> diff --git a/doc/arm/stub.zoneopt.xml b/doc/arm/stub.zoneopt.xml new file mode 100644 index 0000000..7365ece --- /dev/null +++ b/doc/arm/stub.zoneopt.xml @@ -0,0 +1,41 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Generated by doc/misc/docbook-zoneopt.pl --> +<programlisting> +<command>zone</command> <replaceable>string</replaceable> [ <replaceable>class</replaceable> ] { + <command>type</command> stub; + <command>allow-query</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>allow-query-on</command> { <replaceable>address_match_element</replaceable>; ... }; + <command>check-names</command> ( fail | warn | ignore ); + <command>database</command> <replaceable>string</replaceable>; + <command>delegation-only</command> <replaceable>boolean</replaceable>; + <command>dialup</command> ( notify | notify-passive | passive | refresh | <replaceable>boolean</replaceable> ); + <command>file</command> <replaceable>quoted_string</replaceable>; + <command>forward</command> ( first | only ); + <command>forwarders</command> [ port <replaceable>integer</replaceable> ] [ dscp <replaceable>integer</replaceable> ] { ( <replaceable>ipv4_address</replaceable> | <replaceable>ipv6_address</replaceable> ) [ port <replaceable>integer</replaceable> ] [ dscp <replaceable>integer</replaceable> ]; ... }; + <command>masterfile-format</command> ( map | raw | text ); + <command>masterfile-style</command> ( full | relative ); + <command>masters</command> [ port <replaceable>integer</replaceable> ] [ dscp <replaceable>integer</replaceable> ] { ( <replaceable>masters</replaceable> | <replaceable>ipv4_address</replaceable> [ port <replaceable>integer</replaceable> ] | <replaceable>ipv6_address</replaceable> [ port <replaceable>integer</replaceable> ] ) [ key <replaceable>string</replaceable> ]; ... }; + <command>max-records</command> <replaceable>integer</replaceable>; + <command>max-refresh-time</command> <replaceable>integer</replaceable>; + <command>max-retry-time</command> <replaceable>integer</replaceable>; + <command>max-transfer-idle-in</command> <replaceable>integer</replaceable>; + <command>max-transfer-time-in</command> <replaceable>integer</replaceable>; + <command>min-refresh-time</command> <replaceable>integer</replaceable>; + <command>min-retry-time</command> <replaceable>integer</replaceable>; + <command>multi-master</command> <replaceable>boolean</replaceable>; + <command>transfer-source</command> ( <replaceable>ipv4_address</replaceable> | * ) [ port ( <replaceable>integer</replaceable> | * ) ] [ dscp <replaceable>integer</replaceable> ]; + <command>transfer-source-v6</command> ( <replaceable>ipv6_address</replaceable> | * ) [ port ( <replaceable>integer</replaceable> | * ) ] [ dscp <replaceable>integer</replaceable> ]; + <command>use-alt-transfer-source</command> <replaceable>boolean</replaceable>; + <command>zone-statistics</command> ( full | terse | none | <replaceable>boolean</replaceable> ); +}; +</programlisting> diff --git a/doc/arm/trusted-keys.grammar.xml b/doc/arm/trusted-keys.grammar.xml new file mode 100644 index 0000000..b0bd3d7 --- /dev/null +++ b/doc/arm/trusted-keys.grammar.xml @@ -0,0 +1,17 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Generated by doc/misc/docbook-options.pl --> + +<programlisting> +<command>trusted-keys</command> { <replaceable>string</replaceable> <replaceable>integer</replaceable> <replaceable>integer</replaceable> + <replaceable>integer</replaceable> <replaceable>quoted_string</replaceable>; ... }; +</programlisting> |