Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GDNSD-PLUGIN-EXTMON(8)		     gdnsd		GDNSD-PLUGIN-EXTMON(8)

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/local/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 directory at
	   /usr/local/libexec/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/local/lib/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/>.

gdnsd 2.2.4			  2017-05-18		GDNSD-PLUGIN-EXTMON(8)

NAME | SYNOPSIS | DESCRIPTION | CONFIGURATION - GLOBAL | CONFIGURATION - PER-SERVICE-TYPE | EXECUTION ENVIRONMENT | SEE ALSO | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=gdnsd-plugin-extmon&sektion=8&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help