.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "GDNSD.CONFIG 5"
.TH GDNSD.CONFIG 5 "2021-02-11" "gdnsd 2.4.3" "gdnsd"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
gdnsd.config \- gdnsd configuration file
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\& options => {
\& log_stats => 86400
\& tcp_timeout => 15 ; zonefile\-style comment
\& include_optional_ns => true
\& listen => [ 127.0.0.1, 192.0.2.1 ]
\& }
\&
\& # shell\-style comment
\&
\& service_types => {
\& foosvc => { plugin => http_status, vhost => www.example.com, url_path => "/checkme" }
\& barsvc => $include{bar\-svc.cfg}
\& $include{other\-services.cfg}
\& }
\&
\& plugins => {
\& null => {}
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This man page describes the syntax of the primary gdnsd
configuration file. The primary config file is always the
the file named \fIconfig\fR in the configuration directory.
The default configuration directory is \fI/etc/gdnsd\fR,
but this can be overridden by the \f(CW\*(C`\-c\*(C'\fR commandline option.
.PP
The lower-level syntax and structure of the configuration
language is described in detail at the end of this document,
but it should be fairly intuitive from the example above. It
is effectively a generic data structure language allowing
arbitrarily-nested ordered hashes, ordered arrays, and scalar
values. Double-quotes are used to quote scalars containing
whitespace or various ambiguous metacharacters.
.PP
The top-level implicit hash of a gdnsd configuration file allows
only 3 legal keys: \fBoptions\fR, \fBservice_types\fR, and \fBplugins\fR.
.PP
Any of them which are present must have a Hash as their value.
.PP
All of them are optional, as is the configuration file itself.
If you're happy with an all-default configuration, you can
simply not have a config file at all.
.SH "OPTIONS HASH"
.IX Header "OPTIONS HASH"
These options control the overall behavior of \fBgdnsd\fR\|(8).
.IP "\fBusername\fR" 4
.IX Item "username"
String, defaults to \*(L"gdnsd\*(R". This is the username the daemon drops
privileges to the uid/gid of on startup if started as root.
.IP "\fBweaker_security\fR" 4
.IX Item "weaker_security"
Boolean, default false. When false, the daemon may take additional
privilege-preventing measures beyond the basic drop of the uid/gid of the
process. These may be platform specific and evolve over time, and may impose
limits that break some users' configurations in corner cases.
.Sp
This option exists as an escape hatch to get things working again, but the
name of the option is intended to pressure you to find another way to
accomplish your goal without requiring reduced security.
.Sp
At this time, the only security feature this controls is setting the
Linux-specific \f(CW\*(C`prctl()\*(C'\fR flag \f(CW\*(C`PR_SET_NO_NEW_PRIVS\*(C'\fR on kernels 3.5 and
higher. When this is set, it immutably prevents the process and all
descendants from ever gaining new privileges again. This is done regardless
of whether the daemon initially started as root and voluntarily dropped its
own privileges or was started as a regular user.
.Sp
Note that \f(CW\*(C`PR_SET_NO_NEW_PRIVS\*(C'\fR could break plugin_extmon configurations
which execute binaries that need escalated privileges via set[ug]id bits
and/or capabilities bits. A classic example of such a binary is \f(CW\*(C`ping\*(C'\fR.
.IP "\fBzones_default_ttl\fR" 4
.IX Item "zones_default_ttl"
Integer seconds, default 86400. This is the global default
time-to-live for any record in any zonefile. It can be overridden with
a more specific default within zone files themselves via the \f(CW$TTL\fR
directive (see \fBgdnsd.zonefile\fR\|(5)).
.IP "\fBmax_ttl\fR" 4
.IX Item "max_ttl"
Integer seconds, default 3600000 (~42 days),
range 3600 \- 268435455 (2^28\-1, ~8.5 years).
This is the global maximum \s-1TTL.\s0 Any \s-1TTL\s0 found in a zone which
exceeds this value will be clamped to this value with a warning.
Note that the default maximum value is what the Internet's root
nameservers currently use for A\-record TTLs, and those are arguably
the most stable records in the whole system. It's hard to imagine
good reasons to raise this value in practice.
.IP "\fBmin_ttl\fR" 4
.IX Item "min_ttl"
Integer seconds, default 5, range 1 \- 86400 (1 day).
This is the global minimum \s-1TTL.\s0 Any \s-1TTL\s0 found in a zone which
is below this value will be clamped to this value with a warning,
including the minimum TTLs of DYN[\s-1AC\s0] records and \s-1SOA\s0 ncache TTLs.
This value must be less than or equal to max_ttl.
.IP "\fBmax_ncache_ttl\fR" 4
.IX Item "max_ncache_ttl"
Integer seconds, default 10800, range 10 \- 86400.
This is the global maximum for the \s-1SOA\s0 negative-cache \s-1TTL\s0 field.
Values above this will be clamped with a warning. This value
must be greater than or equal to min_ttl.
.IP "\fBdns_port\fR" 4
.IX Item "dns_port"
Integer port, 1\-65535, default 53. This is the global default port
number for \s-1DNS\s0 listener addresses which do not specify port numbers
themselves.
.IP "\fBhttp_port\fR" 4
.IX Item "http_port"
Integer port, 1\-65535, default 3506. This is the default \s-1HTTP\s0 port
number for stats listener addresses which do not specify port numbers
themselves.
.IP "\fBlisten\fR" 4
.IX Item "listen"
The listen option specifies the socket addresses the server listens on
for \s-1DNS\s0 requests.
.Sp
A listen-address specification is an \s-1IP\s0 (v4 or v6) address specified as
a numeric string with standard formatting (anything numeric that
\&\f(CW\*(C`getaddrinfo()\*(C'\fR supports on your platform), optionally followed by a
colon and a port number. If no port number is specified, it defaults
to the value from \f(CW\*(C`dns_port\*(C'\fR, which defaults to \f(CW53\fR.
.Sp
Due to various parsing ambiguities, if you wish to specify a
non-default port number for an IPv6 listen address, you will have to
enclose the address part in square brackets, and then enclose the
entire string in double-quotes.
.Sp
The structure of the listen option as a whole can take one of three
basic forms. In its simplest form, it is just a single listen-address
specification as a string, such as:
.Sp
.Vb 1
\& options => { listen = 192.0.2.1 }
.Ve
.Sp
It can also take the form of an array of such addresses, as in:
.Sp
.Vb 8
\& options => {
\& listen = [
\& 192.0.2.1,
\& 192.0.2.2,
\& 2001:DB8::1,
\& "[2001:DB8::1234]:5353",
\& ]
\& }
.Ve
.Sp
It can also be a hash where the keys are listen addresses, and the values are
per-address options, as in:
.Sp
.Vb 10
\& options => {
\& listen => {
\& 192.0.2.1 => {
\& tcp_timeout = 7
\& },
\& 192.0.2.2:5353 => {
\& udp_threads = 5
\& },
\& }
\& }
.Ve
.Sp
The per-address options (which are identical to, and locally override,
the global option of the same name) are \f(CW\*(C`tcp_threads\*(C'\fR,
\&\f(CW\*(C`tcp_timeout\*(C'\fR, \f(CW\*(C`tcp_clients_per_thread\*(C'\fR, \f(CW\*(C`udp_threads\*(C'\fR, \f(CW\*(C`udp_recv_width\*(C'\fR,
\&\f(CW\*(C`udp_rcvbuf\*(C'\fR, and \f(CW\*(C`udp_sndbuf\*(C'\fR.
.Sp
Finally, it can also be set to the special string value \f(CW\*(C`any\*(C'\fR, as in:
.Sp
.Vb 1
\& options => { listen => any }
.Ve
.Sp
This is the default mode if no explicit \f(CW\*(C`listen\*(C'\fR option is provided. In this
mode, the daemon will listen on the \f(CW\*(C`dns_port\*(C'\fR port (default 53) on the IPv4
and IPv6 \f(CW\*(C`ANY\*(C'\fR addresses \f(CW0.0.0.0\fR and \f(CW\*(C`::\*(C'\fR. gdnsd's \f(CW\*(C`ANY\*(C'\fR\-address
sockets should correctly handle sending outgoing datagrams via the interface
they were received on with a source address matching the destination address of
the request.
.IP "\fBhttp_listen\fR" 4
.IX Item "http_listen"
Basically like \fBlisten\fR above, but used for the \s-1HTTP\s0 listener (serving
stats information), and defaulting to port 3506. The hash form isn't
supported as there are no per-address options, and the any/all options
don't exist here. The default is to listen on the IPv4 and IPv6
any-addresses (\f(CW0.0.0.0\fR and \f(CW\*(C`::\*(C'\fR).
.Sp
It makes common sense to restrict access to this service via firewall
rules, as the data served leaks information about the rate and nature
of your \s-1DNS\s0 traffic. This is mostly intended for your own internal
monitoring purposes.
.IP "\fBtcp_threads\fR" 4
.IX Item "tcp_threads"
Integer, default 1, min 0, max 1024. This is the number of separate
\&\s-1TCP\s0 listening sockets and corresponding listener threads that will be created
for each \s-1DNS\s0 listener address. On a multi-core host, increasing this
parameter (up to at most a small multiple of the \s-1CPU\s0 core count) may
increase overall performance. Note that on hosts without \s-1SO_REUSEPORT\s0
support (notably Linux < 3.9, Solaris), any setting greater than 1 will
be forced to 1 with a warning, as support multiple sockets/threads
per-address are not supported without \s-1SO_REUSEPORT.\s0
.IP "\fBudp_threads\fR" 4
.IX Item "udp_threads"
Exactly like \f(CW\*(C`tcp_threads\*(C'\fR, but for \s-1UDP\s0 sockets per \s-1DNS\s0 listening address.
.IP "\fBtcp_clients_per_thread\fR" 4
.IX Item "tcp_clients_per_thread"
Integer, default 128, min 1, max 65535. This is maximum number of tcp
\&\s-1DNS\s0 connections gdnsd will allow to occur in parallel per listening tcp
thread. Once this limit is reached by a given thread, no new
connections will be allowed to that thread until one of the existing
ones closes or times out. Note that sockets map 1:m to threads, and thus
the total client limit for connecting to a given socket address would be
\&\f(CW\*(C`tcp_clients_per_thread * tcp_threads\*(C'\fR.
.IP "\fBtcp_timeout\fR" 4
.IX Item "tcp_timeout"
Integer seconds, default 5, min 3, max 60. \s-1TCP DNS\s0 connections will be
forcibly shut down if they go idle without receiving and responding to
a valid query for this many seconds. \fBgdnsd\fR\|(8) allows multiple
requests per connection, and this idle timeout applies to the time
between requests as well.
.IP "\fBudp_recv_width\fR" 4
.IX Item "udp_recv_width"
Integer, default 8, min 1, max 64. On supported Linux kernels this
setting tunes the use of more efficient interfaces to receive and send
multiple packets with a single syscall. Higher values reduce syscall
overhead and generally give the server higher throughput and better
efficiency under high loads.
.Sp
I believe that this is basically always a win under load when
supported, but values much larger than necessary do have a chance to
increase average response latency very slightly. The optimal setting
is highly dependent on local hardware, software configuration, and
network load conditions.
.Sp
Setting this to a value of 1 will completely disable this code, as if
we were running on a platform that didn't support it. On platforms
that don't support it, this option has no effect and is ignored. On
Linux if we don't detect a 3.0 or higher kernel at runtime, we fall
back to the same code as other platforms that don't support it.
.IP "\fBudp_rcvbuf\fR" 4
.IX Item "udp_rcvbuf"
Integer, min 4096, max 1048576. If set, this value will be used to set
the \f(CW\*(C`SO_RCVBUF\*(C'\fR socket option on the \s-1UDP\s0 listening socket(s). Most
users do not need to tune this value. If left unset, the code
takes a somewhat heuristic approach, trying to raise the value only if
the OS-supplied default seems too low, and multiplying it a bit in the
case of \f(CW\*(C`udp_recv_width\*(C'\fR > 1.
.IP "\fBudp_sndbuf\fR" 4
.IX Item "udp_sndbuf"
Integer, min 4096, max 1048576. If set, this value will be used to set
the \f(CW\*(C`SO_SNDBUF\*(C'\fR socket option on the \s-1UDP\s0 listening socket(s). Tuning
advice mirrors the above.
.IP "\fBmax_http_clients\fR" 4
.IX Item "max_http_clients"
Integer, default 128, min 1, max 65535. Maximum number of \s-1HTTP\s0
connections to allow in parallel at any given time. Once this number
is reached, no more new connections will be answered until an existing
connection closes or times out.
.IP "\fBhttp_timeout\fR" 4
.IX Item "http_timeout"
Integer seconds, default 5, min 3, max 60. \s-1HTTP\s0 connections will be
forcibly shut down if they go idle for more than this many seconds.
.IP "\fBzones_strict_data\fR" 4
.IX Item "zones_strict_data"
Boolean, default \f(CW\*(C`false\*(C'\fR
.Sp
If false (the default), reporting of many less-serious errors in zone
data are emitted as mere logged warnings, and the zone data is still
loaded and served.
.Sp
If this is set to true, such warnings will be upgraded and treated
the same as the more-serious class of zone data errors which prevent
successful loading of zone data. The consequences of this are variable:
on initial startup or checkconf, this results in a failed zonefile, which
may either be ignored or abort execution, depending on \f(CW\*(C`zones_strict_startup\*(C'\fR
below. During a runtime zone data reload, any existing good copy of the zone
would continue to be served until the error is corrected in the source.
.IP "\fBzones_strict_startup\fR" 4
.IX Item "zones_strict_startup"
Boolean, default \f(CW\*(C`true\*(C'\fR
.Sp
If true (the default), on daemon startup (via \f(CW\*(C`start\*(C'\fR or \f(CW\*(C`restart\*(C'\fR)
if any zone fails to load correctly, the daemon will
abort. If false, the daemon will simply ignore the failed zone and
continue operations.
.Sp
Runtime reloads via \s-1SIGUSR1\s0 and/or periodic/inotify scanning always
treat bad zone data non-fatally (leaving any existing good copy intact
in memory for lookups).
.Sp
This also affects the \f(CW\*(C`checkconf\*(C'\fR action. It will only fail in terms
of exit value on bad zonefiles if this is true (although it will note
any failures to stderr regardless).
.IP "\fBzones_rfc1035_auto\fR" 4
.IX Item "zones_rfc1035_auto"
Boolean, default \f(CW\*(C`true\*(C'\fR.
.Sp
If auto is enabled (the default), the daemon will detect changes to zone data
automatically at runtime and apply them as they appear. In the general case
this is done by periodically scanning \f(CW\*(C`lstat()\*(C'\fR data on the contents of the
zones directory and looking for metadata changes since last check.
.Sp
On modern Linux systems, the daemon may also use \f(CW\*(C`inotify()\*(C'\fR to detect
filesystem modifications in realtime. In these cases it will not usually run
the periodic \f(CW\*(C`lstat()\*(C'\fR scans.
.Sp
Regardless of whether this setting is true or false, you can always manually
trigger a rescan of the zones directory for new data by sending the daemon a
\&\f(CW\*(C`SIGUSR1\*(C'\fR (or executing the \*(L"reload-zones\*(R" command, which sends \s-1SIGUSR1\s0 for
you).
.IP "\fBzones_rfc1035_auto_interval\fR" 4
.IX Item "zones_rfc1035_auto_interval"
Integer seconds, default 31, min 10, max 600. Only applies when
\&\f(CW\*(C`zones_rfc1035_auto\*(C'\fR is \f(CW\*(C`true\*(C'\fR.
.Sp
Sets the time interval for periodically checking the zonefile directory for
changes. On systems which support \f(CW\*(C`inotify()\*(C'\fR, however, the automatic mode
will almost always use that mechanism instead for even faster detection with
less overhead. In the \f(CW\*(C`inotify()\*(C'\fR case, the interval is used only
occasionally as a fallback mechanism to recover a consistent state after
temporary \f(CW\*(C`inotify()\*(C'\fR failures due to inotify queue overflows or the zones
directory itself being moved/deleted, etc.
.IP "\fBzones_rfc1035_quiesce\fR" 4
.IX Item "zones_rfc1035_quiesce"
Floating-point seconds, default 3.0, min 1.02, max 60.0
.Sp
Regardless of whether you're using \f(CW\*(C`zones_rfc1035_auto\*(C'\fR and/or explicit zone
reloads, this interval defines a quiescence delay timer that's commonly used
to coalesce multiple updates to the same file, avoid race conditions with
zonefile writers, and potentially avoid filesystem timestamp issues. This
timer value is also used as the delay to retry loading a zonefile indefinitely
if it fails to load when we first detected a change due to e.g. permissions or
locking issues (as opposed to parse failure).
.Sp
The timer doesn't generally apply in the \f(CW\*(C`inotify()\*(C'\fR case unless there are
multiple nearly-simultaneous events for the same file, or (usually) when the
file is modified in-place, or again if there's a filesystem-level rather than
parser-level issue loading the zonefile.
.Sp
It is highly recommended that whatever tools or scripts you use to manage
zonefile updates use atomic operations (in commandline terms: \f(CW\*(C`mv\*(C'\fR, \f(CW\*(C`rm\*(C'\fR and
\&\f(CW\*(C`ln\*(C'\fR (without \f(CW\*(C`\-s\*(C'\fR!); in syscall terms: \f(CW\*(C`rename()\*(C'\fR, \f(CW\*(C`unlink()\*(C'\fR, and
\&\f(CW\*(C`link()\*(C'\fR) to replace them regardless of whether your system supports
\&\f(CW\*(C`inotify()\*(C'\fR and regardless of whether you're using \f(CW\*(C`zones_rfc1035_auto\*(C'\fR or
not. The scanner ignores subdirectories and dotfiles; feel free to use those
to write out the file initially before atomically putting data into view.
.Sp
Performing non-atomic operations (e.g. in-place writes) on an active zonefile
is inherently racy, especially if more than one update occurs in less time
than the timestamp accuracy of the filesystem. The daemon makes some
accommodations for handling these races, but there will always be ugly corner
cases. It may help slightly if the in-place updater acquires an \f(CW\*(C`fcntl()\*(C'\fR
advisory writelock. In-place writes will be \fBespecially\fR unreliable if you
overwrite a file while the daemon is scanning the directory during its initial
startup, as no quiescence timers or other anti-race mechanisms are used during
startup (as these would necessarily delay service availability).
.Sp
Note that in the general case if a zone file never goes the full quiescence
period without having yet another update applied to it, the new data may never
actually be reloaded, as the daemon will constantly be trying to wait for a
full period of quiescence on the file before loading it.
.IP "\fBlock_mem\fR" 4
.IX Item "lock_mem"
Boolean, default false. Causes the daemon to do
\&\f(CW\*(C`mlockall(MCL_CURRENT|MCL_FUTURE)\*(C'\fR, which effectively locks all daemon
memory into \s-1RAM,\s0 unable to be swapped. Possibly helpful in some
production cases to ensure swap-in doesn't affect \s-1DNS\s0 latency.
.Sp
When started as root with lock_mem set to true, the daemon will remove
any ulimits on locked memory before dropping privileges. When started
as a regular user it may not be able to do so, and those limits could
cause the server to abort execution at any time if they are set too low.
.IP "\fBpriority\fR" 4
.IX Item "priority"
Signed integer, range \-20 to +20, lower values are higher priority. If
explicitly set, gdnsd will attempt \f(CW\*(C`setpriority()\*(C'\fR to this value on
startup. If left unset and gdnsd is started as a normal user, no
\&\f(CW\*(C`setpriority()\*(C'\fR call will be made. If left unset and gdnsd is started
as root, it will default to calling \f(CW\*(C`setpriority()\*(C'\fR with the value
\&\f(CW\*(C`\-11\*(C'\fR.
.IP "\fBdisable_text_autosplit\fR" 4
.IX Item "disable_text_autosplit"
Boolean, default false. On the wire, \f(CW\*(C`TXT\*(C'\fR records are encoded as
discrete chunks of up to 255 characters per chunk. The relevant RFCs
state that multiple chunks should be treated by clients as if they are
concatenated. That is to say, it should make no difference to a client
whether the \f(CW\*(C`TXT\*(C'\fR data is sent as two 16\-byte chunks or one 32\-byte
chunk.
.Sp
Ordinarily, you may specify chunk(s) of a \f(CW\*(C`TXT\*(C'\fR record in gdnsd
zonefiles as a string of any size up to the legal length (just short of
64K in practice), and gdnsd will auto-split the data into 255\-byte
chunks for transmission over the \s-1DNS\s0 protocol correctly. If you choose
to manually break up your \s-1TXT\s0 record into multiple strings in the
zonefile, gdnsd also honors these boundaries and will not attempt to
merge them into larger chunks where possible.
.Sp
If you set this option to true, the auto-splitting behavior is
disabled, and any single character string specified in a zonefile as
part of a \f(CW\*(C`TXT\*(C'\fR record which is larger than 255 bytes will
be considered a syntax error.
.IP "\fBinclude_optional_ns\fR" 4
.IX Item "include_optional_ns"
Boolean, default false. Causes the daemon to include the optional \s-1NS\s0
records in the Authority section of simple authoritative responses
containing actual response data. Leaving this option in its default
state results in smaller response packets and faster response packet
generation in many common cases. This is similar in nature to (but not
exactly like) \s-1BIND\s0's \*(L"minimal-responses\*(R" option, except that we default
to the minimal mode.
.Sp
Regardless of this setting, all *necessary* Authority-section records
are always included, such as when they are necessary for delegation
responses, \s-1NXDOMAIN\s0 responses, and \s-1NOERROR\s0 responses containing no
RRsets in the answer section.
.IP "\fBplugin_search_path\fR" 4
.IX Item "plugin_search_path"
A single string or an array of strings, default empty. Normally the
daemon searches for plugins in the fixed path \f(CW\*(C`/usr/lib/x86_64\-linux\-gnu/gdnsd\*(C'\fR,
using filenames of the form \f(CW\*(C`plugin_${name}.so\*(C'\fR. If you define this
parameter, all paths in this list will be searched in the given order
for plugins *before* trying the default, fixed search path.
.IP "\fBrealtime_stats\fR" 4
.IX Item "realtime_stats"
Boolean, default false. Normally the daemon self-imposes a limit of
not recalculating the daemon-wide statistics more often than once per
second. This improves efficiency in the case that the polling traffic
on our \s-1HTTP\s0 interface gets high.
.Sp
For most uses the default should be fine. If you set this option to
true, the stats will be recalculated on the spot for every stats
request. The test suite uses this so that it can double-check
statistics counters between every request it sends. I don't imagine
anyone else will need to use this option, and it could even be
determinental to performance on \s-1SMP\s0 machines.
.IP "\fBmax_response\fR" 4
.IX Item "max_response"
Integer, default 16384, min 4096, max 64000. This number is used to
size the per\-I/O\-thread buffers that we construct response packets in.
For any sane, normal use of the \s-1DNS,\s0 the default value is far more than
enough. For embedded or other low memory hosts, you might even
consider setting this smaller than default to save a bunch of
per-socket-context buffer space.
.Sp
However, if you have strange \s-1DNS\s0 data that's very large (giant RRsets,
giant blobs of data in \s-1TXT\s0 records) which might generate response
packets greater than the 16K default max here, you *must* set this
parameter large enough to accommodate them or random very bad things
will happen. It should be noted that the odds are high whatever you're
trying to do is misguided in the first place. You can size this by
setting it to the max and running some test queries via \*(L"dig\*(R" (or a
similar tool) to find your limit.
.Sp
This number does not need to take into account \s-1UDP, IP,\s0 or any
lower-level headers. Typically when probing your data for the largest
response sizes you should do \f(CW\*(C`ANY\*(C'\fR queries and/or specific RR-type
queries against the first \s-1CNAME\s0 in any \s-1CNAME\s0 chains leading to large
RR-sets. Keep in mind that the \f(CW\*(C`include_optional_ns\*(C'\fR option will
affect the sizing as well. Also keep in mind that wildcards and
delegations can match any child name, including ones of maximal overall
length.
.IP "\fBmax_edns_response\fR" 4
.IX Item "max_edns_response"
Integer, default 1410, min 512, max 64000. This is the maximum size
of a \s-1UDP\s0 edns response to a client, acting as a cap on the edns
buffer size advertised by the client in its request.
.Sp
The default of 1410 is the largest size suggested in \s-1RFC 6891\s0 when
falling back from the inability to deliver 4K\-sized packets, and it
seems very likely to be a successful size for unfragmented delivery
on most networks today even given IPv6 and some reasonable tunneling.
.Sp
The option obviously has no pragmatic effect if you do not have
large response datasets in your zones in the first place.
.Sp
This value will be capped at the configured (or default) value of
\&\f(CW\*(C`max_response\*(C'\fR with a warning if configured above that value.
.IP "\fBmax_addtl_rrsets\fR" 4
.IX Item "max_addtl_rrsets"
Integer, default 64, min 16, max 256. This is the maximum number of \s-1RR\s0
sets that will ever be added to the Additional section of a response
packet. This sets a hard limit on the number of delegation glue \s-1NS\s0
records a subzone can have (which is checked at startup), and a runtime
soft limit on other Additional section \s-1RR\s0 sets. When the limit is
reached at runtime, the remaining potential additional \s-1RR\s0 sets are
simply not added to the packet. Most users won't need to raise this
value, and users on low\-memory/embedded hosts might want to lower it to
save more memory.
.IP "\fBmax_cname_depth\fR" 4
.IX Item "max_cname_depth"
Integer, default 16, min 4, max 24. How deep \s-1CNAME\s0 \-> \s-1CNAME\s0 chains are
allowed to recurse within local data in a single zonefile. If a chain
longer than this is detected between normal static \s-1CNAME\s0 entries in the
authoritative data of a single zonefile, an error will be thrown when
loading the zonefile.
.Sp
If the limit is exceeded at runtime (due to \f(CW\*(C`DYNC\*(C'\fR dynamic \s-1CNAME\s0
responses) the code will halt further recursive lookups for this
request and return an empty \fB\s-1NXDOMAIN\s0\fR response, and log a loud
message to syslog on every single request for this broken domainname.
.Sp
Note that this is the only thing preventing infinite \s-1CNAME\s0 loops caused
by bad \s-1DYNC\s0 plugin configurations. Also note that even in the \f(CW\*(C`DYNC\*(C'\fR
case, all of this applies only within a single zone. The gdnsd code
never crosses the boundary between two distinct local zonefiles when
processing queries.
.IP "\fBedns_client_subnet\fR" 4
.IX Item "edns_client_subnet"
Boolean, default true. Enables support for the edns-client-subnet
option. gdnsd only includes this \s-1EDNS\s0 option in responses to queries
which also contained the option. In the case of normal responses from
static zone data, the scope mask will be set to zero. Dynamic response
plugins have access to the query's \s-1EDNS\s0 client-subnet data, and have
full control over the response scope mask.
.Sp
If the option is set to false, gdnsd will ignore the option in queries,
never set it in its responses, and plugins will not have access to any
data provided by any ignored edns-client-subnet option in queries.
.Sp
Of the included standard plugins only \f(CW\*(C`reflect\*(C'\fR and \f(CW\*(C`geoip\*(C'\fR make use
of edns-client-subnet information. The rest will leave the scope mask
at zero as normal for client-location-agnostic static data.
.Sp
Relevant links documenting edns-client-subnet:
.Sp
.IP "\fBchaos_response\fR" 4
.IX Item "chaos_response"
String, default \*(L"gdnsd\*(R". When gdnsd receives any query with the class
\&\f(CW\*(C`CH\*(C'\fR (\*(L"Chaos\*(R"), as opposed to the normal \f(CW\*(C`IN\*(C'\fR (\*(L"Internet\*(R"), it will
return a single response record of class \f(CW\*(C`CH\*(C'\fR and type \f(CW\*(C`TXT\*(C'\fR, which
contains the string defined here. This is something like \s-1BIND\s0's
version reporting, which responds to \*(L"version.bind\*(R" queries in the
\&\f(CW\*(C`CH\*(C'\fR class, and is what a client will see if they use such a query
against a gdnsd server.
.IP "\fBlog_stats\fR" 4
.IX Item "log_stats"
Integer, default 3600, min 0, max 86400. The current stats counters
will be emitted as log output (e.g. to syslog) every \f(CW\*(C`log_stats\*(C'\fR
seconds. If set to zero, periodic stats logging is disabled.
Regardless of this setting, stats counters are always emitted to the log
once at the time of daemon shutdown.
.IP "\fBrun_dir\fR" 4
.IX Item "run_dir"
String, defaults to \fI/var/run/gdnsd\fR. This is the directory
which the daemon owns as its run directory. It will create this
directory and/or modify the permissions and ownership of it
on startup. If it does not exist and cannot be created, or the
permissions and ownership cannot be set to acceptable values, the
daemon will not start.
.Sp
The contents of this directory are private to the daemon and
shouldn't be interfered with. This can live on a filesystem that's
volatile across reboots, and doesn't require much disk space.
.IP "\fBstate_dir\fR" 4
.IX Item "state_dir"
String, defaults to \fI/var/lib/gdnsd\fR. This is the directory
which the daemon owns as its state directory. It will create this
directory and/or modify the permissions and ownership of it
on startup. If it does not exist and cannot be created, or the
permissions and ownership cannot be set to acceptable values, the
daemon will not start.
.Sp
The contents of this directory belong to the system administrator
and are used to communicate persistent, stateful information to
the daemon. This should live on a filesystem which is preserved
across reboots.
.IP "\fBany_mitigation\fR" 4
.IX Item "any_mitigation"
Boolean, default true. If true, the server will attempt to mitigate
problems with ANY-query reflection attacks over \s-1UDP.\s0 As \s-1ANY\s0 queries
tend to have the largest response sizes, they are an obvious target for
amplified reflection attacks using gdnsd as the traffic source. \s-1ANY\s0
queries aren't commonly used by legitimate clients; they're mostly for
debugging.
.Sp
Currently gdnsd's only mechanism for mitigation is forcing legitimate
clients to use \s-1TCP\s0 for \s-1ANY\s0 queries by sending a truncated \s-1UDP\s0 response.
Truncation responses are a normal expectation regardless, and supporting
\&\s-1DNS\s0 over \s-1TCP\s0 is a requirement of the \s-1DNS.\s0 Therefore this should cause
no real-world performance or interoperability problems in exchange for
the protection it offers.
.Sp
In future releases, \f(CW\*(C`any_mitigation\*(C'\fR may behave differently and allow
some ANY-over-UDP traffic to succeed when it's safe to do so. For
example, it may allow \s-1ANY\s0 over \s-1UDP\s0 up to a certain response ratelimit,
and/or it may allow \s-1ANY\s0 over \s-1UDP\s0 when the request source is weakly
validated by an edns0 cookie.
.SH "SERVICE_TYPES"
.IX Header "SERVICE_TYPES"
service_types is used in conjunction with certain gdnsd plugins. If
you are not using such a plugin, you can safely ignore this section and
omit it from your configuration.
.PP
The service_types hash contains generic definitions for how to monitor
a given types of service, independently of any specific address or
hostname for that service.
.PP
There are two trivial service_types internally defined as the names
\&\f(CW\*(C`up\*(C'\fR and \f(CW\*(C`down\*(C'\fR, which do no actual monitoring and simply set the
monitored state permanently \f(CW\*(C`UP\*(C'\fR or \f(CW\*(C`DOWN\*(C'\fR. \f(CW\*(C`up\*(C'\fR is the default
service_type when no service_type is specified.
.PP
Within the definition of a service_type there are several generic
parameters related to timing and anti-flap, as well as plugin-specific
parameters that vary per plugin.
.PP
A service type does not, however, specify a name or address for a
specific instance of a service. Those would occur on a per-address
basis in a resolving plugin's configuration down in the \f(CW\*(C`plugins\*(C'\fR
stanza, and the plugin's configuration would then reference a named
service type to be used when monitoring said address.
.PP
A service monitored through these mechanisms is always in either the
\&\f(CW\*(C`UP\*(C'\fR or \f(CW\*(C`DOWN\*(C'\fR state at runtime from a monitoring perspective. The
\&\f(CW\*(C`UP\*(C'\fR state is maintained in the face of intermittent or isolated failures
until the anti-flap thresholds are crossed and the state moves to
\&\f(CW\*(C`DOWN\*(C'\fR.
.PP
Any services monitored for plugins also have their state reported
alongside the standard gdnsd statistics report, served by the built-in
\&\s-1HTTP\s0 server (default port is 3506).
.PP
The following are the generic parameters for all service_types:
.IP "\fBup_thresh\fR" 4
.IX Item "up_thresh"
Integer, default 20, min 1, max 65535. Number of monitoring requests
which must succeed in a row without any failures to transition
a given resource from the \f(CW\*(C`DOWN\*(C'\fR state to the \f(CW\*(C`UP\*(C'\fR state.
.IP "\fBok_thresh\fR" 4
.IX Item "ok_thresh"
Integer, default 10, min 1, max 65535. See below.
.IP "\fBdown_thresh\fR" 4
.IX Item "down_thresh"
Integer, default 10, min 1, max 65535. The \f(CW\*(C`ok_thresh\*(C'\fR and \f(CW\*(C`down_thresh\*(C'\fR
parameters control the transition from the \f(CW\*(C`UP\*(C'\fR state to the \f(CW\*(C`DOWN\*(C'\fR
state while trying to prevent flappy behavior. Their behavior is best
described in terms of an internal failure counter for a resource
which is currently in the \f(CW\*(C`UP\*(C'\fR state. The failure counter starts
at zero on state transition into the \f(CW\*(C`UP\*(C'\fR state.
.Sp
Every state poll that results in a failed response, even if other
successful responses are interleaved between them, increments the
failure counter. If the failure counter reaches \f(CW\*(C`down_thresh\*(C'\fR
the resource is transitioned to the \f(CW\*(C`DOWN\*(C'\fR state. However, if
\&\f(CW\*(C`ok_thresh\*(C'\fR successes occur in a row with no failures between them,
the failure counter is reset back to zero.
.Sp
So with the default values, the expected behavior is that if an \f(CW\*(C`UP\*(C'\fR
resource experiences 10 (possibly isolated or intermittent)
monitor-polling failures over \fBany\fR length of time, without a
string of 10 successes in a row somewhere within the sequence to
reset the counter, it will transition to the \f(CW\*(C`DOWN\*(C'\fR state.
Once \f(CW\*(C`DOWN\*(C'\fR, it will require 20 successes in a row before
transitioning back to the \f(CW\*(C`UP\*(C'\fR state.
.IP "\fBinterval\fR" 4
.IX Item "interval"
Integer seconds, default 10, min 1, max 255. Number of seconds between
successive monitoring requests for a given resource.
.IP "\fBtimeout\fR" 4
.IX Item "timeout"
Integer seconds, default interval/2, min 1, max 255. Maximum time the
monitoring code will wait for a successful response before giving up
and considering the request to be a failure. Defaults to half of the
\&\f(CW\*(C`interval\*(C'\fR, and must be less than \f(CW\*(C`interval\*(C'\fR.
.IP "\fBplugin\fR" 4
.IX Item "plugin"
String, required. This indicates which specific plugin to use to execute
the monitoring requests. Any parameters other than the generic ones listed
here are consumed by the plugin.
.PP
There are six monitoring plugins included with gdnsd that can be used
in a service_types definition, each of which may have additional,
plugin-specific configuration options in addition to the generic ones
above. Each of these is documented in detail in its own manpage
e.g. \f(CW\*(C`gdnsd\-plugin\-FOO\*(C'\fR:
.IP "\fBtcp_connect\fR" 4
.IX Item "tcp_connect"
Checks \s-1TCP\s0 basic connectivity on a given port. Only supports
address resources, not CNAMEs.
.IP "\fBhttp_status\fR" 4
.IX Item "http_status"
Checks \s-1HTTP\s0 connectivity, with options for the port, \s-1URL,\s0 and vhost
to use in the request, and the acceptable \s-1HTTP\s0 status codes in
the response. Only supports address resources, not CNAMEs.
.IP "\fBextmon\fR" 4
.IX Item "extmon"
Periodically executes a custom external commandline program
to poll for the status of a resource. Supports both address
and \s-1CNAME\s0 resources.
.IP "\fBextfile\fR" 4
.IX Item "extfile"
Reads the contents of a file on disk to import state monitoring data
from another source. Supports both address and \s-1CNAME\s0 resources.
.IP "\fBstatic\fR" 4
.IX Item "static"
Configures a static monitoring result, mostly for testing / example code.
Supports both address and \s-1CNAME\s0 resources.
.IP "\fBnull\fR" 4
.IX Item "null"
Configures an always-down static result, mostly for testing / example code.
Supports both address and \s-1CNAME\s0 resources.
.SH "PLUGINS"
.IX Header "PLUGINS"
The plugins hash is optional, and contains one key for every dynamic
resolution plugin you wish to load and use. The value must be a hash,
and the contents of that hash are supplied to the plugin to use in
configuring itself. If the plugin requires no configuration, the empty
hash \f(CW\*(C`{}\*(C'\fR will suffice. It is up to the plugin to determine whether
the supplied hash of configuration data is legal or not.
.PP
Monitoring-only plugins can also be given plugin-global level
configuration here if the plugin author deemed it necessary.
.PP
gdnsd ships with eight different monitoring plugins,
all of which have their own separate manpage documentation (e.g. \f(CW\*(C`man
gdnsd\-plugin\-FOO\*(C'\fR):
.IP "\fBreflect\fR" 4
.IX Item "reflect"
Reflects \s-1DNS\s0 client source \s-1IP\s0 and/or edns-client-subnet information
back to the requestor as address data for debugging.
.IP "\fBsimplefo\fR" 4
.IX Item "simplefo"
Simple primary\->secondary failover of monitored addresses
.IP "\fBmultifo\fR" 4
.IX Item "multifo"
All-active failover of monitored round-robin address groups
.IP "\fBweighted\fR" 4
.IX Item "weighted"
Weighted-round-robin responses with a variety of behavioral flavors,
for both monitored addresses and CNAMEs.
.IP "\fBmetafo\fR" 4
.IX Item "metafo"
Static-ordered address(\-group) meta-failover between 'datacenters',
which are resources defined in terms of other plugins. Supports
both address and \s-1CNAME\s0 data.
.IP "\fBgeoip\fR" 4
.IX Item "geoip"
Combines metafo's functionality with MaxMind GeoIP databases to select
different datacenter address(\-group) preference/failover orderings for
different clients based on approximate geographic location. Supports
both address and \s-1CNAME\s0 data.
.IP "\fBnull\fR" 4
.IX Item "null"
Returns all-zeros addresses or the \s-1CNAME\s0 \f(CW\*(C`invalid.\*(C'\fR \- mostly for
testing and as simple example code.
.IP "\fBstatic\fR" 4
.IX Item "static"
Configures static mappings of resources names to \s-1IP\s0 addresses or
CNAMEs \- mostly for testing and as simple example code.
.PP
A configuration example showing the trivial plugins, as well as
demonstrating the service_types described earlier:
.PP
.Vb 9
\& service_types => {
\& corpwww_type => {
\& plugin => http_status
\& vhost => www.corp.example.com
\& url_path => /check_me
\& down_thresh => 5
\& interval => 5
\& }
\& }
\&
\& plugins => {
\& null => {},
\& reflect => {},
\& static => {
\& foo = 192.0.2.2
\& bar = 192.0.2.123
\& somehost = somehost.example.net.
\& },
\& multifo => {
\& web\-lb =>
\& service_types => [ corpwww_type, xmpp ],
\& lb01 => 192.0.2.200,
\& lb02 => 192.0.2.201,
\& lb03 => 192.0.2.202,
\& }
\& }
\& }
.Ve
.PP
And then in your example.com zonefile, you could have (among your other
RRs):
.PP
.Vb 6
\& zeros 600 DYNA null
\& reflect 10 DYNA reflect
\& reflect\-both 10 DYNA reflect!both
\& pointless 42 DYNA static!foo
\& acname 400 DYNC static!somehost
\& www 300/45 DYNA multifo!web\-lb
.Ve
.SH "LOW-LEVEL SYNTAX"
.IX Header "LOW-LEVEL SYNTAX"
At the lowest level, the syntax of gdnsd config files roughly resembles
an anonymous Perl data structure (using reference syntax). There are
three basic data types for values: ordered hashes (associative arrays
mapping keys to values), ordered arrays of values, and simple strings.
Hashes and arrays can be nested to arbitrary depth. Generally
speaking, whitespace is optional. Single-line comments in both shell
(\f(CW\*(C`#\*(C'\fR) and \s-1DNS\s0 zonefile styles (\f(CW\*(C`;\*(C'\fR) are allowed. They run to the end
of the current line and are considered to be whitespace by the parser.
.PP
A hash is surrounded by curly braces (\f(CW\*(C`{\*(C'\fR and \f(CW\*(C`}\*(C'\fR). Keys are
separated from their values by either \f(CW\*(C`=>\*(C'\fR or \f(CW\*(C`=\*(C'\fR (at your
stylistic discretion). Hash keys follow the same rules as simple
string values. Hash values can be simple strings, arrays, or hashes.
Key/value pairs can optionally have a trailing comma for stylistic
clarity and separation.
.PP
An array is surrounded by square braces (\f(CW\*(C`[\*(C'\fR and \f(CW\*(C`]\*(C'\fR). Values can be
simple strings, arrays, or hashes. Values can optionally have a
trailing comma for style.
.PP
Strings (and thus keys) can be written in both quoted and unquoted
forms. In the quoted form, the string is surrounded by double-quotes
(\f(CW\*(C`"\*(C'\fR), and can contain any literal byte value (even binary/utf\-8
stuff, or \s-1NUL\s0) other than \f(CW\*(C`"\*(C'\fR or \f(CW\*(C`\e\*(C'\fR. Those two characters must be
escaped by \f(CW\*(C`\e\*(C'\fR, i.e. \f(CW\*(C`\e"\*(C'\fR and \f(CW\*(C`\e\e\*(C'\fR.
.PP
In the unquoted form, there are no surrounding quotes, and the allowed
set of unescaped characters is further restricted. The following are
not allowed: \f(CW\*(C`][}{;#,"=\e\*(C'\fR (that is, square brackets, curly brackets,
semicolons, octothorpes, commas, double quotes, equal signs, and
backslashes). Additionally, the first character cannot be a \f(CW\*(C`$\*(C'\fR
(dollar sign).
.PP
Both forms use the same escaping rules, which are the same RFC-standard
escaping rules used in zone files. The escapes always start with \f(CW\*(C`\e\*(C'\fR.
\&\f(CW\*(C`\e\*(C'\fR followed by any single byte other than a digit (\f(CW0\fR \- \f(CW9\fR) is
interepreted as that byte. \f(CW\*(C`\e\*(C'\fR followed by exactly 3 digits
interprets those digits as the unsigned decimal integer value of the
desired byte (the 3 digit value cannot exceed \f(CW255\fR).
.PP
To illustrate the escaping and quoting, the following sets of example
strings show different encodings of the same parsed value:
.PP
.Vb 4
\& example
\& "example"
\& ex\e097mpl\ee
\& "ex\e097mpl\ee"
\&
\& internal\e"doublequote
\& "internal\e"doublequote"
\&
\& white\e space
\& "white space"
\&
\& "braces{every[where]oh}my"
\& braces\e{every\e[where\e]oh\e}my
\&
\& "\e\e==="
\& "\e092==="
\& "\e092\e=\e=\e="
\& \e\e\e=\e=\e=
\& \e092\e=\e=\e=
.Ve
.PP
The top level of the config file is an implicit hash with no bracing
by default, but can also be an array bounded by square brackets. This
is not legal for the primary gdnsd configuration file, but could be
useful in includefiles (see below).
.PP
As a general rule, anywhere the higher-level syntax allows an array of
values, you can substitute a single value. The code will treat it as
if it were an array of length 1.
.PP
When we refer in other sections above to a value as being an \*(L"Integer\*(R"
(or other specific scalar type), we're referring to constraints on the
content of the character string value. All scalar values are character
strings. \*(L"Boolean\*(R" values are characters strings which have the value
\&\*(L"true\*(R" or \*(L"false\*(R", in any mix of upper or lower case.
.PP
The following 3 example configuration files are identical in their
parsed meanings, and should clarify anything miscommunicated above:
.PP
Example 1 (simple and clean):
.PP
.Vb 4
\& options = {
\& listen = [ 192.0.2.1, 192.0.2.2 ],
\& http_listen = 127.0.0.1,
\& }
.Ve
.PP
Example 2 (fat arrows, no commas, some arbitrary quoting):
.PP
.Vb 4
\& "options" => {
\& listen => [ 192.0.2.1 192.0.2.2 ]
\& http_listen => "127.0.0.1"
\& }
.Ve
.PP
Example 3 (compressed and ugly):
.PP
.Vb 1
\& options={listen=[192.0.2.1 192.0.2.2]http_listen=127.0.0.1}
.Ve
.SH "INCLUDING OTHER FILES"
.IX Header "INCLUDING OTHER FILES"
vscf now has a mechanism for config includefiles. The syntax is
.PP
.Vb 3
\& $include{dir/file} # single file must exist
\& $include{dir/*} # not ok if no matching files
\& $include{dir} # ok if no files in dir
.Ve
.PP
where the path can use the same kinds of escaping and/or double-quoting
as normal scalar string data. Whitespace between the path and the
surrounding brackets is optional. Whitespace between \f(CW$include\fR and
the following \f(CW\*(C`{\*(C'\fR is not allowed. If the path is relative (does not
begin with \fI/\fR), it is interpreted as relative to the directory
containing the parent file. Includes can nest other includes to
arbitrary depth.
.PP
The path is normally treated as a glob, allowing the inclusion of
multiple files. When used as a glob, there must be at least one match \-
it will be an error if there are no matching files. However, if \f(CW\*(C`path\*(C'\fR
is not a glob and names an \fBexisting\fR directory explicitly, it will be
treated like it was a glob of all files within that directory by
appending \f(CW\*(C`/*\*(C'\fR, and it will not be an error if there are no files
within that directory (no matches for the glob).
.PP
Keep in mind that at the top level of any given vscf file (even
include files), the file must syntactically be either an implicit
hash or an explicit, square-bracket-bounded, array.
.PP
The include statement can be used in two distinct contexts within
the syntax structure of a config file:
.IP "\fBValue Context\fR" 4
.IX Item "Value Context"
The include statement can replace any whole value (that is, the right
hand side of a hash map entry or a member of an array) with its own
contents, which are either a hash or an array. Note that there is no
mechanism for flattening an include-file's array into the parent array
(the whole included array would be a single array item within the parent
array). Also, including multiple files in a single statement (directory
name or glob pattern) are not allowed in value context. Examples:
.Sp
.Vb 4
\& main config:
\& options => { listen => $include{foo} }
\& foo:
\& [ 127.0.0.1, 127.0.0.2 ]
\&
\& main config:
\& plugins => $include{ "bar" }
\& bar:
\& geoip => { ... }
\& extmon => { ... }
.Ve
.IP "\fBHash-Merge Context\fR" 4
.IX Item "Hash-Merge Context"
The include statement can also appear in a hash where a key would
normally be expected. In this case, the included file must be in hash
(rather than array) form at the top level, and its contents are merged
into the parent hash. The merge is shallow, and conflicting keys are
not allowed. Example:
.Sp
.Vb 10
\& main config:
\& options => { ... },
\& plugins => {
\& extmon => { ... },
\& $include{geoip.cfg},
\& $include{plugins.d},
\& }
\& geoip.cfg:
\& geoip => { ... }
\& plugins.d/foo:
\& weighted => { ... }
\& simplefo => { ... }
\& plugins.d/bar:
\& metafo => { ... }
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBgdnsd\fR\|(8), \fBgdnsd.zonefile\fR\|(5), \fBgdnsd\-plugin\-simplefo\fR\|(8),
\&\fBgdnsd\-plugin\-multifo\fR\|(8), \fBgdnsd\-plugin\-weighted\fR\|(8),
\&\fBgdnsd\-plugin\-metafo\fR\|(8), \fBgdnsd\-plugin\-geoip\fR\|(8),
\&\fBgdnsd\-plugin\-extmon\fR\|(8), \fBgdnsd\-plugin\-extfile\fR\|(8)
\&\fBgdnsd\-plugin\-api\fR\|(3)
.PP
The gdnsd manual.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (c) 2012 Brandon L Black
.PP
This file is part of gdnsd.
.PP
gdnsd is free software: you can redistribute it and/or modify
it under the terms of the \s-1GNU\s0 General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
.PP
gdnsd is distributed in the hope that it will be useful,
but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See the
\&\s-1GNU\s0 General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License
along with gdnsd. If not, see .