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