Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GDNSD.ZONEFILE(5)		     gdnsd		     GDNSD.ZONEFILE(5)

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, $ORIGIN, and $INCLUDE	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.

       $INCLUDE	includes another file as if its	contents existed at the	point
       of the $INCLUDE directive.  Include directives may specify an optional
       origin, which has the same effect as $ORIGIN at the top of the included
       file.  Changes to the origin (and default ttl) within included files
       have no effect on the outer file.

       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.

SPECIAL	NAMES AND ORIGINS
       The standard "@", as a whole name, is supported as an alias for the
       current origin.	In addition to this, gdnsd implements two special
       extensions @Z and @F.  These denote the current zone name, and the
       original	origin (before any internal $ORIGIN declarations) of the file
       currently being parsed.	Unlike "@", they can also be used as the final
       label of	an unqualified name.  @Z and @F	will always be equivalent to
       each other in the main zonefile for a zone, but may differ when parsing
       included	files from "$INCLUDE".	As an example:

	   * zones/example.org has the line "$INCLUDE includes/foo foo"
	   * zones/includes/foo	has these lines:
	      $ORIGIN bar
	      asdf A 192.0.2.1
	      $ORIGIN baz.@F
	      asdf A 192.0.2.2
	      $ORIGIN quux.@Z
	      asdf A 192.0.2.3
	   * This results in creating all of these:
	      asdf.bar.foo.example.org A 192.0.2.1
	      asdf.baz.foo.example.org A 192.0.2.2
	      asdf.quux.example.org    A 192.0.2.3

       Note that the origin changes accomplished with @F and @Z	backtrack
       towards the root	of the name hierarchy, and thus	wouldn't normally be
       possible	without	explicitly using the zone name itself.	The main
       benefit of these	directives is they allow this kind of origin-switching
       behavior	while keeping all zone data relative to	the zone name rather
       than absolute.  When combined with the fact that	the zones scanner will
       load symlinks, this means the above zones/example.org could also	be
       symlinked as zones/example.com, loading all the same files and
       providing an identical tree of data under the other zone	name without
       conflict.

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	explicitly unsupported:	HINFO

       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
       supported traditional standard RR types,	but it can be used to encode
       data for	the non-traditional types.  It's also not allowed to use
       RFC3597 to specify HINFO	RRs, as	these are now reserved in gdnsd	for
       use in handling "ANY" queries, using the	RFC 8482 HINFO option.

       "SOA" records' negative-caching TTL is set to the minimum of the
       traditional "minimum" (last) field (which always	means "negative	cache
       TTL" as of RFC 2308), and the actual TTL	of the SOA record itself.
       This TTL	is used	as the actual TTL of the SOA record any	time it	is
       emitted,	whether	for negative or	positive answers.

       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.	 "DYNA"	cannot co-exist	with
       actual static A or AAAA records at the same name, but can co-exist with
       any other RR-type.

       "DYNA" and "DYNAAAA" RRs	cannot be used to supply the addresses of
       nameservers.  In	other words, any name that exists in zone scope	on the
       right-hand-side of an "NS" record cannot	have "DYNA" or "DYNAAAA" (and
       relatedly, must have at least one of "A"	or "AAAA").

       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.

       "DYNC"'s	dynamic	CNAME targets cannot be	used to	point at names in the
       same zonefile as	the "DYNC" record; they	must be	used to	point at other
       zones.

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

       TXT records are limited to a maximum of 16000 bytes when	encoded	in
       rdata form for wire transmission.

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

gdnsd 3.0.0			  2020-08-31		     GDNSD.ZONEFILE(5)

NAME | SYNOPSIS | DESCRIPTION | DIRECTIVES | SPECIAL NAMES AND ORIGINS | SUPPORTED RESOURCE RECORD TYPES | SEE ALSO | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=gdnsd.zonefile&sektion=5&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help