.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "GDNSD 8" .TH GDNSD 8 "2021-02-24" "gdnsd 3.5.2" "gdnsd" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" gdnsd \- An authoritative DNS daemon .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 12 \& Usage: gdnsd [\-c /etc/gdnsd] [\-D] [\-l] [\-S] [\-R | \-i] \& \-c \- Configuration directory (default /etc/gdnsd) \& \-D \- Enable verbose debug output \& \-l \- Send logs to syslog rather than stderr \& \-S \- Force \*(Aqzones_strict_data = true\*(Aq for this invocation \& \-R \- Attempt downtimeless replacement of another instance \& \-i \- Idempotent mode for start/daemonize: exit 0 if already running \& (\-R and \-i cannot be used together) \& Actions: \& checkconf \- Checks validity of config and zone files \& start \- Start as a regular foreground process \& daemonize \- Start as a background daemon (implies \-l) .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBgdnsd\fR is very fast, light, and pluggable authoritative \s-1DNS\s0 daemon. .SH "BASIC CONFIGURATION" .IX Header "BASIC CONFIGURATION" The primary configuration file is the file named \fIconfig\fR in the configuration directory. .PP Note that the configuration file does not have to exist for successful startup. Without a configuration file, gdnsd will load all of the zones in the zones directory (default \f(CW\*(C`/etc/gdnsd/zones/\*(C'\fR) and listen on port 53 of \&\f(CW0.0.0.0\fR and \f(CW\*(C`::\*(C'\fR using default settings. .SH "COMMANDLINE OPTION FLAGS" .IX Header "COMMANDLINE OPTION FLAGS" .IP "\fB\-c\fR" 4 .IX Item "-c" Set the configuration directory, defaults to \fI/etc/gdnsd\fR. The zones directory is the \fIzones/\fR subdirectory of the configuration directory. .IP "\fB\-D\fR" 4 .IX Item "-D" Enables additional debug-level log output as appropriate. .IP "\fB\-l\fR" 4 .IX Item "-l" Sends log output to syslog rather than the default stderr. This is implicitly turned on by the \f(CW\*(C`daemonize\*(C'\fR action, and is recommended when running as a systemd service as well, to capture priority information. .IP "\fB\-S\fR" 4 .IX Item "-S" Forces the \f(CW\*(C`zones_strict_data\*(C'\fR configuration option to true for this invocation, regardless of the setting in the config file. This is mostly useful for validation during the \f(CW\*(C`checkconf\*(C'\fR option. .IP "\fB\-R\fR" 4 .IX Item "-R" Replace mode for \f(CW\*(C`start\*(C'\fR and \f(CW\*(C`daemonize\*(C'\fR: .Sp Normally, if another server instance has the server control socket locked, a \&\f(CW\*(C`start\*(C'\fR or \f(CW\*(C`daemonize\*(C'\fR attempt will fail. With this flag set, the new server will connect to the old over its control socket and attempt a downtime-less, graceful takeover of operations. This allows for both code and configuration changes to happen without losing requests in most cases and is in general fairly seamless. See the \fBgdnsdctl\fR\|(8) documentation for \*(L"replace\*(R" for more information, as that is the preferred interface to this functionality. .IP "\fB\-i\fR" 4 .IX Item "-i" Idempotent mode for \f(CW\*(C`start\*(C'\fR and \f(CW\*(C`daemonize\*(C'\fR: .Sp Normally, if another server instance has the server control socket locked, a \&\f(CW\*(C`start\*(C'\fR or \f(CW\*(C`daemonize\*(C'\fR attempt will fail. With this flag set, if another instance is already running, this instance will report success and exit with status zero immediately. .SH "ACTIONS" .IX Header "ACTIONS" .IP "\fBcheckconf\fR" 4 .IX Item "checkconf" Checks the validity of the configuration file and zonefiles, setting the exit status appropriately (0 for success). The same code executes implicitly during startup; checkconf just exits at the last point before real runtime actions need to be taken, such as acquiring sockets. .IP "\fBstart\fR" 4 .IX Item "start" Starts gdnsd as a runtime \s-1DNS\s0 server foreground process, emitting log output to stderr. .IP "\fBdaemonize\fR" 4 .IX Item "daemonize" Starts gdnsd as a detached background daemonize process in a new session, parented to \s-1PID 1\s0 (init), emitting log output to directly to syslog. The initial foreground process will emit no terminal output on success, but will wait for the background daemon to complete startup operations successfully before exiting with status zero (or not, in which case it will exit non-zero and emit some kind of failure output to either stderr or syslog). .PP Any other commandline option will be treated as invalid, which will result in displaying a short help text to \fI\s-1STDERR\s0\fR and exiting with a non-zero exit status. This includes things like the ubiquitous \fB\-\-help\fR and \fB\-\-version\fR. .SH "PRIVILEGES" .IX Header "PRIVILEGES" This service pays no attention to, nor does it attempt to check or modify, anything about the runtime security environment or privilege set, or whether or not it happens to be running as \f(CW\*(C`root\*(C'\fR, or attempt any actions that would commonly require \f(CW\*(C`root\*(C'\fR privileges, such as altering its own memlock rlimits or raising its own process priority. The lone exception is that the code blindly assumes that binding its \s-1DNS\s0 listening ports, which default to being in the privileged range, will Just Work. .PP It expects all such things to be managed managed by external mechanisms: either a systemd-like init system which can do it all declaratively, or a combination of tooling in an initscript for a traditional init system to take care of the necessary privileged settings and/or security-jailing / ACLs, etc, .SH "SYSTEMD COMPATIBILITY" .IX Header "SYSTEMD COMPATIBILITY" When run as a systemd service, \f(CW\*(C`start\*(C'\fR should be used rather than \&\f(CW\*(C`daemonize\*(C'\fR, the \f(CW\*(C`\-l\*(C'\fR flag should be used, and the type should be set to \f(CW\*(C`Type=notify\*(C'\fR with \f(CW\*(C`NotifyAccess=all\*(C'\fR. The latter bits will cause systemd to set \f(CW$NOTIFY_SOCKET\fR for the daemon, and the daemon in turn will use this to send a readiness notification when it's done with initial startup tasks and ready to service requests. \f(CW\*(C`gdnsdctl \-l stop\*(C'\fR should be used for the \f(CW\*(C`ExecStop=\*(C'\fR command. .PP The source tree contains an example systemd unit file with reasonable defaults for a production deployment. .SH "ZONE FILES \- RFC1035" .IX Header "ZONE FILES - RFC1035" The directory for standard \s-1RFC1035\s0 zone files (the default zone data backend) is the subdirectory named \fIzones/\fR in the configuration directory, so the default would be \&\fI/etc/gdnsd/zones/\fR. .PP \&\s-1RFC1035\s0 zone files are the traditional zone file format that one typically uses with e.g. \s-1BIND.\s0 For more information on the internal format and processing of these files, see \&\fBgdnsd.zonefile\fR\|(5). This section is about how the directory itself is managed. .PP All files in the zones directory are considered zone files. In general there should be exactly one file per zone, and the filename should match the zone name. Filenames beginning with \&\f(CW\*(C`.\*(C'\fR are ignored. All zone file must be regular files (as opposed to directories, symlinks, sockets, etc). .PP In order to better support the special case of \s-1RFC 2137\s0 \-style classless in\-addr.arpa delegation zones (which contain forward slashes), any \f(CW\*(C`@\*(C'\fR symbol in the filename will be translated to a forward slash (\f(CW\*(C`/\*(C'\fR) when transforming a filename into its corresponding zone name. .PP For similar reasons, if your server is intended to serve the root of the \s-1DNS,\s0 the filename for the root zone should be the special filename \fI\s-1ROOT_ZONE\s0\fR, rather than the impossible literal filename \fI.\fR. Because authoritative servers cannot serve two domains which have a parent<\->child relationship correctly, a root server cannot serve any other zone, so this would be the sole zonefile. .PP The standard \s-1DNS\s0 zone file escape sequences are recognized within the filenames (e.g. \f(CW\*(C`\e.\*(C'\fR for a dot within a label, or \f(CW\*(C`\eNNN\*(C'\fR where \s-1NNN\s0 is a decimal integer in the range 0 \- 255), if for some reason you need a strange character in your zone name. .PP Trailing dots on zonefile names are ignored; e.g. \fIexample.com\fR and \fIexample.com.\fR are functionally equivalent. .PP Duplicate zones (e.g. having both of the above representations of \&\f(CW\*(C`example.com\*(C'\fR present in the zones directory, and/or adding a different case-mapping such as \fIEXample.Com\fR) are illegal. .PP Subzones (e.g. having zonefiles for both \f(CW\*(C`example.com\*(C'\fR and \&\f(CW\*(C`subz.example.com\*(C'\fR) are also illegal. .SH "ZONE FILES \- RELOADING" .IX Header "ZONE FILES - RELOADING" \&\f(CW\*(C`gdnsdctl reload\-zones\*(C'\fR triggers re-loading all zone data. The reload operation is done in a separate thread from the main server and doesn't interrupt \s-1DNS\s0 request flow. .PP \&\f(CW\*(C`gdnsdctl\*(C'\fR will wait for the server to complete the load operation and report back the success or failure of the reload transaction via stdout and its process exit status. .PP If any failure occurs during the reload operation, the entire reload transaction is discarded with no effect on the previous runtime data still in use to answer ongoing queries. .SH "DIRECTORIES" .IX Header "DIRECTORIES" Important directory paths for the core daemon code: .IP "\fI/etc/gdnsd\fR" 4 .IX Item "/etc/gdnsd" Default configuration directory, unless overridden via \f(CW\*(C`\-c\*(C'\fR. The primary configuration file is always the file \fIconfig\fR in the configuration directory. .IP "\fI/run/gdnsd\fR" 4 .IX Item "/run/gdnsd" Default run_dir. This is where the daemon's control socket and lock files are created. See the entry for \f(CW\*(C`run_dir\*(C'\fR in the \&\fBgdnsd.config\fR\|(5) manpage for more information about this directory. .IP "\fI/var/lib/gdnsd\fR" 4 .IX Item "/var/lib/gdnsd" Default state_dir. The \fIadmin_state\fR file is read from this directory for administrative state-overrides on monitored resources, see below in the \s-1FILES\s0 section. See the entry for \f(CW\*(C`state_dir\*(C'\fR in the \&\fBgdnsd.config\fR\|(5) manpage for more information about this directory. .IP "\fI/usr/libexec/gdnsd\fR" 4 .IX Item "/usr/libexec/gdnsd" This is the default path for daemon-private executables that users should not run. The only current case is \fIgdnsd_extmon_helper\fR for the extmon plugin and the path for this can be overridden in that plugin's configuration, documented in \fBgdnsd\-plugin\-extmon\fR\|(8). .SH "ADMIN STATE FILE \- \fI/var/lib/gdnsd/admin_state\fP" .IX Header "ADMIN STATE FILE - /var/lib/gdnsd/admin_state" This file is the input for administrative state overrides affecting plugin resolution decisions. The intent of this file is to allow explicit, human administrative decisions to temporarily override the states affecting plugin decision-making on issues of failover and/or geographic distribution. A non-existent file is treated the same as an empty file. The file is watched at runtime for changes, and any overridden state found is applied quickly. The file is expected to persist reboots and daemon restarts in order to preserve the administrator's intent through these events. .PP A basic understanding of how both monitoring and resolution plugins in gdnsd work is assumed (see \fBgdnsd.config\fR\|(5)). This file is parsed as a vscf hash data structure (again, see \fBgdnsd.config\fR\|(5) for deeper details of that format). The keys are the names of monitored or virtual resources, and the values are forced state values (optionally with monitored-TTL values as well). Keys can also be wildcards using the shell glob syntax which affect multiple resources. .PP For normal monitored resources, the typical form of a key would be \&\f(CW\*(C`THING/service_type\*(C'\fR, where \f(CW\*(C`THING\*(C'\fR is the monitored address or \s-1CNAME\s0 value and \f(CW\*(C`service_type\*(C'\fR is the service_type configured to monitor that address or \s-1CNAME\s0 value by one or more resolver plugins. The value portion takes the form of \f(CW\*(C`STATE[/TTL]\*(C'\fR, where \f(CW\*(C`STATE\*(C'\fR is \f(CW\*(C`UP\*(C'\fR or \f(CW\*(C`DOWN\*(C'\fR and the \s-1TTL\s0 portion is an optional override of the monitored \s-1TTL.\s0 .PP The order of the lines in the file is important; they are processed and applied in-order such that later lines can override the actions of earlier lines. This is especially handy for making exceptions to glob-matches. .PP Example: .PP .Vb 6 \& /var/lib/gdnsd/admin_state: \& 2001:db8::2:123/my_http_check => DOWN # down a specific res+stype \& foo.example.com./extmon_ping => UP # up a specific res+stype \& 192.0.2.1/* => DOWN # down all service_types for this address \& */xmpp => UP/30 # up all resources monitored by xmpp w/ TTL 30 ... \& 192.0.2.2/xmpp => DOWN # ... except this one .Ve .PP Some resolution plugins can also register virtual resources (which are not monitored by any \f(CW\*(C`service_type\*(C'\fR) solely for the purpose of administrative override of decision-making. Currently the geoip and metafo plugins do this for their \f(CW\*(C`datacenters\*(C'\fR, and the keys they create take the form of \&\f(CW\*(C`plugin_name/resname/dcname\*(C'\fR to force a datacenter's state at the per-resource level. The geoip plugin also supports keys of the form \&\f(CW\*(C`plugin_name/mapname/dcname\*(C'\fR to force a datacenter's state at the per-map level. These forcings override the aggregate state passed up to geoip/metafo from per-datacenter plugins (e.g. multifo or weighted monitoring several addresses in a datacenter), and in the geoip case the more-specific per-resource forced state will override any per-map forced state. .PP Example: .PP .Vb 4 \& /var/lib/gdnsd/admin_state: \& geoip/map3/dc\-us => DOWN # down dc\-us in geoip map3 \& */dc\-jp => DOWN # down all datacenters named dc\-jp for geoip and metafo \& metafo/res_www/dc\-jp => UP # exception to above .Ve .PP All of the available monitored and virtual keys that can be matched in this file, as well as their current monitored and/or forced states, are visible in the output of \f(CW\*(C`gdnsdctl states\*(C'\fR in \s-1JSON\s0 format. .SH "SIGNALS" .IX Header "SIGNALS" Any signal not explicitly mentioned is not explicitly handled. That is to say, they will have their default actions, which often include aborting execution. .IP "\fB\s-1SIGTERM\s0\fR, \fB\s-1SIGINT\s0\fR" 4 .IX Item "SIGTERM, SIGINT" Causes the daemon to exit gracefully with accompanying log output. The exit status will reflect the terminating signal appropriately. .IP "\fB\s-1SIGPIPE\s0\fR" 4 .IX Item "SIGPIPE" Ignored. .IP "\fB\s-1SIGHUP\s0\fR" 4 .IX Item "SIGHUP" If started via \f(CW\*(C`daemonize\*(C'\fR, \f(CW\*(C`SIGHUP\*(C'\fR is explicitly ignored by the background daemon, but not by the temporary foreground process during initialization. When started via \f(CW\*(C`start\*(C'\fR, \f(CW\*(C`SIGHUP\*(C'\fR handling is left at defaults, which will normally result in unclean process termination on reception. .IP "\fB\s-1SIGUSR1\s0\fR" 4 .IX Item "SIGUSR1" This signal is \*(L"handled\*(R" by the main daemon for compatibility reasons, as previous versions used it to request asynchronous zone data reloads. It merely logs an error now which notes the new \f(CW\*(C`gdnsdctl\*(C'\fR mechanism, and has no real effect. This compatibility handling may be removed in a future major version update. .IP "\fB\s-1SIGUSR2\s0\fR" 4 .IX Item "SIGUSR2" Used internally as an inter-thread signal, no documented use from the outside. Do not send this signal to any thread of the daemon. .SH "EXIT STATUS" .IX Header "EXIT STATUS" An exit status of zero indicates success, anything else indicates failure. .PP For \f(CW\*(C`daemonize\*(C'\fR, the exit status of the initial foreground process will indicate whether the background daemon launched successfully. .PP For \f(CW\*(C`start\*(C'\fR, the initial foreground process \fBis\fR the daemon, and exit status will reflect the terminating signal appropriately even in a clean shutdown case, or be zero if cleanly shut down by non-signal mechanisms. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBgdnsd.config\fR\|(5), \fBgdnsd.zonefile\fR\|(5) .PP The gdnsd manual. .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright (c) 2012 Brandon L Black .PP This file is part of gdnsd. .PP gdnsd is free software: you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. .PP gdnsd is distributed in the hope that it will be useful, but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See the \&\s-1GNU\s0 General Public License for more details. .PP You should have received a copy of the \s-1GNU\s0 General Public License along with gdnsd. If not, see .