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   3600    DYNA    some_plugin!resource_name
      alias         CNAME   www

      _http._tcp    1800    SRV     5 500 80 www

      foo           TXT     "blah blah" "blah"
      _spf          SPF+    "v=spf1 ..."

DESCRIPTION

    This is the 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.

DIRECTIVES

    The standard $TTL and $ORIGIN directives are supported with their normal
    syntax.

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

    $ADDR_LIMIT_V6 same as above, but for IPv6 "AAAA" rrsets.

    The RFC-standard $INCLUDE directive is not supported. It greatly
    complicates the detection of zone update transactions. 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.

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, SPF, 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 three special-case, non-standard virtual
    resource record types:

  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 it is up
    to the plugin code which addresses of which types to return in the
    response.

    The dynamic plugin response will be generated in answer to A or AAAA
    queries for the given name, and contain A and/or AAAA resource records
    as appropriate. "DYNA" cannot co-exist with actual static A or AAAA
    records at the same name.

  DYNC

    "DYNC" is "DYNA"'s counterpart for dynamically-determined CNAME records
    via plugin code.

  SPF+

    "SPF+" is simply shorthand for specifying a single set of text data
    which is duplicated as both TXT and SPF records at the same name. It is
    always equivalent to removing the "+", copying the whole record, and
    changing "SPF" to "TXT" in the second copy.

    Our "TXT" (and SPF, and SPF+) RRs support the auto-splitting of long
    string constants. Rather than manually breaking the data into 255-byte
    chunks, 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.)

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

