Provided by: gdnsd_2.2.0-1ubuntu1_i386 bug

NAME

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

SYNOPSIS

       Example plugin config:

         service_types => {
           wget_ssl_index => {
             plugin => "extmon",
             timeout => 15,
             interval => 30,
             cmd => ["/usr/bin/wget", "-T", "3", "-q", "-O", "/dev/null", "https://%%ITEM%%/index.html"]
           },
           svc_alwaysok => {
             plugin => "extmon",
             timeout => 1,
             direct => true,
             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/lib/i386-linux-gnu/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 directory at
           /usr/lib/i386-linux-gnu/gdnsd/gdnsd_extmon_helper.  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's plugin
           library path (default /usr/lib/i386-linux-gnu/gdnsd) as well.

       helper_failure_action
           String, either "stasis" or "kill_daemon".  Default is "stasis".

           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 "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 or CNAME text 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.

       direct
           Boolean, default false.

           Normally extmon's results are processed by the same anti-flap state
           machine used for traditional monitors like the HTTP and TCP
           monitoring plugins.  This means the results are subject to the
           various thresholds ("ok_thresh", "up_thresh", "down_thresh") and it
           may take some time for a new persistent state to actually affect
           resolution.

           If "direct" is set to "true", the results of extmon's monitoring
           are applied directly and immediately as the final state of the
           monitored resources after every monitoring check.  If your command
           flaps back and forther between success and failure on every run, so
           will the internal state and so will the resulting changes in
           resolution.  Useful if extmon is actually gathering state from an
           external complex monitoring environment that has already taken care
           of things like anti-flap measures.

EXECUTION ENVIRONMENT

       The plugin launches a helper binary gdnsd_extmon_helper during daemon
       startup, 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 muck with the
       execution of the external commands).  This separation also prevents a
       class of functional and security bugs related to mixing runtime
       pthreads with routine forking to exec the child processes.

       The executed scripts will run 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 "-f start".

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