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", "%%IPADDR%%"]
           },
           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 "%%IPADDR%%" (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/>.