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

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

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

        Finally, 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".

        There are also two special singalur string values: "any" and "scan".

        If set to "any", the daemon will listen on the "dns_port" port
        (default 53) on 0.0.0.0 and "::" (if IPv6 support is detected).

          options => { listen => any }

        If set to "scan", scan all available IP (v4 and v6) network
        interfaces via "getifaddrs()" and set up a separate listener on the
        "dns_port" port (again, default 53) for each address found.

          options => { listen => scan }

        If the listen option isn't specified at all, for historical
        compatibility reasons the current default is "scan". However, this
        default is expected to change to "any" in a future version, so you
        should specify "scan" explicitly if you require this behavior.

    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. Also, the default
        addresses are the IPv4 and IPv6 (if supported) any-addresses
        (0.0.0.0 and "::"), rather than the iterated per-interface addresses
        that the DNS listener uses.

        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 socket. Once this limit is reached by a given socket,
        no new connections will be allowed to that socket until one of the
        existing ones closes or times out. Note that sockets map 1:1 to
        threads, and thus the total client limit for connecting to a given
        address would be "tcp_clients_per_thread * tcp_threads" for a given
        address.

    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
        only 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 fatal
        error (failure to start, or non-zero exit code, respectively).
        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 SIGHUP 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 via periodically scanning "lstat()"
        data on the contents of the zones directory and looking for metadata
        changes since last check.

        On recent Linux systems, the daemon may also use "inotify()" to
        detect filesystem modifications in realtime and not need to run the
        periodic full directory scan, making the average delay much smaller
        (subject to compile- and run- time compatibility). You will need a
        runtime Linux kernel version of 2.6.36 or higher to enable this
        feature.

        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 "SIGHUP" (or executing the "reload" command /
        initscript action, which sends SIGHUP 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 when
        recovering from temporary "inotify()" failures.

    zones_rfc1035_min_quiesce
        Floating-point seconds, default 0.0, min 0.0, max 5.0

        This short-duration quiescence timeout applies to certain internal
        cases when validating zonefile update activity. (Specifically:
        delays after "inotify()" events for atomic move/delete and delayed
        initial zonefile loading on daemon startup).

        At daemon start, a heuristic test of the mtime resolution on the
        zones filesystem will determine whether we can use a faster 0.01s or
        the default 1.02s as a basic sane minimum, and this config setting
        will be adjusted upwards to the detected minimum as necessary.

        Most users should not need to mess with this setting! The only
        reason to do so would be if you suspected operating system or
        filesystem bugs related to high-res mtimes (or bugs so severe that
        even ~1-second mtime resolution isn't reliable, in which case you
        might want to try values in the 3-5s range, or just find a new FS
        and/or OS...).

    zones_rfc1035_quiesce
        Floating-point seconds, default 5.0, min 0.0, max 60.0

        This timer is related to the above, but is used in cases where we're
        not only worried about filesystem-level timestamp accuracy, but also
        waiting for additional intentional actions by scripts, programs, or
        users which might be actively modifying a zonefile. It applies to
        all changes detected via SIGHUP or periodic automatic scanning, and
        to "inotify()" events which do not indicate atomic operations (e.g.
        create/write/close, rather than move/delete. In other words,
        someone/something is actually overwriting the data in-place or using
        an editor on the file in-place).

        It is recommended that whatever tools or scripts you use to manage
        zonefile updates use atomic operations to replace them. First write
        the new data to a dotfile, e.g. .example.com.tmp1234, in the same
        zones directory (gdnsd ignores all filenames with a leading dot),
        and then mv(1) / rename(2) the file to its final destination
        filename example.com.

        If the value specified is less than the final runtime value of
        "zones_rfc1035_min_quiesce" above, it will be adjusted upwards to
        that minimum value for correct operation.

    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" (and "SPF", which are
        identical in wire-format other than the RR-type) 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" or "SPF" 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 "$PREFIX/lib/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 62464. 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_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.

    debug
        Boolean, default false. If (and only if) gdnsd was built in debug
        mode (--enable-developer, which slows things down with a ton of
        assertion checks among other things), setting this option to "true"
        will cause additional debugging output to syslog/stderr.

    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>

    monitor_force_v6_up
        Boolean, default false. Forces all monitored resources with IPv6
        addresses permanently to the UP state, and does not actually send
        them monitoring requests. Useful if some of your DNS servers don't
        have working or reliable IPv6 routing, which would otherwise fail
        IPv6 polls and force the related addresses to be marked DOWN. A
        better alternative would be to only host DNS for v6-capable services
        on v6-capable DNS hosts, or install a
        Tunnelbroker/Sixxs/Teredo/Miredo/etc tunnel to get v6 routability.

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

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
    the given types of service. Each service type uses a protocol-specific
    plugin, and the default is the included plugin "http_status", which
    checks HTTP status code responses.

    The other included monitoring plugins are "tcp_connect" (documented
    below alongside "http_status", just checks TCP), and "extmon", which
    executes external monitoring commands/scripts and has its own
    documentation at gdnsd-plugin-extmon(8).

    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 can be in one of three
    states at runtime: "UP", "DANGER", or "DOWN". The UP state means that
    all is perfectly well. The DANGER state means that some isolated
    failures have been seen in the recent past (perhaps even just one), but
    that gdnsd has not yet seen a consistent enough pattern of failure to
    declare the service dead. The DOWN state, obviously, means that gdnsd
    does consider the service dead. These states are presented to the plugin
    that requested the monitoring. It is up to the plugin to determine how
    this affects DNS responses.

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

    There are five built-in service types that can't be overridden:

    One built-in service type is implicitly named "default". It uses the
    default "http_status" plugin and is defined to all of the default
    parameters shown below.

    The other four are named "none", "up", "danger", and "down".

    These do no actual monitoring, and simply force the state of resources
    using these service_types to a fixed state. "none" is just an alias for
    "up".

    The following are the generic parameters for all service_types:

    up_thresh
        Integer, default 20, min 1, max 255. Number of monitoring requests
        which must succeed with no intervening failures to transition a
        given IP for this resource from the DOWN state to the UP state.

    ok_thresh
        Integer, default 10, min 1, max 255. Number of monitoring requests
        which must succeed with no intervening failures to transition a
        given IP for this resource from the DANGER state to the UP state.

    down_thresh
        Integer, default 10, min 1, max 255. Number of monitoring requests
        which must fail, regardless of any intervening successes, to
        transition a given IP for this resource from the DANGER state to the
        DOWN state.

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

    timeout
        Integer seconds, default 3, 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. Must be less than 90%
        of interval.

    plugin
        String, default "http_status". This indicates which
        protocol-specific plugin to use to execute the monitoring requests.
        Any parameters other than the generic ones listed here are consumed
        by the plugin.

    The "tcp_connect" plugin has just one plugin-specific parameter:

    port
        Integer, required. This is the port number to contact on the remote
        host to check this service type. It has no default and must be
        specified.

    The following are the plugin-specific parameters for the default
    monitoring plugin "http_status":

    port
        Integer, default 80. This is the port number to contact on the
        remote host to check this service type.

    url_path
        String, default "/". This is the URL that should be used when
        checking this service type.

    vhost
        Hostname, no default. If defined, the HTTP/1.0 monitoring request
        will include this as a "Host:" header in the monitoring request. If
        not defined, no "Host:" header will be sent.

    ok_codes
        Array of 3-digit HTTP status codes, default "[ 200 ]". This defines
        the HTTP status codes in responses that will be accepted as
        successful.

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 3 very trivial dynamic resolution plugins named "null",
    "static", and "reflect".

    "null" simply returns all-zeros addresses for DYNA records, and
    "invalid." as the RHS of DYNC records. It does not pay attention to any
    plugin-specific configuration.

    The "static" plugin can be configured with a map of resource names to
    IPv4 addresses or CNAME hostnames, and it will do the obvious: map those
    resource names statically for use in either DYNA or DYNC zonefile
    records.

    "reflect" is primarily for real-world testing and debugging. It attempts
    to reflect back to the query originator an address answer showing the
    server's view of where the client is located on the network. Currently
    in the common case this will be the address of the intermediate cache
    server which communicated directly with gdnsd. However, if the query
    contains the draft edns-client-subnet option, the response can reflect
    that as well.

    It accepts 4 fixed resource names at the zonefile level: "dns", "edns",
    "best", and "both". "dns" means to ignore edns-client-subnet and always
    return the cache's address. "edns" means to ignore the cache's address
    and always return edns-client-subnet information, (or 0.0.0.0 if not
    available). "best" will return the edns-client-subnet information if
    available, or the cache's address if not. "both" returns both addresses
    if edns-client-subnet is available, or just the cache otherwise. The
    default behavior is "best".

    gdnsd also includes five other plugins that are more production-useful,
    all of which have their own separate manpage documentation (e.g. "man
    gdnsd-plugin-FOO"):

    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

    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 geographically-differentiated CNAME resolution as
        well.

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

      service_types => {
        corpwww_type => {
          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.
        },
      }

    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

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

    where "filename" can use the same kinds of escaping and/or
    double-quoting as normal scalar string data. Whitespace between the
    filename and the surrounding brackets is optional. Whitespace between
    $include and the following "{" is not. If the filename is relative (does
    not begin with /), it is interpreted as relative to the directory
    containing the parent file. Include files can nest other include files
    to arbitrary depth.

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

          main config:
            options => { ... },
            plugins => {
                extmon => { ... },
                metafo => { ... },
                $include{geoip_cfg},
                simplefo => { ... }
            }
          geoip_cfg:
            geoip => { ... },
            weighted => { ... }

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

