
=head1 NAME

gdnsd.zonefile - gdnsd zonefile syntax

=head1 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 ..."

=head1 DESCRIPTION

This is the zonefile syntax for L<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.

=head1 DIRECTIVES

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

C<$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 C<$TTL> setting, the default TTL comes from the
global config option C<zones_default_ttl>, which in turn defaults
to C<86400> (1 day).

C<$ORIGIN> changes what is appended to unqualified hostnames
(those lacking a final C<.>) seen in the zone file from that
point forward, as well as any C<@> entries (which is an alias
for the current origin).  C<$ORIGIN> itself may also be an unqualified
name, in which case the previous origin is appended to it.
Any fully-qualified C<$ORIGIN> must be within the zone described
by this zonefile.  The default origin is the zone name itself.

C<$ADDR_LIMIT_V4> is a non-standard, gdnsd-specific directive.
It requires a single unsigned integer argument.  The argument
limits the total number of C<A> records to include in the server's
responses for any given C<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.

C<$ADDR_LIMIT_V6> same as above, but for IPv6 C<AAAA> rrsets.

The RFC-standard C<$INCLUDE> directive is not supported.  It
greatly complicates the detection of zone update transactions.
Most legitimate uses of C<$INCLUDE> to reduce redundancy
should be replaced with a zonefile-generating script instead,
perhaps using a template system.

BIND's C<$GENERATE> extension is not supported at this time.

=head1 SUPPORTED RESOURCE RECORD TYPES

L<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 C<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 C<IN> RRs.

Additionally, gdnsd supports three special-case, non-standard
virtual resource record types:

=head2 DYNA

C<DYNA> is for dynamically-determined address records (both A
and AAAA) via plugin code.  The right-hand-side of a C<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.  C<DYNA> cannot co-exist with
actual static A or AAAA records at the same name.

=head2 DYNC

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

=head2 SPF+

C<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 C<+>, copying the
whole record, and changing C<SPF> to C<TXT> in the second copy.

Our C<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 L<gdnsd.config(5)> as well.)

=head1 SEE ALSO

L<gdnsd(8)>, L<gdnsd.config(5)>

The gdnsd manual.

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

=cut
