1.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") 2.. 3.. SPDX-License-Identifier: MPL-2.0 4.. 5.. This Source Code Form is subject to the terms of the Mozilla Public 6.. License, v. 2.0. If a copy of the MPL was not distributed with this 7.. file, you can obtain one at https://mozilla.org/MPL/2.0/. 8.. 9.. See the COPYRIGHT file distributed with this work for additional 10.. information regarding copyright ownership. 11 12.. _zone_file: 13 14.. _soa_rr: 15 16Zone File 17--------- 18 19This section, largely borrowed from :rfc:`1034`, describes the concept of a 20Resource Record (RR) and explains how to use them. 21 22Resource Records 23~~~~~~~~~~~~~~~~ 24 25A domain name identifies a node in the DNS tree namespace. Each node has a set of resource 26information, which may be empty. The set of resource information 27associated with a particular name is composed of separate RRs. The order 28of RRs in a set is not significant and need not be preserved by name 29servers, resolvers, or other parts of the DNS. However, sorting of 30multiple RRs is permitted for optimization purposes: for example, to 31specify that a particular nearby server be tried first. See 32:any:`sortlist` and :ref:`rrset_ordering`. 33 34The components of a Resource Record are: 35 36.. glossary:: 37 38 owner name 39 The domain name where the RR is found. 40 41 RR type 42 An encoded 16-bit value that specifies the type of the resource record. 43 For a list of *types* of valid RRs, including those that have been obsoleted, please refer to 44 `https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-4`. 45 46 TTL 47 The time-to-live of the RR. This field is a 32-bit integer in units of seconds, 48 and is primarily used by resolvers when they cache RRs. The TTL describes how long 49 a RR can be cached before it should be discarded. 50 51 class 52 An encoded 16-bit value that identifies a protocol family or an instance of a protocol. 53 54 RDATA 55 The resource data. The format of the data is type- and sometimes class-specific. 56 57 58The following *classes* of resource records are currently valid in the 59DNS: 60 61.. glossary:: 62 63 IN 64 The Internet. The only widely :term:`class` used today. 65 66 CH 67 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**. 68 69 HS 70 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. 71 72The :term:`owner name` is often implicit, rather than forming an integral part 73of the RR. For example, many name servers internally form tree or hash 74structures for the name space, and chain RRs off nodes. The remaining RR 75parts are the fixed header (type, class, TTL), which is consistent for 76all RRs, and a variable part (RDATA) that fits the needs of the resource 77being described. 78 79The TTL field is a time limit on how long an RR can be 80kept in a cache. This limit does not apply to authoritative data in 81zones; that also times out, but follows the refreshing policies for the 82zone. The TTL is assigned by the administrator for the zone where the 83data originates. While short TTLs can be used to minimize caching, and a 84zero TTL prohibits caching, the realities of Internet performance 85suggest that these times should be on the order of days for the typical 86host. If a change is anticipated, the TTL can be reduced prior to 87the change to minimize inconsistency, and then 88increased back to its former value following the change. 89 90The data in the RDATA section of RRs is carried as a combination of 91binary strings and domain names. The domain names are frequently used as 92"pointers" to other data in the DNS. 93 94.. _rr_text: 95 96Textual Expression of RRs 97^^^^^^^^^^^^^^^^^^^^^^^^^ 98 99RRs are represented in binary form in the packets of the DNS protocol, 100and are usually represented in highly encoded form when stored in a name 101server or resolver. In the examples provided in :rfc:`1034`, a style 102similar to that used in primary files was employed in order to show the 103contents of RRs. In this format, most RRs are shown on a single line, 104although continuation lines are possible using parentheses. 105 106The start of the line gives the owner of the RR. If a line begins with a 107blank, then the owner is assumed to be the same as that of the previous 108RR. Blank lines are often included for readability. 109 110Following the owner are listed the TTL, type, and class of the RR. Class 111and type use the mnemonics defined above, and TTL is an integer before 112the type field. To avoid ambiguity in parsing, type and class 113mnemonics are disjoint, TTLs are integers, and the type mnemonic is 114always last. The IN class and TTL values are often omitted from examples 115in the interest of clarity. 116 117The resource data or RDATA section of the RR is given using knowledge 118of the typical representation for the data. 119 120For example, the RRs carried in a message might be shown as: 121 122 +---------------------+---------------+--------------------------------+ 123 | **ISI.EDU.** | **MX** | **10 VENERA.ISI.EDU.** | 124 +---------------------+---------------+--------------------------------+ 125 | | **MX** | **10 VAXA.ISI.EDU** | 126 +---------------------+---------------+--------------------------------+ 127 | **VENERA.ISI.EDU** | **A** | **128.9.0.32** | 128 +---------------------+---------------+--------------------------------+ 129 | | **A** | **10.1.0.52** | 130 +---------------------+---------------+--------------------------------+ 131 | **VAXA.ISI.EDU** | **A** | **10.2.0.27** | 132 +---------------------+---------------+--------------------------------+ 133 | | **A** | **128.9.0.33** | 134 +---------------------+---------------+--------------------------------+ 135 136The MX RRs have an RDATA section which consists of a 16-bit number 137followed by a domain name. The address RRs use a standard IP address 138format to contain a 32-bit Internet address. 139 140The above example shows six RRs, with two RRs at each of three domain 141names. 142 143Here is another possible example: 144 145 +----------------------+---------------+-------------------------------+ 146 | **XX.LCS.MIT.EDU.** | **IN A** | **10.0.0.44** | 147 +----------------------+---------------+-------------------------------+ 148 | | **CH A** | **MIT.EDU. 2420** | 149 +----------------------+---------------+-------------------------------+ 150 151This shows two addresses for **XX.LCS.MIT.EDU**, each of a 152different class. 153 154.. _mx_records: 155 156Discussion of MX Records 157~~~~~~~~~~~~~~~~~~~~~~~~ 158 159As described above, domain servers store information as a series of 160resource records, each of which contains a particular piece of 161information about a given domain name (which is usually, but not always, 162a host). The simplest way to think of an RR is as a typed pair of data, a 163domain name matched with a relevant datum and stored with some 164additional type information, to help systems determine when the RR is 165relevant. 166 167MX records are used to control delivery of email. The data specified in 168the record is a priority and a domain name. The priority controls the 169order in which email delivery is attempted, with the lowest number 170first. If two priorities are the same, a server is chosen randomly. If 171no servers at a given priority are responding, the mail transport agent 172falls back to the next largest priority. Priority numbers do not 173have any absolute meaning; they are relevant only respective to other 174MX records for that domain name. The domain name given is the machine to 175which the mail is delivered. It *must* have an associated address 176record (A or AAAA); CNAME is not sufficient. 177 178For a given domain, if there is both a CNAME record and an MX record, 179the MX record is in error and is ignored. Instead, the mail is 180delivered to the server specified in the MX record pointed to by the 181CNAME. For example: 182 183 +------------------------+--------+--------+--------------+------------------------+ 184 | **example.com.** | **IN** | **MX** | **10** | **mail.example.com.** | 185 +------------------------+--------+--------+--------------+------------------------+ 186 | | **IN** | **MX** | **10** | **mail2.example.com.** | 187 +------------------------+--------+--------+--------------+------------------------+ 188 | | **IN** | **MX** | **20** | **mail.backup.org.** | 189 +------------------------+--------+--------+--------------+------------------------+ 190 | **mail.example.com.** | **IN** | **A** | **10.0.0.1** | | 191 +------------------------+--------+--------+--------------+------------------------+ 192 | **mail2.example.com.** | **IN** | **A** | **10.0.0.2** | | 193 +------------------------+--------+--------+--------------+------------------------+ 194 195Mail delivery is attempted to **mail.example.com** and 196**mail2.example.com** (in any order); if neither of those succeeds, 197delivery to **mail.backup.org** is attempted. 198 199.. _Setting_TTLs: 200 201Setting TTLs 202~~~~~~~~~~~~ 203 204The time-to-live (TTL) of the RR field is a 32-bit integer represented in 205units of seconds, and is primarily used by resolvers when they cache 206RRs. The TTL describes how long an RR can be cached before it should be 207discarded. The following three types of TTLs are currently used in a zone 208file. 209 210.. glossary:: 211 212 SOA minimum 213 The last field in the SOA is the negative caching TTL. 214 This controls how long other servers cache no-such-domain (NXDOMAIN) 215 responses from this server. Further details can be found in :rfc:`2308`. 216 217 The maximum time for negative caching is 3 hours (3h). 218 219 $TTL 220 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. 221 222 RR TTLs 223 Each RR can have a TTL as the second field in the RR, which controls how long other servers can cache it. 224 225All of these TTLs default to units of seconds, though units can be 226explicitly specified: for example, **1h30m**. 227 228.. _ipv4_reverse: 229 230Inverse Mapping in IPv4 231~~~~~~~~~~~~~~~~~~~~~~~ 232 233Reverse name resolution (that is, translation from IP address to name) 234is achieved by means of the **in-addr.arpa** domain and PTR records. 235Entries in the in-addr.arpa domain are made in least-to-most significant 236order, read left to right. This is the opposite order to the way IP 237addresses are usually written. Thus, a machine with an IP address of 23810.1.2.3 would have a corresponding in-addr.arpa name of 2393.2.1.10.in-addr.arpa. This name should have a PTR resource record whose 240data field is the name of the machine or, optionally, multiple PTR 241records if the machine has more than one name. For example, in the 242**example.com** domain: 243 244 +--------------+-------------------------------------------------------+ 245 | **$ORIGIN** | **2.1.10.in-addr.arpa** | 246 +--------------+-------------------------------------------------------+ 247 | **3** | **IN PTR foo.example.com.** | 248 +--------------+-------------------------------------------------------+ 249 250.. note:: 251 252 The **$ORIGIN** line in this example is only to provide context; 253 it does not necessarily appear in the actual 254 usage. It is only used here to indicate that the example is 255 relative to the listed origin. 256 257.. _zone_directives: 258 259Other Zone File Directives 260~~~~~~~~~~~~~~~~~~~~~~~~~~ 261 262The DNS "master file" format was initially defined in :rfc:`1035` and has 263subsequently been extended. While the format itself is class-independent, 264all records in a zone file must be of the same class. 265 266Master file directives include **$ORIGIN**, **$INCLUDE**, and **$TTL.** 267 268.. _atsign: 269 270The **@** (at-sign) 271^^^^^^^^^^^^^^^^^^^ 272 273When used in the label (or name) field, the asperand or at-sign (@) 274symbol represents the current origin. At the start of the zone file, it 275is the <**zone_name**>, followed by a trailing dot (.). 276 277.. _origin_directive: 278 279The **$ORIGIN** Directive 280^^^^^^^^^^^^^^^^^^^^^^^^^ 281 282Syntax: **$ORIGIN** domain-name [comment] 283 284**$ORIGIN** sets the domain name that is appended to any 285unqualified records. When a zone is first read, there is an implicit 286``$ORIGIN <zone_name>.``; note the trailing dot. The 287current **$ORIGIN** is appended to the domain specified in the 288**$ORIGIN** argument if it is not absolute. 289 290:: 291 292 $ORIGIN example.com. 293 WWW CNAME MAIN-SERVER 294 295is equivalent to 296 297:: 298 299 WWW.EXAMPLE.COM. CNAME MAIN-SERVER.EXAMPLE.COM. 300 301The **$INCLUDE** Directive 302^^^^^^^^^^^^^^^^^^^^^^^^^^ 303 304Syntax: **$INCLUDE** filename [origin] [comment] 305 306This reads and processes the file **filename** as if it were included in the 307file at this point. The **filename** can be an absolute path, or a relative 308path. In the latter case it is read from :iscman:`named`'s working directory. If 309**origin** is specified, the file is processed with **$ORIGIN** set to that 310value; otherwise, the current **$ORIGIN** is used. 311 312The origin and the current domain name revert to the values they had 313prior to the **$INCLUDE** once the file has been read. 314 315.. note:: 316 317 :rfc:`1035` specifies that the current origin should be restored after 318 an **$INCLUDE**, but it is silent on whether the current domain name 319 should also be restored. BIND 9 restores both of them. This could be 320 construed as a deviation from :rfc:`1035`, a feature, or both. 321 322.. _ttl_directive: 323 324The **$TTL** Directive 325^^^^^^^^^^^^^^^^^^^^^^ 326 327Syntax: **$TTL** default-ttl [comment] 328 329This sets the default Time-To-Live (TTL) for subsequent records with undefined 330TTLs. Valid TTLs are of the range 0-2147483647 seconds. 331 332**$TTL** is defined in :rfc:`2308`. 333 334.. _generate_directive: 335 336BIND Primary File Extension: the **$GENERATE** Directive 337~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 338 339Syntax: **$GENERATE** range owner [ttl] [class] type rdata [comment] 340 341**$GENERATE** is used to create a series of resource records that only 342differ from each other by an iterator. 343 344**range** 345 This can be one of two forms: start-stop or start-stop/step. 346 If the first form is used, then step is set to 1. "start", 347 "stop", and "step" must be positive integers between 0 and 348 (2^31)-1. "start" must not be larger than "stop". 349 350**owner** 351 This describes the owner name of the resource records to be created. 352 353 The **owner** string may include one or more **$** (dollar sign) 354 symbols, which will be replaced with the iterator value when 355 generating records; see below for details. 356 357**ttl** 358 This specifies the time-to-live of the generated records. If 359 not specified, this is inherited using the normal TTL inheritance 360 rules. 361 362 **class** and **ttl** can be entered in either order. 363 364**class** 365 This specifies the class of the generated records. This must 366 match the zone class if it is specified. 367 368 **class** and **ttl** can be entered in either order. 369 370**type** 371 This can be any valid type. 372 373**rdata** 374 This is a string containing the RDATA of the resource record 375 to be created. As with **owner**, the **rdata** string may 376 include one or more **$** symbols, which are replaced with the 377 iterator value. **rdata** may be quoted if there are spaces in 378 the string; the quotation marks do not appear in the generated 379 record. 380 381 Any single **$** (dollar sign) symbols within the **owner** or 382 **rdata** strings are replaced by the iterator value. To get a **$** 383 in the output, escape the **$** using a backslash **\\**, e.g., 384 ``\$``. (For compatibility with earlier versions, **$$** is also 385 recognized as indicating a literal **$** in the output.) 386 387 The **$** may optionally be followed by modifiers which change 388 the offset from the iterator, field width, and base. Modifiers 389 are introduced by a **{** (left brace) immediately following 390 the **$**, as in **${offset[,width[,base]]}**. For example, 391 **${-20,3,d}** subtracts 20 from the current value and prints 392 the result as a decimal in a zero-padded field of width 3. 393 Available output forms are decimal (**d**), octal (**o**), 394 hexadecimal (**x** or **X** for uppercase), and nibble (**n** 395 or **N** for uppercase). The modfiier cannot contain whitespace 396 or newlines. 397 398 The default modifier is **${0,0,d}**. If the **owner** is not 399 absolute, the current **$ORIGIN** is appended to the name. 400 401 In nibble mode, the value is treated as if it were a reversed 402 hexadecimal string, with each hexadecimal digit as a separate 403 label. The width field includes the label separator. 404 405Examples: 406 407**$GENERATE** can be used to easily generate the sets of records required 408to support sub-/24 reverse delegations described in :rfc:`2317`: 409 410:: 411 412 $ORIGIN 0.0.192.IN-ADDR.ARPA. 413 $GENERATE 1-2 @ NS SERVER$.EXAMPLE. 414 $GENERATE 1-127 $ CNAME $.0 415 416is equivalent to 417 418:: 419 420 0.0.0.192.IN-ADDR.ARPA. NS SERVER1.EXAMPLE. 421 0.0.0.192.IN-ADDR.ARPA. NS SERVER2.EXAMPLE. 422 1.0.0.192.IN-ADDR.ARPA. CNAME 1.0.0.0.192.IN-ADDR.ARPA. 423 2.0.0.192.IN-ADDR.ARPA. CNAME 2.0.0.0.192.IN-ADDR.ARPA. 424 ... 425 127.0.0.192.IN-ADDR.ARPA. CNAME 127.0.0.0.192.IN-ADDR.ARPA. 426 427This example creates a set of A and MX records. Note the MX's **rdata** 428is a quoted string; the quotes are stripped when **$GENERATE** is processed: 429 430:: 431 432 $ORIGIN EXAMPLE. 433 $GENERATE 1-127 HOST-$ A 1.2.3.$ 434 $GENERATE 1-127 HOST-$ MX "0 ." 435 436is equivalent to 437 438:: 439 440 HOST-1.EXAMPLE. A 1.2.3.1 441 HOST-1.EXAMPLE. MX 0 . 442 HOST-2.EXAMPLE. A 1.2.3.2 443 HOST-2.EXAMPLE. MX 0 . 444 HOST-3.EXAMPLE. A 1.2.3.3 445 HOST-3.EXAMPLE. MX 0 . 446 ... 447 HOST-127.EXAMPLE. A 1.2.3.127 448 HOST-127.EXAMPLE. MX 0 . 449 450 451This example generates A and AAAA records using modifiers; the AAAA 452**owner** names are generated using nibble mode: 453 454:: 455 456 $ORIGIN EXAMPLE. 457 $GENERATE 0-2 HOST-${0,4,d} A 1.2.3.${1,0,d} 458 $GENERATE 1024-1026 ${0,3,n} AAAA 2001:db8::${0,4,x} 459 460is equivalent to: 461 462:: 463 464 HOST-0000.EXAMPLE. A 1.2.3.1 465 HOST-0001.EXAMPLE. A 1.2.3.2 466 HOST-0002.EXAMPLE. A 1.2.3.3 467 0.0.4.EXAMPLE. AAAA 2001:db8::400 468 1.0.4.EXAMPLE. AAAA 2001:db8::401 469 2.0.4.EXAMPLE. AAAA 2001:db8::402 470 471The **$GENERATE** directive is a BIND extension and not part of the 472standard zone file format. 473 474.. _zonefile_format: 475 476Additional File Formats 477~~~~~~~~~~~~~~~~~~~~~~~ 478 479In addition to the standard text format, BIND 9 supports the ability 480to read or dump to zone files in other formats. 481 482The **raw** format is a binary representation of zone data in a manner 483similar to that used in zone transfers. Since it does not require 484parsing text, load time is significantly reduced. 485 486For a primary server, a zone file in **raw** format is expected 487to be generated from a text zone file by the :iscman:`named-compilezone` command. 488For a secondary server or a dynamic zone, the zone file is automatically 489generated when :iscman:`named` dumps the zone contents after zone transfer or 490when applying prior updates, if one of these formats is specified by the 491**masterfile-format** option. 492 493If a zone file in **raw** format needs manual modification, it first must 494be converted to **text** format by the :iscman:`named-compilezone` command, 495then converted back after editing. For example: 496 497:: 498 499 named-compilezone -f raw -F text -o zonefile.text <origin> zonefile.raw 500 [edit zonefile.text] 501 named-compilezone -f text -F raw -o zonefile.raw <origin> zonefile.text 502