NAME

    gdnsd - An authoritative DNS daemon

SYNOPSIS

      Usage: gdnsd [-d <rootdir> ] <action>
      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/>.

