.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "GDNSD.ZONEFILE 5" .TH GDNSD.ZONEFILE 5 "2015-05-14" "gdnsd 2.1.2" "gdnsd" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" gdnsd.zonefile \- gdnsd zonefile syntax .SH "SYNOPSIS" .IX Header "SYNOPSIS" example.com: .PP .Vb 1 \& $TTL 86400 \& \& @ SOA ns1 hostmaster ( \& 1 ; serial \& 7200 ; refresh \& 30M ; retry \& 3D ; expire \& 900 ; ncache \& ) \& \& @ NS ns1.example.com. \& @ NS ns2 \& @ NS ns.example.net. \& \& ns1 A 192.0.2.1 ; a comment \& ns2.example.com. A 192.0.2.2 \& \& @ 7200 MX 10 mail\-a \& @ 7200 MX 100 mail\-b \& \& $ttl 86400 \& ; a comment \& mail\-a A 192.0.2.3 \& mail\-b A 192.0.2.4 \& \& subz NS ns1.subz \& subz NS ns2.subz \& ns1.subz A 192.0.2.5 \& ns2.subz A 192.0.2.6 \& \& www 600/10 DYNA some_plugin!resource_name \& alias CNAME www \& \& _http._tcp 1800 SRV 5 500 80 www \& \& foo TXT "blah blah" "blah" \& _spf TXT "v=spf1 ..." .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This is the primary zonefile syntax for \fIgdnsd\fR\|(8). The syntax is designed to be as close as possible to the standard zonefile syntax from \s-1RFC 1035 \s0(which is the \*(L"standard\*(R" format one typically sees with traditional \s-1BIND\s0 servers). This document will just cover a few important highlights and/or deviations from the norm. .SH "DIRECTIVES" .IX Header "DIRECTIVES" The standard \f(CW$TTL\fR and \f(CW$ORIGIN\fR directives are supported with their normal syntax and semantics. .PP \&\f(CW$TTL\fR changes the default \s-1TTL\s0 of any records coming after it, and can occur multiple times. Note that in the absence of a zonefile-level \f(CW$TTL\fR setting, the default \s-1TTL\s0 comes from the global config option \f(CW\*(C`zones_default_ttl\*(C'\fR, which in turn defaults to \f(CW86400\fR (1 day). .PP \&\f(CW$ORIGIN\fR changes what is appended to unqualified hostnames (those lacking a final \f(CW\*(C`.\*(C'\fR) seen in the zone file from that point forward, as well as any \f(CW\*(C`@\*(C'\fR entries (which is an alias for the current origin). \f(CW$ORIGIN\fR itself may also be an unqualified name, in which case the previous origin is appended to it. Any fully-qualified \f(CW$ORIGIN\fR must be within the zone described by this zonefile. The default origin is the zone name itself. .PP \&\f(CW$ADDR_LIMIT_V4\fR is a non-standard, gdnsd-specific directive. It requires a single unsigned integer argument. The argument limits the total number of \f(CW\*(C`A\*(C'\fR records to include in the server's responses for any given \f(CW\*(C`A\*(C'\fR rrset (whether static or dynamic). The default limit is zero, which is interpreted as no limit. Setting the limit via this directive affects all rrsets until the value is changed again by another directive. gdnsd always rotates the RRs of an address RR-set in a round-robin fashion, and this rotation occurs before the limit is applied, allowing a small pseudo-random subset of a larger list to be delivered via this mechanism. .PP \&\f(CW$ADDR_LIMIT_V6\fR same as above, but for IPv6 \f(CW\*(C`AAAA\*(C'\fR rrsets. .PP The RFC-standard \f(CW$INCLUDE\fR directive is not supported because it would greatly complicate the detection of zone update transactions with our current filesystem-based change detection scheme. Most legitimate uses of \f(CW$INCLUDE\fR to reduce redundancy should be replaced with a zonefile-generating script instead, perhaps using a template system. .PP \&\s-1BIND\s0's \f(CW$GENERATE\fR extension is not supported at this time, but there's no fundamental reason it couldn't be added at a later date. .SH "SUPPORTED RESOURCE RECORD TYPES" .IX Header "SUPPORTED RESOURCE RECORD TYPES" \&\fIgdnsd\fR\|(8) supports the following standard \s-1RR\s0 types with their standard \s-1RDATA\s0 formats: \s-1SOA, A, AAAA, NS, PTR, CNAME, MX, SRV, TXT,\s0 and \s-1NAPTR. \s0 All RRs must be in class \f(CW\*(C`IN\*(C'\fR, which is the implicit default. .PP It also supports the generic format for unknown \s-1RR\s0 types documented in \s-1RFC 3597,\s0 which has syntax like: .PP .Vb 1 \& foo TYPE31337 \e# 10 0123456789 ABCDEF0123 .Ve .PP \&... which indicates an \s-1RR\s0 of numeric type 31337 containing 10 bytes of \s-1RDATA,\s0 specified as the final part of the \s-1RR\s0 as a pair of 5\-byte hex strings. See \s-1RFC 3597\s0 itself for full details. Note however that gdnsd does not allow using the \&\s-1RFC 3597\s0 format for types gdnsd explicitly supports (all of which predate 3597 anyways), and that even in the \s-1RFC 3597\s0 case we still only allow class \f(CW\*(C`IN\*(C'\fR RRs. .PP Additionally, gdnsd supports two special-case, non-standard virtual resource record types \s-1DYNA\s0 and \s-1DYNC:\s0 .SS "\s-1DYNA\s0" .IX Subsection "DYNA" \&\f(CW\*(C`DYNA\*(C'\fR is for dynamically-determined address records (both A and \s-1AAAA\s0) via plugin code. The right-hand-side of a \f(CW\*(C`DYNA\*(C'\fR \&\s-1RR\s0 is a plugin name and a resource name separated by an exclamation mark. The named plugin will be fed the resource name and the \s-1DNS\s0 client's \s-1IP\s0 address and/or edns-client-subnet information, and it is up to the plugin code which addresses of which types to return in the response. .PP The dynamic plugin lookup for \f(CW\*(C`DYNA\*(C'\fR will be used anywhere that regular \f(CW\*(C`A\*(C'\fR and/or \f(CW\*(C`AAAA\*(C'\fR records would be used. This includes not only direct responses to \f(CW\*(C`A\*(C'\fR and \f(CW\*(C`AAAA\*(C'\fR queries, but also things like Additional-section RRs and \f(CW\*(C`ANY\*(C'\fR\-query output. \&\f(CW\*(C`DYNA\*(C'\fR cannot co-exist with actual static A or \s-1AAAA\s0 records at the same name, but can co-exist with any other RR-type. .PP Example: .PP .Vb 4 \& ; asks plugin \*(Aqgeoip\*(Aq to provide address data from \& ; its resource named \*(Aqpubwww\*(Aq for address queries. \& foo DYNA geoip!pubwww \& foo MX 10 mail .Ve .SS "\s-1DYNC\s0" .IX Subsection "DYNC" \&\f(CW\*(C`DYNC\*(C'\fR has the same syntax as \f(CW\*(C`DYNA\*(C'\fR above, but different data rules. Plugins results returned via \f(CW\*(C`DYNC\*(C'\fR can be either addresses or a \f(CW\*(C`CNAME\*(C'\fR record. \f(CW\*(C`DYNC\*(C'\fR cannot co-exist with \fBany\fR other resource record at the same name, much like normal \f(CW\*(C`CNAME\*(C'\fR RRs. This also implies that \f(CW\*(C`DYNC\*(C'\fR cannot be used at the zone root, as the zone root requires \f(CW\*(C`NS\*(C'\fR and \f(CW\*(C`SOA\*(C'\fR RRs. While \f(CW\*(C`DYNC\*(C'\fR responses are included in \f(CW\*(C`ANY\*(C'\fR queries for the given name, they are \fBnot\fR used in Additional-section processing, even when the plugin responds with address records rather than \f(CW\*(C`CNAME\*(C'\fR. .PP Example: .PP .Vb 5 \& ; asks plugin \*(Aqgeoip\*(Aq to provide address data or a CNAME \& ; (at the plugin\*(Aqs discretion) for its resource named \& ; \*(Aqwww\*(Aq. No other RRs of any type for name \*(Aqfoo\*(Aq are \& ; legal alongside this record. \& foo DYNC geoip!www .Ve .SS "\s-1DYNA/DYNC\s0 TTLs" .IX Subsection "DYNA/DYNC TTLs" \&\f(CW\*(C`DYNA\*(C'\fR and \f(CW\*(C`DYNC\*(C'\fR \s-1TTL\s0 fields have a syntax extension and slightly different meanings than the \s-1TTL\s0 field of a traditional, fixed \s-1RR.\s0 The format for \s-1DYNA/DYNC\s0 TTLs is \f(CW\*(C`MAX[/MIN]\*(C'\fR, with \f(CW\*(C`MIN\*(C'\fR defaulting to half of \f(CW\*(C`MAX\*(C'\fR if not specified explicitly. .PP Based on the configuration and state of the underlying monitored services, (see \*(L"service_types\*(R" in \fIgdnsd.config\fR\|(8)), gdnsd knows the minimum time to the next possible state-change which could affect a given \f(CW\*(C`DYNA\*(C'\fR or \&\f(CW\*(C`DYNC\*(C'\fR result. For example, given the configuration and state, it may be known that in order for a currently \f(CW\*(C`DOWN\*(C'\fR address to transition to the \f(CW\*(C`UP\*(C'\fR state (and thus change the answer to a given query) would require 7 more successful monitoring checks in a row at 8\-second intervals, and therefore cannot happen in less than 56 seconds. In this case 56 seconds would be the internally-calculated \s-1TTL.\s0 .PP In cases where multiple monitored resources factor into a plugin's decision and/or response (e.g. multifo), the calculated \s-1TTL\s0 will generally be the minimum of all involved internal monitoring TTLs. This calculated \&\s-1TTL\s0 is then clamped to the \f(CW\*(C`MAX\*(C'\fR and \f(CW\*(C`MIN\*(C'\fR limits from the zonefile. .PP Examples: .PP .Vb 6 \& ; Explicit range of 30 \- 300: \& www 300/30 DYNC weighted!foo \& ; Implicit range of 150 \- 300: \& www 300 DYNA metafo!myservice \& ; Avoid all TTL\-mangling and use a fixed value of 10 minutes: \& www 600/600 DYNA geoip!foo\-dist .Ve .SS "\s-1TXT\s0 data auto-splitting" .IX Subsection "TXT data auto-splitting" gdnsd's \f(CW\*(C`TXT\*(C'\fR RRs support the auto-splitting of long string constants. Rather than manually breaking the data into 255\-byte chunks as required by the protocol, you can specify a single long chunk and have the server break it at 255 byte boundaries automatically. (this behavior can be disabled via \fIgdnsd.config\fR\|(5) as well, which will turn oversized chunks into zonefile parsing errors). .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIgdnsd\fR\|(8), \fIgdnsd.config\fR\|(5) .PP The gdnsd manual. .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright (c) 2012 Brandon L Black .PP This file is part of gdnsd. .PP gdnsd is free software: you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. .PP gdnsd is distributed in the hope that it will be useful, but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE. \s0 See the \&\s-1GNU\s0 General Public License for more details. .PP You should have received a copy of the \s-1GNU\s0 General Public License along with gdnsd. If not, see .