On Thu, Feb 17, 2022 at 09:01:58AM -0800, Evan Silberman wrote:
>
> Inline below. Since I mistakenly believed my first email didn't go and
> just resent it gzipped just in case, I'm now spamming a little bit and I
> apologize; I'll chill out now and await more feedback.
>
hi.
as a start, i advise you to run your page through mandoc's inbuilt
checker:
$ mandoc -Tlint zonefile.5
if any of the issues it flags are unclear, feel free to mail me offlist.
then repost your cleaned page.
i should say that i'm personally not sure about this page. isn;t
this general dns stuff? by that i mean, does openbsd seek to document
such aspects?
jmc
> .\"
> .\" 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 r...@example.org. 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/
