NAME

       gdnsd - An authoritative DNS daemon

SYNOPSIS

         Usage: gdnsd [-s] [-S] [-d <rootdir> ] <action>
           -s - Force 'zones_strict_startup = true' for this invocation
           -S - Force 'zones_strict_data = true' for this invocation
           -d - [see "THE ROOTDIR ARGUMENT" below]
         Actions:
           checkconf - Checks validity of configuration and zonefiles
           startfg - Start gdnsd in foreground mode with logging to stderr
           start - Start gdnsd as a regular daemon
           stop - Stops a running daemon previously started by 'start'
           reload - Send SIGHUP to running daemon for zone data reload
           restart - Equivalent to checkconf && stop && start, but faster
           force-reload - Aliases 'restart'
           condrestart - Does 'restart' action only if already running
           try-restart - Aliases 'condrestart'
           status - Checks the status of the running daemon

DESCRIPTION

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

       Other than the "action" argument, the only other argument is "-d" for setting a chroot
       directory, which is discussed in detail below.  The commandline parsing is sensitive to
       ordering: "-d" must come before the action, if used.

THE ROOTDIR ARGUMENT

       The "-d <rootdir>" argument specifies whether gdnsd will use a chroot directory (or not)
       and the path of that directory.  The special value "system" indicates to *not* use a
       chroot directory, and use the normal system paths defined via autoconf.  The default can
       be changed at build time, and you can see what your build's default is by executing e.g.
       "gdnsd --help".  The default default is "system".

       If a default or commandline-supplied chroot directory is in use, all files which gdnsd
       interacts with at runtime live within that chroot directory.

       In the chroot case, gdnsd will create the chroot directory and all structure within on
       startup if necessary, but will not create the parent of the chroot directory for you.

BASIC SECURITY

       When started as the "root" user, gdnsd will always attempt to drop privileges to another
       user, and will fail fatally if that does not succeed.  The default username for this is
       "gdnsd", but this can be overridden in the main config file.

       If a chroot directory is in use and gdnsd is started as the "root" user, the daemon will
       also permanently chroot itself into that directory on startup.  If a chroot directory is
       specified, but the daemon is started as a regular user, the daemon will "chdir" to the
       root directory and use relative paths to mimick the chroot functionality.  This can be
       useful if, for example, you're using external software to secure the daemon in some jail-
       like structure, or running tests as a regular user against test data.

BASIC CONFIGURATION

       There is a single primary configuration file. Its pathname is fixed at build time for the
       "system" case, and fixed relative to the chroot directory in the chroot case.  In the
       "system" case it will live at $sysconfdir/gdnsd/config, where $sysconfdir will typically
       be /etc or /usr/local/etc depending on autoconf configuration.

       In the chroot case the path is "/etc/config" within the chroot 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 and listen on
       port 53 of all available interfaces using default settings.

ZONE FILES

       The zones directory is the subdirectory named "zones" in the same location as the main
       config file (see above re: chroot -vs- system).

       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 other files must be regular files (as opposed to
       directories, symlinks, sockets, etc).

       The zones directory is handled dynamically.  It can be empty at startup, which results in
       all queries returning "REFUSED".  As files are added, modified, and deleted in this
       directory, zone data will automatically change at runtime.

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

       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
       handled by loading both and giving runtime lookup priority to one of the copies based on a
       couple of simple rules: the highest "serial" wins, and if more than one file has the
       highest serial, the highest filesystem "mtime" value wins.  If the primary copy is later
       removed, any remaining copy of the zone will be promoted for runtime lookups according to
       that same ordering.

       Subzones (e.g. having zonefiles for both "example.com" and "subz.example.com") are only
       marginally supported.  The child zone will be loaded into memory, but its data won't be
       available for lookup, as it is suppressed by the existence of the parent zone.  If the
       parent zone is later removed, the subzone data will become available.  Logically, it is
       not possible for a single server to be authoritative for both a subzone and its parent
       zone at the same time, as each "role" (parent and child) requires different responses to
       requests for data within the child zone.  gdnsd choses to default to the "parent" role in
       these conflict cases.

       See gdnsd.zonefile(5) for details on the internal syntax of the zonefiles themselves.

ACTIONS

       gdnsd acts as its own initscript, internalizing daemon management functions.  All valid
       invocations of the gdnsd command include an action, most of which model normal initscript
       actions.  You may still want a light initscript wrapper to comply with distribution
       standards for e.g. terminal output on success/failure, but it's not necessary for basic
       functionality.

       checkconf
           Checks the validity of the configuration file and zonefiles, setting the exit status
           appropriately (0 for success).

           The "start", "startfg", and all "restart"-like actions implicitly do the same checks
           as "checkconf" as they load the configuration for runtime use.

       startfg
           Starts gdnsd in foreground mode, with all of the logging that would normally go to
           syslog appearing instead on stderr.  Useful for debugging and testing.

       start
           Starts gdnsd as a regular background daemon.

       stop
           Stops the gdnsd daemon previously started by start.

       restart
           This is equivalent to the sequence "checkconf && stop && start", but faster.  What
           actually happens behind the scenes is a bit more complicated:

           "restart" is a special case of "start" which first does all of the "checkconf" actions
           (bringing all the runtime data into memory), then stops the existing daemon, and then
           finishes starting itself (acquiring sockets, dropping privs, spawning threads, etc).

           The net result is that this minimizes the pause in service availability during the
           restart (especially if you have a large volume of zone data that takes significant
           time to load), and also leaves the original daemon instance untouched if the
           configuration is invalid (you've made an error in your new zone data, etc).

       reload
           Sends "SIGHUP" to the running daemon, forcing a manual re-check of the zones directory
           for updated files.

       force-reload
           An alias for "restart".

       condrestart
           This is basically "restart only if already running".

           Performs the same actions as "restart", but aborts early (with a successful exit
           value) if the daemon was not already running.

       try-restart
           Alias for "condrestart".

       status
           Checks the status of the running daemon, returning 0 if it is running or non-zero if
           it isn't.

       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.

ENVIRONMENT VARIABLES

       TZ  On most systems tested, gdnsd's current solution for getting syslog timestamps correct
           while under "chroot()" seems to work fine, as it does "tzset()" before "chroot()", and
           so no special setting of the "TZ" environment variable is required.

           On some older/stranger systems, the syslog messages will revert to UTC timestamps
           after "chroot()".  The workaround for these systems is to either set the "TZ"
           environment variable in gdnsd's initscript to a value like "/etc/localtime", which
           will make glibc cache the timezone correctly, or to copy all of the relevant timezone
           files into the chroot directory (/etc/localtime and perhaps all of
           /usr/share/zoneinfo).  Or whatever your platform may require.  Patches welcome.

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.

       SIGHUP
           Causes the daemon to attempt to load any new changes to the zone data.

       SIGPIPE
           Ignored when daemonized.

EXIT STATUS

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

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