NAME

    gdnsd-plugin-extmon - gdnsd plugin for monitoring via external commands

SYNOPSIS

    Example plugin config:

      service_types => {
        pingit => {
          plugin => "extmon",
          timeout => 5,
          cmd => ["/bin/ping", "-w", "2", "-c", "2", "%%ITEM%%"]
        },
        svc_alwaysok => {
          plugin => "extmon",
          timeout => 1,
          cmd => ["/bin/sh", "-c", "exit 0"]
        },
        svc_alwaysfail_via_timeout => {
          plugin => "extmon",
          timeout => 2,
          cmd => ["/bin/sh", "-c", "sleep 5"]
        }
      }

      # optional, if installed path confuses the daemon...
      plugins => {
        extmon => { helper_path => "/usr/libexec/gdnsd/gdnsd_extmon_helper" }
      }

DESCRIPTION

    gdnsd-plugin-extmon allows you to configure external commands to provide
    monitoring feedback to the dynamic address plugins.

CONFIGURATION - GLOBAL

    These are plugin-global settings which are configured within "plugins =>
    { extmon => { ... } }".

    helper_path
        String pathname, optional.

        Normally, this plugin will successfully locate its helper binary
        gdnsd_extmon_helper in the installation "$libexec/gdnsd" directory
        for gdnsd. If for some reason it can't do so, e.g. due to a
        relocated installation, you can set an explicit full pathname to the
        helper here. Note that in this case you're probably also having to
        set the daemon-global config option "plugin_search_path" as well,
        since locating plugin objects uses similar mechanisms to find the
        installation $libdir/gdnsd path.

    helper_failure_action
        String, one of "stasis", "fail_once", or "kill_daemon". Default is
        "fail_once".

        This configures the behavior of the plugin if the helper process
        gdnsd_extmon_helper unexpectedly dies, which prevents the gathering
        of any further legitimate monitoring state updates.

        Regardless of this setting, there will be at least one syslog
        message indicating the failure.

        If set to "stasis", all monitored states are left as-is with no
        further updates. The downside is that unless someone notices the
        syslog message, this failure mode is hard to notice.

        If set to "fail_once" (the default), a single artificial monitoring
        failure is triggered for each resource. This will transition
        steady-state "UP" resources to "DANGER" (and could trigger "DOWN" on
        resources that had already been in "DANGER" for several updates),
        making the failure condition a little more obvious while not
        generally affecting users too much (other than reduced TTLs for
        plugins that do that on "DANGER").

        If set to "kill_daemon", the whole gdnsd daemon will fail fatally.

CONFIGURATION - PER-SERVICE-TYPE

    The universal, plugin-neutral service_type parameters all apply in their
    usual sense: "up_thresh", "ok_thresh", "down_thresh", "interval",
    "plugin", and "timeout". See gdnsd.config(5) for basic information on
    these. The following are specific to this "extmon" plugin:

    cmd Array of one or more strings, required.

        This sets the command and arguments to execute for the monitoring
        check. The array is passed directly to "execv()" for execution (with
        re-use of the first element as the pathname to execute). If you need
        to use shell facilities, start the argument list with e.g.
        ""/bin/sh", "-c", ...".

        All argument strings are searched for the magic string "%%ITEM%%"
        (which can appear multiple times per argument). Everywhere this
        magic string is found, the IP address of the resource being
        monitored will be substituted in its place.

        The command must exit with an exit value of zero for success or
        non-zero for failure.

EXECUTION ENVIRONMENT

    The plugin launches a helper binary gdnsd_extmon_helper before the main
    daemon does its "chroot()" call, and this helper does the actual runtime
    command executions. It manages the timeouts and intervals and feeds
    results back to the plugin over a pipe. This communication is one-way at
    runtime (no daemon -> helper traffic) for security reasons (to help
    ensure that a compromised daemon can't easily leverage the helper to
    escape chroot).

    The executed scripts will run outside of the daemon's chroot, but with
    the same userid the daemon normally drops privileges to. The stdout,
    stdin, and stderr descriptors will usually be set to /dev/null. stdout
    and stderr may be open to the current tty if the main daemon was started
    in foreground debugging mode via "startfg".

SEE ALSO

    gdnsd.config(5), gdnsd(8)

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

