NAME¶
gdnsd.zonefile - gdnsd zonefile syntax
SYNOPSIS¶
example.com:
$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 ..."
DESCRIPTION¶
This is the primary zonefile syntax for
gdnsd(8). The syntax is designed
to be as close as possible to the standard zonefile syntax from RFC 1035
(which is the "standard" format one typically sees with traditional
BIND servers). This document will just cover a few important highlights and/or
deviations from the norm.
DIRECTIVES¶
The standard $TTL and $ORIGIN directives are supported with their normal syntax
and semantics.
$TTL changes the default TTL of any records coming after it, and can occur
multiple times. Note that in the absence of a zonefile-level $TTL setting, the
default TTL comes from the global config option "zones_default_ttl",
which in turn defaults to 86400 (1 day).
$ORIGIN changes what is appended to unqualified hostnames (those lacking a final
".") seen in the zone file from that point forward, as well as any
"@" entries (which is an alias for the current origin). $ORIGIN
itself may also be an unqualified name, in which case the previous origin is
appended to it. Any fully-qualified $ORIGIN must be within the zone described
by this zonefile. The default origin is the zone name itself.
$ADDR_LIMIT_V4 is a non-standard, gdnsd-specific directive. It requires a single
unsigned integer argument. The argument limits the total number of
"A" records to include in the server's responses for any given
"A" 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.
$ADDR_LIMIT_V6 same as above, but for IPv6 "AAAA" rrsets.
The RFC-standard $INCLUDE 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 $INCLUDE to
reduce redundancy should be replaced with a zonefile-generating script
instead, perhaps using a template system.
BIND's $GENERATE extension is not supported at this time, but there's no
fundamental reason it couldn't be added at a later date.
SUPPORTED RESOURCE RECORD TYPES¶
gdnsd(8) supports the following standard RR types with their standard
RDATA formats: SOA, A, AAAA, NS, PTR, CNAME, MX, SRV, TXT, and NAPTR. All RRs
must be in class "IN", which is the implicit default.
It also supports the generic format for unknown RR types documented in RFC 3597,
which has syntax like:
foo TYPE31337 \# 10 0123456789 ABCDEF0123
... which indicates an RR of numeric type 31337 containing 10 bytes of RDATA,
specified as the final part of the RR as a pair of 5-byte hex strings. See RFC
3597 itself for full details. Note however that gdnsd does not allow using the
RFC 3597 format for types gdnsd explicitly supports (all of which predate 3597
anyways), and that even in the RFC 3597 case we still only allow class
"IN" RRs.
Additionally, gdnsd supports two special-case, non-standard virtual resource
record types DYNA and DYNC:
DYNA¶
"DYNA" is for dynamically-determined address records (both A and AAAA)
via plugin code. The right-hand-side of a "DYNA" RR is a plugin name
and a resource name separated by an exclamation mark. The named plugin will be
fed the resource name and the DNS client's IP 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.
The dynamic plugin lookup for "DYNA" will be used anywhere that
regular "A" and/or "AAAA" records would be used. This
includes not only direct responses to "A" and "AAAA"
queries, but also things like Additional-section RRs and "ANY"-query
output. "DYNA" cannot co-exist with actual static A or AAAA records
at the same name, but can co-exist with any other RR-type.
Example:
; asks plugin 'geoip' to provide address data from
; its resource named 'pubwww' for address queries.
foo DYNA geoip!pubwww
foo MX 10 mail
DYNC¶
"DYNC" has the same syntax as "DYNA" above, but different
data rules. Plugins results returned via "DYNC" can be either
addresses or a "CNAME" record. "DYNC" cannot co-exist with
any other resource record at the same name, much like normal
"CNAME" RRs. This also implies that "DYNC" cannot be used
at the zone root, as the zone root requires "NS" and "SOA"
RRs. While "DYNC" responses are included in "ANY" queries
for the given name, they are
not used in Additional-section processing,
even when the plugin responds with address records rather than
"CNAME".
Example:
; asks plugin 'geoip' to provide address data or a CNAME
; (at the plugin's discretion) for its resource named
; 'www'. No other RRs of any type for name 'foo' are
; legal alongside this record.
foo DYNC geoip!www
DYNA/DYNC TTLs¶
"DYNA" and "DYNC" TTL fields have a syntax extension and
slightly different meanings than the TTL field of a traditional, fixed RR. The
format for DYNA/DYNC TTLs is "MAX[/MIN]", with "MIN"
defaulting to half of "MAX" if not specified explicitly.
Based on the configuration and state of the underlying monitored services, (see
"service_types" in
gdnsd.config(8)), gdnsd knows the minimum
time to the next possible state-change which could affect a given
"DYNA" or "DYNC" result. For example, given the
configuration and state, it may be known that in order for a currently
"DOWN" address to transition to the "UP" 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
TTL.
In cases where multiple monitored resources factor into a plugin's decision
and/or response (e.g. multifo), the calculated TTL will generally be the
minimum of all involved internal monitoring TTLs. This calculated TTL is then
clamped to the "MAX" and "MIN" limits from the zonefile.
Examples:
; 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
TXT data auto-splitting¶
gdnsd's "TXT" 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
gdnsd.config(5) as well, which will turn oversized chunks into zonefile
parsing errors).
SEE ALSO¶
gdnsd(8),
gdnsd.config(5)
The gdnsd manual.
COPYRIGHT AND LICENSE¶
Copyright (c) 2012 Brandon L Black <blblack@gmail.com>
This file is part of gdnsd.
gdnsd is free software: you can redistribute it and/or modify it under the terms
of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.
gdnsd is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with
gdnsd. If not, see <
http://www.gnu.org/licenses/>.