GDNSD-PLUGIN-EXTMON(8) gdnsd GDNSD-PLUGIN-EXTMON(8)NAMEgdnsd-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" }
}
DESCRIPTIONgdnsd-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 ALSOgdnsd.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/>.
gdnsd 1.11.0 2013-12-06 GDNSD-PLUGIN-EXTMON(8)
