GDNSD.CONFIG(5) | gdnsd | GDNSD.CONFIG(5) |
gdnsd.config - gdnsd configuration file
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 => {} }
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.
These options control the overall behavior of gdnsd(8).
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".
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.
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.
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.
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.
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).
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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>
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.
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.
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 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:
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.
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":
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"):
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
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}
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:
main config: options => { listen => $include{foo} } foo: [ 127.0.0.1, 127.0.0.2 ] main config: plugins => $include{ "bar" } bar: geoip => { ... } extmon => { ... }
main config: options => { ... }, plugins => { extmon => { ... }, $include{geoip.cfg}, $include{plugins.d}, } geoip.cfg: geoip => { ... } plugins.d/foo: weighted => { ... } simplefo => { ... } plugins.d/bar: metafo => { ... }
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 (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/>.
2021-02-11 | gdnsd 2.4.3 |