OpenBSD is distributed with an authoritative name server daemon, nsd(8), but that distribution doesn't document the format of zone files in manual section 5. I thought hey, you should be able to read about zone files in the manual. So I took a stab at writing zonefile.5, attached.
I did my best to address nearly all important details of zonefiles as standardized, as well as a useful subset of the RR type zoo. Included is a description of SRV records, which might not be useful/relevant enough for most administrators. Excluded is a description of CAA records, which are probably increasingly useful to cautious administrators but which I haven't used and seem to have more complexity than I want to boil down for a manual. I am interested in feedback in general, and also specifically on the following: - have I included more detail than OpenBSD might want to be responsible for documenting? - have I excluded any RR types that many people will want to read about? - have I used mdoc(7) properly? (I use Ic to mark up RR types and Ar to mark up the fields of RDATA. Makes sense to me and renders nicely but I can understand wanting to dispute this idea.) - have I described an RR type or some clarification that's in an RFC I didn't reference? I'm happy to respond to feedback and resubmit complete drafts, but if this is promising enough for OpenBSD developers to commit, I'm happy to send diffs in response to feedback as well. If nothing else, this was fun to work on. Regards, Evan Silberman
.\" .\" Copyright (c) 2022 Evan Silberman .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .Dd .Dt ZONEFILE 5 .Os .Sh NAME .Nm zonefile .Nd DNS authoritative zone definition file format .Sh DESCRIPTION A .Nm is a standardized textual representation of records in the Domain Name System. Zone files are used to define the records served by authoritative nameservers such as .Xr nsd 8 . .Pp Zone files are line-oriented; that is, each line of the file is generally a seperate entry. An entry can be split onto multiple lines by surrounding data fields with parentheses. Any newline characters within parentheses are ignored and the data within treated as a continuation of the preceding entry. .Pp Domain names in a zone file consist of labels separated by periods .Pq referred to as Dq dots . A .Tg label .Sy label is any string of bytes. A domain name ending in a dot is called .Tg absolute .Sy absolute or .Sy fully-qualified ; a domain name not ending in a dot is called .Tg relative .Sy relative and is processed as if it were followed by a dot and the current origin domain name, as indicated by the .Ic $ORIGIN and .Ic $INCLUDE directives (see below). .Pp While a label may be any arbitrary string of characters, most domain names in a zone file will be Internet host names. A .Tg host .Sy host name is a domain name whose labels consist only of ASCII letters, digits, and hyphens .Pq Dq - , and do not begin or end with a hyphen. .Pp A semicolon .Pq Dq ; is used to begin a comment. Text from the semicolon to the end of the line is ignored. .Pq A backslash .Pq Dq \ followed by a non-digit character quotes the following character and any special meaning it has is ignored. Thus, a label may include periods, semicolons, or parentheses by quoting them. .Sh DIRECTIVES Directives in a zone file begin with a dollar sign, and affect the processing of the zone file. There are only three directives commonly supported by authoritative name server daemons: .Bl -tag -width Ds .It Ic $ORIGIN Ar origin Set the absolute name .Ar origin as the origin domain for relative names in following resource record entries. The origin remains the same until another .Ic $ORIGIN is reached. Note that the origin is applied to relative names in both the .Ar name field of a resource record and in any fields of the record .Ar data that are domain names. .It Ic $INCLUDE Ar file Op Ar origin Include and process the contents of .Ar file before processing the remaining entries in this file. If an .Ar origin is given, it will be set as the origin when processing records in .Ar file . The .Ic $INCLUDE directive never changes the current origin of the including file, regardless of any .Ic $ORIGIN or .Ic $INCLUDE directives in the included .Ar file . .It Ic $TTL Ar ttl Use .Ar ttl as the time-to-live value for all resource records with a blank .Ar ttl field. .El .Sh RESOURCE RECORDS .Pp A resource record has the general form: .Bd -ragged -offset indent .Ar name .Ar ttl .Ar class .Ar type .Ar data .Ed .Pp The .Ar name field is a domain name, as described above. If it ends with a dot, it is used as-is. If its last label is not followed by a dot, a dot and the current origin are appended. A lone .Tg @ .Dq @ given as the .Ar name is a shorthand for the current origin. If the .Ar name is left blank, by beginning the resource record's line with a space character, the last stated .Ar name in the file will be reused. .Pp The .Ar ttl , or .Dq time-to-live , is a number giving the maximum time, in seconds, for which clients should save and reuse the record before querying for it again. .Pp The .Ar class is a string identifying the DNS namespace the record belongs to. In practice, essentially all DNS records use the class .Dq IN , for .Dq Internet . The only other assigned values for .Ar class are .Dq CH , for .Dq Chaosnet , and .Dq HS , for .Dq Hesiod , and are of chiefly historical interest. The .Ar class may be omitted, in which case the last stated .Ar class will be reused. Every resource record in a zone file should belong to the same .Ar class . .Pp The resource record .Ar type is a string indicating the meaning of the resource record's .Ar data . There are many defined .Ar type Ns No s; some of the most important are described below. .Pp Finally, the record .Ar data is given as one or more arbitrary strings separated by spaces. The meaning of .Ar data depends on the resource record .Ar type . .Sh RESOURCE RECORD TYPES Many resource record types are defined, most of which are in use on the Internet to at least some extent. Some of the most common types required to provide names for hosts and Internet services are described below. This section describes the record data format used within zone files. The actual encoding of the record data in the DNS protocol is not discussed here. .Bl -tag -width Ds .It Ic SOA Ar mname rname serial refresh retry expire min-ttl An .Ic SOA .Pq Dq start of authority record defines a number of control values for a DNS zone. Every zone file begins with a single .Ic SOA record. Most of the .Ic SOA subfields provide instructions to recursive nameservers .Pq those queried directly by clients as to how to cache the zone data. .Bl -tag -width Ds .It Ar mname The host name of the main or primary authoritative name server for this zone. .It Ar rname An email address for the party responsible for the zone. The address is encoded as a domain name, with the first unquoted dot standing in for the .Dq @ in the email address. .It Ar serial A serial or version number for the zone. Administrators maintaining zone files should increment this number whenever changing other data in the zone file. A common scheme for maintaining the .Ar serial is to encode the current date into a numeric string, followed by a within-day serial number, such as .Dq 2020082902 for the second version of August 29, 2020. .Po As the value of .Ar serial is encoded as a 32 bit unsigned integer, using the time of day in this scheme is not possible. .Pc .It Ar refresh The interval in seconds that other name servers should wait before proactively refreshing the zone. .It Ar retry The interval in seconds that other name servers should wait before retrying a failed refresh. .It Ar expire The maximum time in seconds that other name servers should retain their version of the zone. After the interval given by .Ar expire elapses, other name servers should stop responding to queries with their cached zone data. .It Ar min-ttl The minimum time-to-live that nameservers should respond with for records in this zone. .El .It Ic NS Ar nameserver Indicates that .Ar nameserver is the host name of an authoritative nameserver for the record's .Ar name . .Ar nameserver must have an .Ic A or .Ic AAAA record in DNS; it must not be a .Ic CNAME . .It Ic A Ar address An IPv4 .Ar address for the named host, written in dotted-quad format. .It Ic AAAA Ar address An IPv6 .Ar address for the named host, written in colon-separated format. .It Ic CNAME Ar canonical-name Indicates that the record's .Ar name is an alias for the domain name .Ar canonical-name . .It Ic MX Ar priority mail-exchange The host at the domain named .Ar mail-exchange may receive Internet mail intended for .Ar name . When multiple .Ic MX records are provided for the same .Ar name , records with lower numeric .Ar priority values .Pq which must be in the range 0-65535 are preferred. The .Ar mail-exchange must be a host name with an .Ic A or .Ic AAAA record in DNS; it may not be a .Ic CNAME . .It Ic TXT Ar string Op Ar string ... Arbitrary .Ar string values, the meaning of which may be defined by the application and the .Ar name of the record, or which may have no meaning at all. One common use of .Ic TXT records is to prove control over .Ar name to a service provider, by publishing a challenge .Ar string shared by the provider and and waiting for them to read it back from the .Ic TXT record over DNS. .It Ic SRV Ar priority Ar weight Ar port Ar target Indicates that a specific service is available on the .Ar target host on the given .Ar port . Unlike other common record types, the .Ar name of a .Ic SRV record has a meaningful format: .Bd -ragged -offset indent .Sm off _ .Ar service . .Ns _ .Ar proto . .Ar host-name .Sm on .Ed .Pp where .Ar service is the name of the service being advertised and .Ar proto is the protocol (usually .Cm TCP or .Cm UDP over which the service is offered. The underscore .Pq Dq _ character preceding the .Ar service and .Ar proto labels are chosen to prevent conflicts with domain names that are host names. The .Ar host-name is the domain name for which the .Ar target host provides the advertised service. .Pp The .Ar priority , like the similar field in .Ic MX records, is a number from 0 to 65535 indicating the relative priority of the .Ar target host among all hosts providing .Ar service for .Ar host-name . Clients are meant to try .Ar target Ns s with the lowest-numbered .Ar priority before trying higher-numbered .Ar target Ns s. The .Ar weight is, again, a number from 0 to 65535 which gives the relative likelihood with which clients should contact the given .Ar target for .Ar service among all .Ar target Ns s with the same .Ar priority . If all .Ar target Ns s have a .Ar weight of 0, clients should choose between them with equal probability. If any matching records have a weight greater than 0, records that have weight 0 have a very small chance of being selected by clients. .El .Sh EXAMPLES The following example zone file defines some records for the domain .Dq example.org. . .Bd -literal -offset indent ; example.org.zone $ORIGIN example.org. ; @ is replaced with the origin. root.example.org.' represents ; the email address [email protected]. The TTL of 86400 tells ; resolvers they can cache this record for up to 24 hours. ; The record is split over multiple lines by enclosing a portion of ; the data in parentheses. The trailing comments labeling the fields ; are also ignored. @ 86400 IN SOA ns1.example.org. root.example.org. ( 2020082201 ; serial 10800 ; refresh 3600 ; retry 604800 ; expire 3600 ) ; minimum ttl ; The name and TTL are omitted from these records, so the ; previously stated example.org. and 86400 are reused IN NS ns1.example.org. IN NS ns2.example.org. ; A primary and backup mail server for example.org. IN MX 10 mail.example.org. IN MX 20 mail-backup.example.org. ; The name is omitted but a shorter TTL of 3600 seconds (1 hour) is ; used. Clients should check to see if the address of example.org. ; has changed after an hour. 3600 IN A 10.0.0.100 ; www is a relative name, so it is processed with the origin ; appended after a dot. Thus this line is a CNAME record with the ; name www.example.org. The TTL is omitted, so the previously ; stated value of 3600 is reused. www IN CNAME example.org. ; These are the addresses of the mail servers indicated by the ; above MX records. mail IN A 10.0.0.40 mail-backup IN A 10.0.0.50 ; user1.example.org. is an absolute name ending in a dot user1.example.org. IN A 10.0.0.121 ; user2.example.org is a relative name not ending in a dot, so this ; record will end up with the name user2.example.org.example.org. user2.example.org IN A 10.0.0.122 .Ed .Sh STANDARDS .Rs .%A P. Mockapetris .%D November 1987 .%R RFC 1034 .%T DOMAIN NAMES - CONCEPTS AND FACILITIES .Re .Pp .Rs .%A P. Mockapetris .%D November 1987 .%R RFC 1035 .%T DOMAIN NAMES - IMPLEMENTATION AND SPECIFICATION .Re .Pp .Rs .%A A. Gulbrandsen .%A P. Vixie .%A L. Esibov .%D February 2000 .%R RFC 2782 .%T A DNS RR for specifying the location of services (DNS SRV) .Re .Pp .Rs .%A S. Thomson .%A C. Huitema .%A V. Ksinant .%A M. Souissi .%D October 2003 .%R RFC 3596 .%T DNS Extensions to Support IP Version 6 .Re .Sh FILES Zonefiles for .Xr nsd 8 are read from .Pa /var/nsd/zones/master/
