Re: new manual: zonefile.5
On Thu, Feb 17, 2022 at 07:31:47PM GMT, Evan Silberman wrote: > Jason McIntyre wrote: > > as a start, i advise you to run your page through mandoc's inbuilt > > checker > > Yep, done. I've addressed all the ones I think I can properly address. > Date still blank, $OpenBSD$ still absent. It also complains that > .Sh FILES is not in its conventional location but I think that's because > I have nonstandard sections after .Sh DESCRIPTION. Those could be > subsections but mdoc(7) allows for nonstandard sections when it aids > legibility, which I think it does here. > Hi Evan, No, this is because FILES comes before EXAMPLES. > .\" > .\" Copyright (c) 2022 Evan Silberman Also, I don't think this is necessarily wrong, but there's usually a blank line between the Copyright line and the license text. Also, you can simply add: .\" $OpenBSD$ ^ BTW, I never know whether to use a space character or a tab there - I've seen both being used. and: .Dd $Mdocdate$ Regards, Raf > .\" 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 > 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
Re: new manual: zonefile.5
On Thu, Feb 17, 2022 at 11:31:47AM -0800, Evan Silberman wrote: > Jason McIntyre wrote: > > as a start, i advise you to run your page through mandoc's inbuilt > > checker > > Yep, done. I've addressed all the ones I think I can properly address. > Date still blank, $OpenBSD$ still absent. It also complains that > .Sh FILES is not in its conventional location but I think that's because > I have nonstandard sections after .Sh DESCRIPTION. Those could be > subsections but mdoc(7) allows for nonstandard sections when it aids > legibility, which I think it does here. > you can check the section order in mdoc(7). FILES comes before EXAMPLES. the rest is not needed for now, but we would normally have an $Mdocdate$ tag that expands to the date when committing, and an $OpenBSD$ one for cvs revision. i'm going to wait for any other feedback before actually reviewing the content. 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 > 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
Re: new manual: zonefile.5
Jason McIntyre wrote: > as a start, i advise you to run your page through mandoc's inbuilt > checker Yep, done. I've addressed all the ones I think I can properly address. Date still blank, $OpenBSD$ still absent. It also complains that .Sh FILES is not in its conventional location but I think that's because I have nonstandard sections after .Sh DESCRIPTION. Those could be subsections but mdoc(7) allows for nonstandard sections when it aids legibility, which I think it does here. .\" .\" 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 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
Re: new manual: zonefile.5
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, >
Re: new manual: zonefile.5
On 2022/02/17 11:16, Dave Voutila wrote: > > Evan Silberman writes: > > > 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 you offered similar documentation to the upstream nsd project from > NLnet Labs? https://github.com/NLnetLabs/nsd > > > - 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. > > > > I don't work on nsd(8), but getting this into the upstream project and > maintained there would probably make the most sense. I will admit that > since the file isn't inlined in the email, I didn't inspect it so won't > speak to its quality at the moment. They use man formatting not mdoc unfortunately. Could be converted but it's not as *nice* :) (It's equally relevant to BIND and Knot, and at least partially to PowerDNS, all of which seem to use RST as their "base" format for docs). > > If nothing else, this was fun to work on. I've only had a quick read but I like it so far. At least NSD, BIND, knot currently defer to the RFCs for this (mainly 1035 but then you have to pick through a couple of dozen 'updated by' to figure out which extra parts apply) and they're not so informative about real world use, this seems a nice place to mention "gotchas".
Re: new manual: zonefile.5
Oh I guess my first mail made it through after all, dunno what my confusion was. Dave Voutila wrote: > > Evan Silberman writes: > > > 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 you offered similar documentation to the upstream nsd project from > NLnet Labs? https://github.com/NLnetLabs/nsd I thought about it, and maybe I'll go that way if carrying this in OpenBSD doesn't get support, but I have more enthusiasm for and familiarity with contributing to OpenBSD and I spend a limited amount of time doing stuff with computers for fun these days so I'm maximizing my enjoyment by submitting here. > I don't work on nsd(8), but getting this into the upstream project and > maintained there would probably make the most sense. I will admit that > since the file isn't inlined in the email, I didn't inspect it so won't > speak to its quality at the moment. 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. .\" .\" 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
Re: new manual: zonefile.5
Evan Silberman writes: > 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 you offered similar documentation to the upstream nsd project from NLnet Labs? https://github.com/NLnetLabs/nsd > - 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. > I don't work on nsd(8), but getting this into the upstream project and maintained there would probably make the most sense. I will admit that since the file isn't inlined in the email, I didn't inspect it so won't speak to its quality at the moment. > If nothing else, this was fun to work on. >
new manual: zonefile.5
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
