Ubuntu Manpage: gdnsd - An authoritative DNS daemon

NAME

       gdnsd - An authoritative DNS daemon

SYNOPSIS

         Usage: gdnsd [-c /etc/gdnsd] [-D] [-l] [-S] [-R | -i] <action>
           -c - Configuration directory (default /etc/gdnsd)
           -D - Enable verbose debug output
           -l - Send logs to syslog rather than stderr
           -S - Force 'zones_strict_data = true' 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)

DESCRIPTION

       gdnsd is very fast, light, and pluggable authoritative DNS daemon.

BASIC CONFIGURATION

       The primary configuration file is the file named config in the configuration directory.

       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 "/etc/gdnsd/zones/") and listen on
       port 53 of 0.0.0.0 and "::" using default settings.

COMMANDLINE OPTION FLAGS

-c Set the configuration directory, defaults to /etc/gdnsd. The zones directory is the zones/
subdirectory of the configuration directory.

-D Enables additional debug-level log output as appropriate.

-l Sends log output to syslog rather than the default stderr. This is implicitly turned on by the
"daemonize" action, and is recommended when running as a systemd service as well, to capture priority
information.

-S Forces the "zones_strict_data" configuration option to true for this invocation, regardless of the
setting in the config file. This is mostly useful for validation during the "checkconf" option.

-R Replace mode for "start" and "daemonize":

Normally, if another server instance has the server control socket locked, a "start" or "daemonize"
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 gdnsdctl(8) documentation for "replace" for more information, as that is the
preferred interface to this functionality.

-i Idempotent mode for "start" and "daemonize":

Normally, if another server instance has the server control socket locked, a "start" or "daemonize"
attempt will fail. With this flag set, if another instance is already running, this instance will
report success and exit with status zero immediately.

ACTIONS

       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.

       start
           Starts gdnsd as a runtime DNS server foreground process, emitting log output to stderr.

       daemonize
           Starts gdnsd as a detached background daemonize process in a new session, parented to PID  1  (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).

       Any other commandline option will be treated as invalid, which will result in  displaying  a  short  help
       text  to STDERR and exiting with a non-zero exit status.  This includes things like the ubiquitous --help
       and --version.

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 "root", or attempt
       any actions that would commonly require "root" 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
       DNS listening ports, which default to being in the privileged range, will Just Work.

       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,

SYSTEMD COMPATIBILITY

       When run as a systemd service, "start" should be used rather than "daemonize", the "-l"  flag  should  be
       used,  and  the  type should be set to "Type=notify" with "NotifyAccess=all".  The latter bits will cause
       systemd to set $NOTIFY_SOCKET 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.  "gdnsdctl -l stop"
       should be used for the "ExecStop=" command.

       The  source  tree  contains  an  example  systemd  unit  file  with  reasonable defaults for a production
       deployment.

ZONE FILES - RFC1035

The directory for standard RFC1035 zone files (the default zone data backend) is the subdirectory named
zones/ in the configuration directory, so the default would be /etc/gdnsd/zones/.

RFC1035 zone files are the traditional zone file format that one typically uses with e.g. BIND. For more
information on the internal format and processing of these files, see gdnsd.zonefile(5). This section is
about how the directory itself is managed.

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 "." are ignored. All
zone file must be regular files (as opposed to directories, symlinks, sockets, etc).

In order to better support the special case of RFC 2137 -style classless in-addr.arpa delegation zones
(which contain forward slashes), any "@" symbol in the filename will be translated to a forward slash
("/") when transforming a filename into its corresponding zone name.

For similar reasons, if your server is intended to serve the root of the DNS, the filename for the root
zone should be the special filename ROOT_ZONE, rather than the impossible literal filename .. 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.

The standard DNS zone file escape sequences are recognized within the filenames (e.g. "\." for a dot
within a label, or "\NNN" where NNN is a decimal integer in the range 0 - 255), if for some reason you
need a strange character in your zone name.

Trailing dots on zonefile names are ignored; e.g. example.com and example.com. are functionally
equivalent.

Duplicate zones (e.g. having both of the above representations of "example.com" present in the zones
directory, and/or adding a different case-mapping such as EXample.Com) are illegal.

Subzones (e.g. having zonefiles for both "example.com" and "subz.example.com") are also illegal.

ZONE FILES - RELOADING

       "gdnsdctl  reload-zones"  triggers  re-loading all zone data.  The reload operation is done in a separate
       thread from the main server and doesn't interrupt DNS request flow.

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

       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.

DIRECTORIES

Important directory paths for the core daemon code:

/etc/gdnsd
Default configuration directory, unless overridden via "-c". The primary configuration file is
always the file config in the configuration directory.

/run/gdnsd
Default run_dir. This is where the daemon's control socket and lock files are created. See the
entry for "run_dir" in the gdnsd.config(5) manpage for more information about this directory.

/var/lib/gdnsd
Default state_dir. The admin_state file is read from this directory for administrative state-
overrides on monitored resources, see below in the FILES section. See the entry for "state_dir" in
the gdnsd.config(5) manpage for more information about this directory.

/usr/libexec/gdnsd
This is the default path for daemon-private executables that users should not run. The only current
case is gdnsd_extmon_helper for the extmon plugin and the path for this can be overridden in that
plugin's configuration, documented in gdnsd-plugin-extmon(8).

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.

A basic understanding of how both monitoring and resolution plugins in gdnsd work is assumed (see
gdnsd.config(5)). This file is parsed as a vscf hash data structure (again, see gdnsd.config(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.

For normal monitored resources, the typical form of a key would be "THING/service_type", where "THING" is
the monitored address or CNAME value and "service_type" is the service_type configured to monitor that
address or CNAME value by one or more resolver plugins. The value portion takes the form of
"STATE[/TTL]", where "STATE" is "UP" or "DOWN" and the TTL portion is an optional override of the
monitored TTL.

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.

Example:

/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

Some resolution plugins can also register virtual resources (which are not monitored by any
"service_type") solely for the purpose of administrative override of decision-making. Currently the
geoip and metafo plugins do this for their "datacenters", and the keys they create take the form of
"plugin_name/resname/dcname" to force a datacenter's state at the per-resource level. The geoip plugin
also supports keys of the form "plugin_name/mapname/dcname" 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.