Ubuntu Manpage: gdnsd.zonefile - gdnsd zonefile syntax

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

All RRs must be of class "IN", which is the implicit default.

gdnsd(8) supports the following standard RR types with their standard RDATA formats:

traditional: SOA, A, AAAA, NS, PTR, CNAME, MX, SRV, TXT, NAPTR non-traditional: CAA

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.

gdnsd does not allow using the RFC3597 format to specify any of the traditional standard
RR types, but it can be used to encode data for the non-traditional types.

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).

COPYRIGHT AND LICENSE