Provided by: gdnsd_2.3.0-1_amd64 bug

NAME

       gdnsd.config - gdnsd configuration file

SYNOPSIS

         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 => {}
         }

DESCRIPTION

       This man page describes the syntax of the primary gdnsd configuration file.  The primary
       config file is always the the file named config in the configuration directory.  The
       default configuration directory is /etc/gdnsd, but this can be overridden by the "-c"
       commandline option.

       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.

       The top-level implicit hash of a gdnsd configuration file allows only 3 legal keys:
       options, service_types, and plugins.

       Any of them which are present must have a Hash as their value.

       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.

OPTIONS HASH

       These options control the overall behavior of gdnsd(8).

       username
           String, defaults to "gdnsd".  This is the username the daemon drops privileges to the
           uid/gid of on startup if started as root.

       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.

           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.

           At this time, the only security feature this controls is setting the Linux-specific
           "prctl()" flag "PR_SET_NO_NEW_PRIVS" 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.

           Note that "PR_SET_NO_NEW_PRIVS" 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 "ping".

       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 $TTL directive (see gdnsd.zonefile(5)).

       max_ttl
           Integer seconds, default 3600000 (~42 days), range 3600 - 268435455 (2^28-1, ~8.5
           years).  This is the global maximum TTL.  Any TTL 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.

       min_ttl
           Integer seconds, default 5, range 1 - 86400 (1 day).  This is the global minimum TTL.
           Any TTL found in a zone which is below this value will be clamped to this value with a
           warning, including the minimum TTLs of DYN[AC] records and SOA ncache TTLs.  This
           value must be less than or equal to max_ttl.

       max_ncache_ttl
           Integer seconds, default 10800, range 10 - 86400.  This is the global maximum for the
           SOA negative-cache TTL field.  Values above this will be clamped with a warning.  This
           value must be greater than or equal to min_ttl.

       dns_port
           Integer port, 1-65535, default 53.  This is the global default port number for DNS
           listener addresses which do not specify port numbers themselves.

       http_port
           Integer port, 1-65535, default 3506.  This is the default HTTP port number for stats
           listener addresses which do not specify port numbers themselves.

       listen
           The listen option specifies the socket addresses the server listens on for DNS
           requests.

           A listen-address specification is an IP (v4 or v6) address specified as a numeric
           string with standard formatting (anything numeric that "getaddrinfo()" 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 "dns_port", which defaults to 53.

           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.

           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:

             options => { listen = 192.0.2.1 }

           It can also take the form of an array of such addresses, as in:

             options => {
               listen = [
                 192.0.2.1,
                 192.0.2.2,
                 2001:DB8::1,
                 "[2001:DB8::1234]:5353",
               ]
             }

           It can also be a hash where the keys are listen addresses, and the values are per-
           address options, as in:

             options => {
               listen => {
                 192.0.2.1 => {
                   tcp_timeout = 7
                 },
                 192.0.2.2:5353 => {
                   udp_threads = 5
                 },
               }
             }

           The per-address options (which are identical to, and locally override, the global
           option of the same name) are "tcp_threads", "tcp_timeout", "tcp_clients_per_thread",
           "udp_threads", "udp_recv_width", "udp_rcvbuf", and "udp_sndbuf".

           Finally, it can also be set to the special string value "any", as in:

             options => { listen => any }

           This is the default mode if no explicit "listen" option is provided.  In this mode,
           the daemon will listen on the "dns_port" port (default 53) on the IPv4 and IPv6 "ANY"
           addresses 0.0.0.0 and "::".  gdnsd's "ANY"-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.

       http_listen
           Basically like listen above, but used for the HTTP 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 (0.0.0.0 and "::").

           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 DNS traffic.  This is
           mostly intended for your own internal monitoring purposes.

       tcp_threads
           Integer, default 1, min 0, max 1024.  This is the number of separate TCP listening
           sockets and corresponding listener threads that will be created for each DNS listener
           address.  On a multi-core host, increasing this parameter (up to at most a small
           multiple of the CPU core count) may increase overall performance.  Note that on hosts
           without SO_REUSEPORT 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 SO_REUSEPORT.

       udp_threads
           Exactly like "tcp_threads", but for UDP sockets per DNS listening address.

       tcp_clients_per_thread
           Integer, default 128, min 1, max 65535.  This is maximum number of tcp DNS 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
           "tcp_clients_per_thread * tcp_threads".

       tcp_timeout
           Integer seconds, default 5, min 3, max 60.  TCP DNS connections will be forcibly shut
           down if they go idle without receiving and responding to a valid query for this many
           seconds.  gdnsd(8) allows multiple requests per connection, and this idle timeout
           applies to the time between requests as well.

       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.

           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.

           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.

       udp_rcvbuf
           Integer, min 4096, max 1048576.  If set, this value will be used to set the
           "SO_RCVBUF" socket option on the UDP 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 "udp_recv_width" > 1.

       udp_sndbuf
           Integer, min 4096, max 1048576.  If set, this value will be used to set the
           "SO_SNDBUF" socket option on the UDP listening socket(s).  Tuning advice mirrors the
           above.

       max_http_clients
           Integer, default 128, min 1, max 65535.  Maximum number of HTTP 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.

       http_timeout
           Integer seconds, default 5, min 3, max 60.  HTTP connections will be forcibly shut
           down if they go idle for more than this many seconds.

       zones_strict_data
           Boolean, default "false"

           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.

           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
           "zones_strict_startup" 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.

       zones_strict_startup
           Boolean, default "true"

           If true (the default), on daemon startup (via "start" or "restart") if any zone fails
           to load correctly, the daemon will abort.  If false, the daemon will simply ignore the
           failed zone and continue operations.

           Runtime reloads via SIGUSR1 and/or periodic/inotify scanning always treat bad zone
           data non-fatally (leaving any existing good copy intact in memory for lookups).

           This also affects the "checkconf" 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).

       zones_rfc1035_auto
           Boolean, default "true".

           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 "lstat()" data on the contents of the zones directory
           and looking for metadata changes since last check.

           On modern Linux systems, the daemon may also use "inotify()" to detect filesystem
           modifications in realtime.  In these cases it will not usually run the periodic
           "lstat()" scans.

           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 "SIGUSR1" (or
           executing the "reload-zones" command, which sends SIGUSR1 for you).

       zones_rfc1035_auto_interval
           Integer seconds, default 31, min 10, max 600.  Only applies when "zones_rfc1035_auto"
           is "true".

           Sets the time interval for periodically checking the zonefile directory for changes.
           On systems which support "inotify()", however, the automatic mode will almost always
           use that mechanism instead for even faster detection with less overhead.  In the
           "inotify()" case, the interval is used only occasionally as a fallback mechanism to
           recover a consistent state after temporary "inotify()" failures due to inotify queue
           overflows or the zones directory itself being moved/deleted, etc.

       zones_rfc1035_quiesce
           Floating-point seconds, default 3.0, min 1.02, max 60.0

           Regardless of whether you're using "zones_rfc1035_auto" 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).

           The timer doesn't generally apply in the "inotify()" 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.

           It is highly recommended that whatever tools or scripts you use to manage zonefile
           updates use atomic operations (in commandline terms: "mv", "rm" and "ln" (without
           "-s"!); in syscall terms: "rename()", "unlink()", and "link()") to replace them
           regardless of whether your system supports "inotify()" and regardless of whether
           you're using "zones_rfc1035_auto" 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.

           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 "fcntl()" advisory writelock.  In-place
           writes will be especially 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).

           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.

       lock_mem
           Boolean, default false.  Causes the daemon to do "mlockall(MCL_CURRENT|MCL_FUTURE)",
           which effectively locks all daemon memory into RAM, unable to be swapped.  Possibly
           helpful in some production cases to ensure swap-in doesn't affect DNS latency.

           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.

       priority
           Signed integer, range -20 to +20, lower values are higher priority.  If explicitly
           set, gdnsd will attempt "setpriority()" to this value on startup.  If left unset and
           gdnsd is started as a normal user, no "setpriority()" call will be made.  If left
           unset and gdnsd is started as root, it will default to calling "setpriority()" with
           the value "-11".

       disable_text_autosplit
           Boolean, default false.  On the wire, "TXT" 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 "TXT" data is sent as two 16-byte chunks or one
           32-byte chunk.

           Ordinarily, you may specify chunk(s) of a "TXT" 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 DNS protocol
           correctly.  If you choose to manually break up your TXT record into multiple strings
           in the zonefile, gdnsd also honors these boundaries and will not attempt to merge them
           into larger chunks where possible.

           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 "TXT" record which is
           larger than 255 bytes will be considered a syntax error.

       include_optional_ns
           Boolean, default false.  Causes the daemon to include the optional NS 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) BIND's "minimal-responses" option, except that we default to
           the minimal mode.

           Regardless of this setting, all *necessary* Authority-section records are always
           included, such as when they are necessary for delegation responses, NXDOMAIN
           responses, and NOERROR responses containing no RRsets in the answer section.

       plugin_search_path
           A single string or an array of strings, default empty.  Normally the daemon searches
           for plugins in the fixed path "/usr/lib/x86_64-linux-gnu/gdnsd", using filenames of
           the form "plugin_${name}.so".  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.

       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 HTTP interface gets high.

           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 SMP machines.

       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 DNS, 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.

           However, if you have strange DNS data that's very large (giant RRsets, giant blobs of
           data in TXT 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 "dig" (or a similar tool) to
           find your limit.

           This number does not need to take into account UDP, IP, or any lower-level headers.
           Typically when probing your data for the largest response sizes you should do "ANY"
           queries and/or specific RR-type queries against the first CNAME in any CNAME chains
           leading to large RR-sets.  Keep in mind that the "include_optional_ns" 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.

       max_edns_response
           Integer, default 1410, min 512, max 64000.  This is the maximum size of a UDP edns
           response to a client, acting as a cap on the edns buffer size advertised by the client
           in its request.

           The default of 1410 is the largest size suggested in RFC 6891 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.

           The option obviously has no pragmatic effect if you do not have large response
           datasets in your zones in the first place.

           This value will be capped at the configured (or default) value of "max_response" with
           a warning if configured above that value.

       max_addtl_rrsets
           Integer, default 64, min 16, max 256.  This is the maximum number of RR 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 NS records a subzone can have (which is checked at
           startup), and a runtime soft limit on other Additional section RR sets.  When the
           limit is reached at runtime, the remaining potential additional RR 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.

       max_cname_depth
           Integer, default 16, min 4, max 24.  How deep CNAME -> CNAME chains are allowed to
           recurse within local data in a single zonefile.  If a chain longer than this is
           detected between normal static CNAME entries in the authoritative data of a single
           zonefile, an error will be thrown when loading the zonefile.

           If the limit is exceeded at runtime (due to "DYNC" dynamic CNAME responses) the code
           will halt further recursive lookups for this request and return an empty NXDOMAIN
           response, and log a loud message to syslog on every single request for this broken
           domainname.

           Note that this is the only thing preventing infinite CNAME loops caused by bad DYNC
           plugin configurations.  Also note that even in the "DYNC" 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.

       edns_client_subnet
           Boolean, default true.  Enables support for the edns-client-subnet option.  gdnsd only
           includes this EDNS 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 EDNS client-subnet data,
           and have full control over the response scope mask.

           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.

           Of the included standard plugins only "reflect" and "geoip" make use of edns-client-
           subnet information.  The rest will leave the scope mask at zero as normal for client-
           location-agnostic static data.

           Relevant links documenting edns-client-subnet:

           <http://www.afasterinternet.com/>
           <http://tools.ietf.org/html/draft-vandergaast-edns-client-subnet-00>

       chaos_response
           String, default "gdnsd".  When gdnsd receives any query with the class "CH" ("Chaos"),
           as opposed to the normal "IN" ("Internet"), it will return a single response record of
           class "CH" and type "TXT", which contains the string defined here.  This is something
           like BIND's version reporting, which responds to "version.bind" queries in the "CH"
           class, and is what a client will see if they use such a query against a gdnsd server.

       log_stats
           Integer, default 3600, min 0, max 86400.  The current stats counters will be emitted
           as log output (e.g. to syslog) every "log_stats" 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.

       run_dir
           String, defaults to /var/run/gdnsd.  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.

           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.

       state_dir
           String, defaults to /var/lib/gdnsd.  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.

           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.

       any_mitigation
           Boolean, default true.  If true, the server will attempt to mitigate problems with
           ANY-query reflection attacks over UDP.  As ANY queries tend to have the largest
           response sizes, they are an obvious target for amplified reflection attacks using
           gdnsd as the traffic source.  ANY queries aren't commonly used by legitimate clients;
           they're mostly for debugging.

           Currently gdnsd's only mechanism for mitigation is forcing legitimate clients to use
           TCP for ANY queries by sending a truncated UDP response.  Truncation responses are a
           normal expectation regardless, and supporting DNS over TCP is a requirement of the
           DNS.  Therefore this should cause no real-world performance or interoperability
           problems in exchange for the protection it offers.

           In future releases, "any_mitigation" may behave differently and allow some ANY-over-
           UDP traffic to succeed when it's safe to do so.  For example, it may allow ANY over
           UDP up to a certain response ratelimit, and/or it may allow ANY over UDP when the
           request source is weakly validated by an edns0 cookie.

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.

       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.

       There are two trivial service_types internally defined as the names "up" and "down", which
       do no actual monitoring and simply set the monitored state permanently "UP" or "DOWN".
       "up" is the default service_type when no service_type is specified.

       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.

       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 "plugins" stanza, and the plugin's configuration would then reference a named
       service type to be used when monitoring said address.

       A service monitored through these mechanisms is always in either the "UP" or "DOWN" state
       at runtime from a monitoring perspective.  The "UP" state is maintained in the face of
       intermittent or isolated failures until the anti-flap thresholds are crossed and the state
       moves to "DOWN".

       Any services monitored for plugins also have their state reported alongside the standard
       gdnsd statistics report, served by the built-in HTTP server (default port is 3506).

       The following are the generic parameters for all service_types:

       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 "DOWN"
           state to the "UP" state.

       ok_thresh
           Integer, default 10, min 1, max 65535.  See below.

       down_thresh
           Integer, default 10, min 1, max 65535.  The "ok_thresh" and "down_thresh" parameters
           control the transition from the "UP" state to the "DOWN" 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 "UP" state.  The failure counter
           starts at zero on state transition into the "UP" state.

           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 "down_thresh" the resource is transitioned to the "DOWN" state.  However, if
           "ok_thresh" successes occur in a row with no failures between them, the failure
           counter is reset back to zero.

           So with the default values, the expected behavior is that if an "UP" resource
           experiences 10 (possibly isolated or intermittent) monitor-polling failures over any
           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 "DOWN" state.  Once "DOWN",
           it will require 20 successes in a row before transitioning back to the "UP" state.

       interval
           Integer seconds, default 10, min 1, max 255.  Number of seconds between successive
           monitoring requests for a given resource.

       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 "interval", and must be less than "interval".

       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.

       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. "gdnsd-plugin-FOO":

       tcp_connect
           Checks TCP basic connectivity on a given port.  Only supports address resources, not
           CNAMEs.

       http_status
           Checks HTTP connectivity, with options for the port, URL, and vhost to use in the
           request, and the acceptable HTTP status codes in the response.  Only supports address
           resources, not CNAMEs.

       extmon
           Periodically executes a custom external commandline program to poll for the status of
           a resource.  Supports both address and CNAME resources.

       extfile
           Reads the contents of a file on disk to import state monitoring data from another
           source.  Supports both address and CNAME resources.

       static
           Configures a static monitoring result, mostly for testing / example code.  Supports
           both address and CNAME resources.

       null
           Configures an always-down static result, mostly for testing / example code.  Supports
           both address and CNAME resources.

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 "{}" will suffice.  It is up to the plugin to determine
       whether the supplied hash of configuration data is legal or not.

       Monitoring-only plugins can also be given plugin-global level configuration here if the
       plugin author deemed it necessary.

       gdnsd ships with eight different monitoring plugins, all of which have their own separate
       manpage documentation (e.g. "man gdnsd-plugin-FOO"):

       reflect
           Reflects DNS client source IP and/or edns-client-subnet information back to the
           requestor as address data for debugging.

       simplefo
           Simple primary->secondary failover of monitored addresses

       multifo
           All-active failover of monitored round-robin address groups

       weighted
           Weighted-round-robin responses with a variety of behavioral flavors, for both
           monitored addresses and CNAMEs.

       metafo
           Static-ordered address(-group) meta-failover between 'datacenters', which are
           resources defined in terms of other plugins.  Supports both address and CNAME data.

       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 CNAME data.

       null
           Returns all-zeros addresses or the CNAME "invalid." - mostly for testing and as simple
           example code.

       static
           Configures static mappings of resources names to IP addresses or CNAMEs - mostly for
           testing and as simple example code.

       A configuration example showing the trivial plugins, as well as demonstrating the
       service_types described earlier:

         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,
             }
           }
         }

       And then in your example.com zonefile, you could have (among your other RRs):

         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

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 ("#") and DNS zonefile styles
       (";") are allowed.  They run to the end of the current line and are considered to be
       whitespace by the parser.

       A hash is surrounded by curly braces ("{" and "}").  Keys are separated from their values
       by either "=>" or "=" (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.

       An array is surrounded by square braces ("[" and "]").  Values can be simple strings,
       arrays, or hashes.  Values can optionally have a trailing comma for style.

       Strings (and thus keys) can be written in both quoted and unquoted forms.  In the quoted
       form, the string is surrounded by double-quotes ("""), and can contain any literal byte
       value (even binary/utf-8 stuff, or NUL) other than """ or "\".  Those two characters must
       be escaped by "\", i.e.  "\"" and "\\".

       In the unquoted form, there are no surrounding quotes, and the allowed set of unescaped
       characters is further restricted.  The following are not allowed: "][}{;#,"=\" (that is,
       square brackets, curly brackets, semicolons, octothorpes, commas, double quotes, equal
       signs, and backslashes).  Additionally, the first character cannot be a "$" (dollar sign).

       Both forms use the same escaping rules, which are the same RFC-standard escaping rules
       used in zone files.  The escapes always start with "\".  "\" followed by any single byte
       other than a digit (0 - 9) is interepreted as that byte.  "\" followed by exactly 3 digits
       interprets those digits as the unsigned decimal integer value of the desired byte (the 3
       digit value cannot exceed 255).

       To illustrate the escaping and quoting, the following sets of example strings show
       different encodings of the same parsed value:

         example
         "example"
         ex\097mpl\e
         "ex\097mpl\e"

         internal\"doublequote
         "internal\"doublequote"

         white\ space
         "white space"

         "braces{every[where]oh}my"
         braces\{every\[where\]oh\}my

         "\\==="
         "\092==="
         "\092\=\=\="
         \\\=\=\=
         \092\=\=\=

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

       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.

       When we refer in other sections above to a value as being an "Integer" (or other specific
       scalar type), we're referring to constraints on the content of the character string value.
       All scalar values are character strings.  "Boolean" values are characters strings which
       have the value "true" or "false", in any mix of upper or lower case.

       The following 3 example configuration files are identical in their parsed meanings, and
       should clarify anything miscommunicated above:

       Example 1 (simple and clean):

         options = {
           listen = [ 192.0.2.1, 192.0.2.2 ],
           http_listen = 127.0.0.1,
         }

       Example 2 (fat arrows, no commas, some arbitrary quoting):

         "options" => {
           listen => [ 192.0.2.1 192.0.2.2 ]
           http_listen => "127.0.0.1"
         }

       Example 3 (compressed and ugly):

         options={listen=[192.0.2.1 192.0.2.2]http_listen=127.0.0.1}

INCLUDING OTHER FILES

       vscf now has a mechanism for config includefiles.  The syntax is

         $include{dir/file} # single file must exist
         $include{dir/*}   # not ok if no matching files
         $include{dir}     # ok if no files in dir

       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 $include and the following "{" is not allowed.  If the path is relative
       (does not begin with /), it is interpreted as relative to the directory containing the
       parent file.  Includes can nest other includes to arbitrary depth.

       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 "path" is not a glob and names an existing directory
       explicitly, it will be treated like it was a glob of all files within that directory by
       appending "/*", and it will not be an error if there are no files within that directory
       (no matches for the glob).

       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.

       The include statement can be used in two distinct contexts within the syntax structure of
       a config file:

       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:

             main config:
               options => { listen => $include{foo} }
             foo:
               [ 127.0.0.1, 127.0.0.2 ]

             main config:
               plugins => $include{ "bar" }
             bar:
               geoip => { ... }
               extmon => { ... }

       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:

             main config:
               options => { ... },
               plugins => {
                   extmon => { ... },
                   $include{geoip.cfg},
                   $include{plugins.d},
               }
             geoip.cfg:
               geoip => { ... }
             plugins.d/foo:
               weighted => { ... }
               simplefo => { ... }
             plugins.d/bar:
               metafo => { ... }

SEE ALSO

       gdnsd(8), gdnsd.zonefile(5), gdnsd-plugin-simplefo(8), gdnsd-plugin-multifo(8),
       gdnsd-plugin-weighted(8), gdnsd-plugin-metafo(8), gdnsd-plugin-geoip(8),
       gdnsd-plugin-extmon(8), gdnsd-plugin-extfile(8) gdnsd-plugin-api(3)

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