Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GDNSD(8)			     gdnsd			      GDNSD(8)

NAME
       gdnsd - An authoritative	DNS daemon

SYNOPSIS
	 Usage:	gdnsd [-c /usr/local/etc/gdnsd]	[-D] [-l] [-S] [-R | -i] <action>
	   -c -	Configuration directory	(default /usr/local/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 "/usr/local/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	/usr/local/etc/gdnsd.
	   The zones directory,	if not explicitly configured in	the main
	   configuration file, defaults	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 /usr/local/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:

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

       /var/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/db/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/local/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/db/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/db/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.

       Example:

	   /var/db/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

       All of the available monitored and virtual keys that can	be matched in
       this file are listed in the daemon's HTML, CSV, and JSON	-format
       outputs from the	built-in status	http server (default port 3506), as
       are their current monitors and admin_state-forced states.

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.

       SIGTERM,	SIGINT
	   Causes the daemon to	exit gracefully	with accompanying log output.
	   The exit status will	reflect	the terminating	signal appropriately.

       SIGPIPE
	   Ignored.

       SIGHUP
	   If started via "daemonize", "SIGHUP"	is explicitly ignored by the
	   background daemon, but not by the temporary foreground process
	   during initialization.  When	started	via "start", "SIGHUP" handling
	   is left at defaults,	which will normally result in unclean process
	   termination on reception.

       SIGUSR1
	   This	signal is "handled" 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
	   "gdnsdctl" mechanism, and has no real effect.  This compatibility
	   handling may	be removed in a	future major version update.

       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.

EXIT STATUS
       An exit status of zero indicates	success, anything else indicates
       failure.

       For "daemonize",	the exit status	of the initial foreground process will
       indicate	whether	the background daemon launched successfully.

       For "start", the	initial	foreground process is 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.

SEE ALSO
       gdnsd.config(5),	gdnsd.zonefile(5)

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

gdnsd 3.0.0			  2020-08-31			      GDNSD(8)

NAME | SYNOPSIS | DESCRIPTION | BASIC CONFIGURATION | COMMANDLINE OPTION FLAGS | ACTIONS | PRIVILEGES | SYSTEMD COMPATIBILITY | ZONE FILES - RFC1035 | ZONE FILES - RELOADING | DIRECTORIES | SIGNALS | EXIT STATUS | SEE ALSO | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=gdnsd&sektion=8&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help