diff --git a/doc/arm/Makefile.am b/doc/arm/Makefile.am index ba734687a5..f22b365717 100644 --- a/doc/arm/Makefile.am +++ b/doc/arm/Makefile.am @@ -53,6 +53,7 @@ EXTRA_DIST = \ tkey.inc.rst \ troubleshooting.inc.rst \ tsig.inc.rst \ + zones.inc.rst \ ../dnssec-guide \ ../misc/acl.grammar.rst \ ../misc/controls.grammar.rst \ diff --git a/doc/arm/chapter3.rst b/doc/arm/chapter3.rst index 9a51e7e77a..a9d263f609 100644 --- a/doc/arm/chapter3.rst +++ b/doc/arm/chapter3.rst @@ -9,4 +9,5 @@ .. See the COPYRIGHT file distributed with this work for additional .. information regarding copyright ownership. -.. include:: configuration.inc.rst \ No newline at end of file +.. include:: configuration.inc.rst +.. include:: zones.inc.rst diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst index c44c67c148..3920d99656 100644 --- a/doc/arm/reference.rst +++ b/doc/arm/reference.rst @@ -6413,438 +6413,6 @@ An ``in-view`` zone cannot be used as a response policy zone. An ``in-view`` zone is not intended to reference a ``forward`` zone. -.. _zone_file: - -Zone File ---------- - -.. _types_of_resource_records_and_when_to_use_them: - -Types of Resource Records and When to Use Them -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This section, largely borrowed from :rfc:`1034`, describes the concept of a -Resource Record (RR) and explains when each type is used. Since the -publication of :rfc:`1034`, several new RRs have been identified and -implemented in the DNS. These are also included. - -Resource Records -^^^^^^^^^^^^^^^^ - -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 -:ref:`the_sortlist_statement` and :ref:`rrset_ordering`. - -The components of a Resource Record are: - -owner name - The domain name where the RR is found. - -type - An encoded 16-bit value that specifies the type of the resource record. - -TTL - 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. - -class - An encoded 16-bit value that identifies a protocol family or an instance of a protocol. - -RDATA - The resource data. The format of the data is type- and sometimes class-specific. - -For a complete list of *types* of valid RRs, including those that have been obsoleted, please refer to https://en.wikipedia.org/wiki/List_of_DNS_record_types. - -The following *classes* of resource records are currently valid in the -DNS: - -IN - The Internet. - -CH - Chaosnet, a LAN protocol created at MIT in the mid-1970s. It was rarely used for its historical purpose, but was reused for BIND's built-in server information zones, e.g., ``version.bind``. - -HS - Hesiod, an information service developed by MIT's Project Athena. It was used to share information about various systems databases, such as users, groups, printers, etc. - -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. - -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; that also times out, but follows 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 is anticipated, the TTL can be reduced prior to -the change to minimize inconsistency, and then -increased back to its former value following the change. - -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. - -.. _rr_text: - -Textual Expression of RRs -^^^^^^^^^^^^^^^^^^^^^^^^^ - -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 primary 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. - -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. - -Following the owner are listed 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. 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 interest of clarity. - -The resource data or RDATA section of the RR is given using knowledge -of the typical representation for the data. - -For example, the RRs carried in a message might be shown as: - - +---------------------+---------------+--------------------------------+ - | ``ISI.EDU.`` | ``MX`` | ``10 VENERA.ISI.EDU.`` | - +---------------------+---------------+--------------------------------+ - | | ``MX`` | ``10 VAXA.ISI.EDU`` | - +---------------------+---------------+--------------------------------+ - | ``VENERA.ISI.EDU`` | ``A`` | ``128.9.0.32`` | - +---------------------+---------------+--------------------------------+ - | | ``A`` | ``10.1.0.52`` | - +---------------------+---------------+--------------------------------+ - | ``VAXA.ISI.EDU`` | ``A`` | ``10.2.0.27`` | - +---------------------+---------------+--------------------------------+ - | | ``A`` | ``128.9.0.33`` | - +---------------------+---------------+--------------------------------+ - -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. - -The above example shows six RRs, with two RRs at each of three domain -names. - -Here is another possible example: - - +----------------------+---------------+-------------------------------+ - | ``XX.LCS.MIT.EDU.`` | ``IN A`` | ``10.0.0.44`` | - +----------------------+---------------+-------------------------------+ - | | ``CH A`` | ``MIT.EDU. 2420`` | - +----------------------+---------------+-------------------------------+ - -This shows two addresses for ``XX.LCS.MIT.EDU``, each of a -different class. - -.. _mx_records: - -Discussion of MX Records -~~~~~~~~~~~~~~~~~~~~~~~~ - -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 an 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. - -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 -falls 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 is delivered. It *must* have an associated address -record (A or AAAA); CNAME is not sufficient. - -For a given domain, if there is both a CNAME record and an MX record, -the MX record is in error and is ignored. Instead, the mail is -delivered to the server specified in the MX record pointed to by the -CNAME. For example: - - +------------------------+--------+--------+--------------+------------------------+ - | ``example.com.`` | ``IN`` | ``MX`` | ``10`` | ``mail.example.com.`` | - +------------------------+--------+--------+--------------+------------------------+ - | | ``IN`` | ``MX`` | ``10`` | ``mail2.example.com.`` | - +------------------------+--------+--------+--------------+------------------------+ - | | ``IN`` | ``MX`` | ``20`` | ``mail.backup.org.`` | - +------------------------+--------+--------+--------------+------------------------+ - | ``mail.example.com.`` | ``IN`` | ``A`` | ``10.0.0.1`` | | - +------------------------+--------+--------+--------------+------------------------+ - | ``mail2.example.com.`` | ``IN`` | ``A`` | ``10.0.0.2`` | | - +------------------------+--------+--------+--------------+------------------------+ - -Mail delivery is attempted to ``mail.example.com`` and -``mail2.example.com`` (in any order); if neither of those succeeds, -delivery to ``mail.backup.org`` is attempted. - -.. _Setting_TTLs: - -Setting TTLs -~~~~~~~~~~~~ - -The time-to-live (TTL) 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 an RR can be cached before it should be -discarded. The following three types of TTLs are currently used in a zone -file. - -SOA - The last field in the SOA is the negative caching TTL. This controls how long other servers cache no-such-domain (NXDOMAIN) responses from this server. - - The maximum time for negative caching is 3 hours (3h). - -$TTL - 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. - -RR TTLs - Each RR can have a TTL as the second field in the RR, which controls how long other servers can cache it. - -All of these TTLs default to units of seconds, though units can be -explicitly specified: for example, ``1h30m``. - -.. _ipv4_reverse: - -Inverse Mapping in IPv4 -~~~~~~~~~~~~~~~~~~~~~~~ - -Reverse name resolution (that is, translation from IP address to name) -is achieved by means of the ``in-addr.arpa`` 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 -``example.com`` domain: - - +--------------+-------------------------------------------------------+ - | ``$ORIGIN`` | ``2.1.10.in-addr.arpa`` | - +--------------+-------------------------------------------------------+ - | ``3`` | ``IN PTR foo.example.com.`` | - +--------------+-------------------------------------------------------+ - -.. note:: - - The ``$ORIGIN`` line in this example is only to provide context; - it does not necessarily appear in the actual - usage. It is only used here to indicate that the example is - relative to the listed origin. - -.. _zone_directives: - -Other Zone File Directives -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The DNS "master file" format was initially defined in :rfc:`1035` and has -subsequently been extended. While the format itself is class-independent, -all records in a zone file must be of the same class. - -Master file directives include ``$ORIGIN``, ``$INCLUDE``, and ``$TTL.`` - -.. _atsign: - -The ``@`` (at-sign) -^^^^^^^^^^^^^^^^^^^ - -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 <``zone_name``>, followed by a trailing dot (.). - -.. _origin_directive: - -The ``$ORIGIN`` Directive -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Syntax: ``$ORIGIN`` domain-name [comment] - -``$ORIGIN`` sets the domain name that is appended to any -unqualified records. When a zone is first read, there is an implicit -``$ORIGIN`` <``zone_name``>``.``; note the trailing dot. The -current ``$ORIGIN`` is appended to the domain specified in the -``$ORIGIN`` argument if it is not absolute. - -:: - - $ORIGIN example.com. - WWW CNAME MAIN-SERVER - -is equivalent to - -:: - - WWW.EXAMPLE.COM. CNAME MAIN-SERVER.EXAMPLE.COM. - -.. _include_directive: - -The ``$INCLUDE`` Directive -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Syntax: ``$INCLUDE`` filename [origin] [comment] - -This reads and processes the file ``filename`` as if it were included in the -file at this point. The ``filename`` can be an absolute path, or a relative -path. In the latter case it is read from :iscman:`named`'s working directory. If -``origin`` is specified, the file is processed with ``$ORIGIN`` set to that -value; otherwise, the current ``$ORIGIN`` is used. - -The origin and the current domain name revert to the values they had -prior to the ``$INCLUDE`` once the file has been read. - -.. note:: - - :rfc:`1035` specifies that the current origin should be restored after - an ``$INCLUDE``, 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. - -.. _ttl_directive: - -The ``$TTL`` Directive -^^^^^^^^^^^^^^^^^^^^^^ - -Syntax: ``$TTL`` default-ttl [comment] - -This sets the default Time-To-Live (TTL) for subsequent records with undefined -TTLs. Valid TTLs are of the range 0-2147483647 seconds. - -``$TTL`` is defined in :rfc:`2308`. - -.. _generate_directive: - -BIND Primary File Extension: the ``$GENERATE`` Directive -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Syntax: ``$GENERATE`` range lhs [ttl] [class] type rhs [comment] - -``$GENERATE`` is used to create a series of resource records that only -differ from each other by an iterator. ``$GENERATE`` can be used to -easily generate the sets of records required to support sub-/24 reverse -delegations described in :rfc:`2317`. - -:: - - $ORIGIN 0.0.192.IN-ADDR.ARPA. - $GENERATE 1-2 @ NS SERVER$.EXAMPLE. - $GENERATE 1-127 $ CNAME $.0 - -is equivalent to - -:: - - 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. - -Both generate a set of A and MX records. Note the MX's right-hand side is a -quoted string. The quotes are stripped when the right-hand side is -processed. - -:: - - $ORIGIN EXAMPLE. - $GENERATE 1-127 HOST-$ A 1.2.3.$ - $GENERATE 1-127 HOST-$ MX "0 ." - -is equivalent to - -:: - - 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 . - -``range`` - 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". - -``owner`` - This describes the owner name of the resource records to be created. Any single ``$`` (dollar sign) symbols within the ``owner`` string are replaced by the iterator value. To get a ``$`` in the output, escape the ``$`` using a backslash ``\``, e.g., ``\$``. The ``$`` may optionally be followed by modifiers which change the offset from the iterator, field width, and base. - - Modifiers are introduced by a ``{`` (left brace) immediately following the ``$``, as in ``${offset[,width[,base]]}``. For example, ``${-20,3,d}`` subtracts 20 from the current value and prints the result as a decimal in a zero-padded field of width 3. Available output forms are decimal (``d``), octal (``o``), hexadecimal (``x`` or ``X`` for uppercase), and nibble (``n`` or ``N`` for uppercase). - - The default modifier is ``${0,0,d}``. If the ``owner`` is not absolute, the current ``$ORIGIN`` is appended to the name. - - In nibble mode, the value is treated as if it were a reversed hexadecimal string, with each hexadecimal digit as a separate label. The width field includes the label separator. - - For compatibility with earlier versions, ``$$`` is still recognized as indicating a literal $ in the output. - -``ttl`` - This specifies the time-to-live of the generated records. If not specified, this is inherited using the normal TTL inheritance rules. - - ``class`` and ``ttl`` can be entered in either order. - -``class`` - This specifies the class of the generated records. This must match the zone class if it is specified. - - ``class`` and ``ttl`` can be entered in either order. - -``type`` - This can be any valid type. - -``rdata`` - This is a string containing the RDATA of the resource record to be created. It may be quoted if there are spaces in the string; the quotation marks do not appear in the generated record. - -The ``$GENERATE`` directive is a BIND extension and not part of the -standard zone file format. - -.. _zonefile_format: - -Additional File Formats -~~~~~~~~~~~~~~~~~~~~~~~ - -In addition to the standard text format, BIND 9 supports the ability -to read or dump to zone files in other formats. - -The ``raw`` 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. - -For a primary server, a zone file in ``raw`` format is expected -to be generated from a text zone file by the :iscman:`named-compilezone` command. -For a secondary server or a dynamic zone, the zone file is automatically -generated when :iscman:`named` dumps the zone contents after zone transfer or -when applying prior updates, if one of these formats is specified by the -``masterfile-format`` option. - -If a zone file in ``raw`` format needs manual modification, it first must -be converted to ``text`` format by the :iscman:`named-compilezone` command, -then converted back after editing. For example: - -:: - - named-compilezone -f raw -F text -o zonefile.text zonefile.raw - [edit zonefile.text] - named-compilezone -f text -F raw -o zonefile.raw zonefile.text .. _statistics: diff --git a/doc/arm/zones.inc.rst b/doc/arm/zones.inc.rst new file mode 100644 index 0000000000..71a7acbe98 --- /dev/null +++ b/doc/arm/zones.inc.rst @@ -0,0 +1,443 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. 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 https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +.. _zone_file: + +Zone File +--------- + +.. _types_of_resource_records_and_when_to_use_them: + +Types of Resource Records and When to Use Them +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section, largely borrowed from :rfc:`1034`, describes the concept of a +Resource Record (RR) and explains when each type is used. Since the +publication of :rfc:`1034`, several new RRs have been identified and +implemented in the DNS. These are also included. + +Resource Records +^^^^^^^^^^^^^^^^ + +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 +:ref:`the_sortlist_statement` and :ref:`rrset_ordering`. + +The components of a Resource Record are: + +owner name + The domain name where the RR is found. + +type + An encoded 16-bit value that specifies the type of the resource record. + +TTL + 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. + +class + An encoded 16-bit value that identifies a protocol family or an instance of a protocol. + +RDATA + The resource data. The format of the data is type- and sometimes class-specific. + +For a complete list of *types* of valid RRs, including those that have been obsoleted, please refer to https://en.wikipedia.org/wiki/List_of_DNS_record_types. + +The following *classes* of resource records are currently valid in the +DNS: + +IN + The Internet. + +CH + Chaosnet, a LAN protocol created at MIT in the mid-1970s. It was rarely used for its historical purpose, but was reused for BIND's built-in server information zones, e.g., ``version.bind``. + +HS + Hesiod, an information service developed by MIT's Project Athena. It was used to share information about various systems databases, such as users, groups, printers, etc. + +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. + +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; that also times out, but follows 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 is anticipated, the TTL can be reduced prior to +the change to minimize inconsistency, and then +increased back to its former value following the change. + +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. + +.. _rr_text: + +Textual Expression of RRs +^^^^^^^^^^^^^^^^^^^^^^^^^ + +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 primary 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. + +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. + +Following the owner are listed 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. 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 interest of clarity. + +The resource data or RDATA section of the RR is given using knowledge +of the typical representation for the data. + +For example, the RRs carried in a message might be shown as: + + +---------------------+---------------+--------------------------------+ + | ``ISI.EDU.`` | ``MX`` | ``10 VENERA.ISI.EDU.`` | + +---------------------+---------------+--------------------------------+ + | | ``MX`` | ``10 VAXA.ISI.EDU`` | + +---------------------+---------------+--------------------------------+ + | ``VENERA.ISI.EDU`` | ``A`` | ``128.9.0.32`` | + +---------------------+---------------+--------------------------------+ + | | ``A`` | ``10.1.0.52`` | + +---------------------+---------------+--------------------------------+ + | ``VAXA.ISI.EDU`` | ``A`` | ``10.2.0.27`` | + +---------------------+---------------+--------------------------------+ + | | ``A`` | ``128.9.0.33`` | + +---------------------+---------------+--------------------------------+ + +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. + +The above example shows six RRs, with two RRs at each of three domain +names. + +Here is another possible example: + + +----------------------+---------------+-------------------------------+ + | ``XX.LCS.MIT.EDU.`` | ``IN A`` | ``10.0.0.44`` | + +----------------------+---------------+-------------------------------+ + | | ``CH A`` | ``MIT.EDU. 2420`` | + +----------------------+---------------+-------------------------------+ + +This shows two addresses for ``XX.LCS.MIT.EDU``, each of a +different class. + +.. _mx_records: + +Discussion of MX Records +~~~~~~~~~~~~~~~~~~~~~~~~ + +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 an 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. + +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 +falls 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 is delivered. It *must* have an associated address +record (A or AAAA); CNAME is not sufficient. + +For a given domain, if there is both a CNAME record and an MX record, +the MX record is in error and is ignored. Instead, the mail is +delivered to the server specified in the MX record pointed to by the +CNAME. For example: + + +------------------------+--------+--------+--------------+------------------------+ + | ``example.com.`` | ``IN`` | ``MX`` | ``10`` | ``mail.example.com.`` | + +------------------------+--------+--------+--------------+------------------------+ + | | ``IN`` | ``MX`` | ``10`` | ``mail2.example.com.`` | + +------------------------+--------+--------+--------------+------------------------+ + | | ``IN`` | ``MX`` | ``20`` | ``mail.backup.org.`` | + +------------------------+--------+--------+--------------+------------------------+ + | ``mail.example.com.`` | ``IN`` | ``A`` | ``10.0.0.1`` | | + +------------------------+--------+--------+--------------+------------------------+ + | ``mail2.example.com.`` | ``IN`` | ``A`` | ``10.0.0.2`` | | + +------------------------+--------+--------+--------------+------------------------+ + +Mail delivery is attempted to ``mail.example.com`` and +``mail2.example.com`` (in any order); if neither of those succeeds, +delivery to ``mail.backup.org`` is attempted. + +.. _Setting_TTLs: + +Setting TTLs +~~~~~~~~~~~~ + +The time-to-live (TTL) 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 an RR can be cached before it should be +discarded. The following three types of TTLs are currently used in a zone +file. + +SOA + The last field in the SOA is the negative caching TTL. This controls how long other servers cache no-such-domain (NXDOMAIN) responses from this server. + + The maximum time for negative caching is 3 hours (3h). + +$TTL + 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. + +RR TTLs + Each RR can have a TTL as the second field in the RR, which controls how long other servers can cache it. + +All of these TTLs default to units of seconds, though units can be +explicitly specified: for example, ``1h30m``. + +.. _ipv4_reverse: + +Inverse Mapping in IPv4 +~~~~~~~~~~~~~~~~~~~~~~~ + +Reverse name resolution (that is, translation from IP address to name) +is achieved by means of the ``in-addr.arpa`` 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 +``example.com`` domain: + + +--------------+-------------------------------------------------------+ + | ``$ORIGIN`` | ``2.1.10.in-addr.arpa`` | + +--------------+-------------------------------------------------------+ + | ``3`` | ``IN PTR foo.example.com.`` | + +--------------+-------------------------------------------------------+ + +.. note:: + + The ``$ORIGIN`` line in this example is only to provide context; + it does not necessarily appear in the actual + usage. It is only used here to indicate that the example is + relative to the listed origin. + +.. _zone_directives: + +Other Zone File Directives +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The DNS "master file" format was initially defined in :rfc:`1035` and has +subsequently been extended. While the format itself is class-independent, +all records in a zone file must be of the same class. + +Master file directives include ``$ORIGIN``, ``$INCLUDE``, and ``$TTL.`` + +.. _atsign: + +The ``@`` (at-sign) +^^^^^^^^^^^^^^^^^^^ + +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 <``zone_name``>, followed by a trailing dot (.). + +.. _origin_directive: + +The ``$ORIGIN`` Directive +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: ``$ORIGIN`` domain-name [comment] + +``$ORIGIN`` sets the domain name that is appended to any +unqualified records. When a zone is first read, there is an implicit +``$ORIGIN`` <``zone_name``>``.``; note the trailing dot. The +current ``$ORIGIN`` is appended to the domain specified in the +``$ORIGIN`` argument if it is not absolute. + +:: + + $ORIGIN example.com. + WWW CNAME MAIN-SERVER + +is equivalent to + +:: + + WWW.EXAMPLE.COM. CNAME MAIN-SERVER.EXAMPLE.COM. + +.. _include_directive: + +The ``$INCLUDE`` Directive +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: ``$INCLUDE`` filename [origin] [comment] + +This reads and processes the file ``filename`` as if it were included in the +file at this point. The ``filename`` can be an absolute path, or a relative +path. In the latter case it is read from :iscman:`named`'s working directory. If +``origin`` is specified, the file is processed with ``$ORIGIN`` set to that +value; otherwise, the current ``$ORIGIN`` is used. + +The origin and the current domain name revert to the values they had +prior to the ``$INCLUDE`` once the file has been read. + +.. note:: + + :rfc:`1035` specifies that the current origin should be restored after + an ``$INCLUDE``, 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. + +.. _ttl_directive: + +The ``$TTL`` Directive +^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: ``$TTL`` default-ttl [comment] + +This sets the default Time-To-Live (TTL) for subsequent records with undefined +TTLs. Valid TTLs are of the range 0-2147483647 seconds. + +``$TTL`` is defined in :rfc:`2308`. + +.. _generate_directive: + +BIND Primary File Extension: the ``$GENERATE`` Directive +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Syntax: ``$GENERATE`` range lhs [ttl] [class] type rhs [comment] + +``$GENERATE`` is used to create a series of resource records that only +differ from each other by an iterator. ``$GENERATE`` can be used to +easily generate the sets of records required to support sub-/24 reverse +delegations described in :rfc:`2317`. + +:: + + $ORIGIN 0.0.192.IN-ADDR.ARPA. + $GENERATE 1-2 @ NS SERVER$.EXAMPLE. + $GENERATE 1-127 $ CNAME $.0 + +is equivalent to + +:: + + 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. + +Both generate a set of A and MX records. Note the MX's right-hand side is a +quoted string. The quotes are stripped when the right-hand side is +processed. + +:: + + $ORIGIN EXAMPLE. + $GENERATE 1-127 HOST-$ A 1.2.3.$ + $GENERATE 1-127 HOST-$ MX "0 ." + +is equivalent to + +:: + + 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 . + +``range`` + 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". + +``owner`` + This describes the owner name of the resource records to be created. Any single ``$`` (dollar sign) symbols within the ``owner`` string are replaced by the iterator value. To get a ``$`` in the output, escape the ``$`` using a backslash ``\``, e.g., ``\$``. The ``$`` may optionally be followed by modifiers which change the offset from the iterator, field width, and base. + + Modifiers are introduced by a ``{`` (left brace) immediately following the ``$``, as in ``${offset[,width[,base]]}``. For example, ``${-20,3,d}`` subtracts 20 from the current value and prints the result as a decimal in a zero-padded field of width 3. Available output forms are decimal (``d``), octal (``o``), hexadecimal (``x`` or ``X`` for uppercase), and nibble (``n`` or ``N`` for uppercase). + + The default modifier is ``${0,0,d}``. If the ``owner`` is not absolute, the current ``$ORIGIN`` is appended to the name. + + In nibble mode, the value is treated as if it were a reversed hexadecimal string, with each hexadecimal digit as a separate label. The width field includes the label separator. + + For compatibility with earlier versions, ``$$`` is still recognized as indicating a literal $ in the output. + +``ttl`` + This specifies the time-to-live of the generated records. If not specified, this is inherited using the normal TTL inheritance rules. + + ``class`` and ``ttl`` can be entered in either order. + +``class`` + This specifies the class of the generated records. This must match the zone class if it is specified. + + ``class`` and ``ttl`` can be entered in either order. + +``type`` + This can be any valid type. + +``rdata`` + This is a string containing the RDATA of the resource record to be created. It may be quoted if there are spaces in the string; the quotation marks do not appear in the generated record. + +The ``$GENERATE`` directive is a BIND extension and not part of the +standard zone file format. + +.. _zonefile_format: + +Additional File Formats +~~~~~~~~~~~~~~~~~~~~~~~ + +In addition to the standard text format, BIND 9 supports the ability +to read or dump to zone files in other formats. + +The ``raw`` 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. + +For a primary server, a zone file in ``raw`` format is expected +to be generated from a text zone file by the :iscman:`named-compilezone` command. +For a secondary server or a dynamic zone, the zone file is automatically +generated when :iscman:`named` dumps the zone contents after zone transfer or +when applying prior updates, if one of these formats is specified by the +``masterfile-format`` option. + +If a zone file in ``raw`` format needs manual modification, it first must +be converted to ``text`` format by the :iscman:`named-compilezone` command, +then converted back after editing. For example: + +:: + + named-compilezone -f raw -F text -o zonefile.text zonefile.raw + [edit zonefile.text] + named-compilezone -f text -F raw -o zonefile.raw zonefile.text