.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "GDNSD-PLUGIN-EXTMON 8" .TH GDNSD-PLUGIN-EXTMON 8 "2021-02-24" "gdnsd 3.5.2" "gdnsd" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" gdnsd\-plugin\-extmon \- gdnsd plugin for monitoring via external commands .SH "SYNOPSIS" .IX Header "SYNOPSIS" Example plugin config: .PP .Vb 10 \& 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, \& max_proc => 10, \& cmd => ["/bin/sh", "\-c", "sleep 5"] \& } \& } \& \& # optional, if installed path confuses the daemon... \& plugins => { \& extmon => { helper_path => "/usr/libexec/gdnsd/gdnsd_extmon_helper" } \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBgdnsd-plugin-extmon\fR allows you to configure external commands to provide monitoring feedback to the dynamic address plugins. .SH "CONFIGURATION \- GLOBAL" .IX Header "CONFIGURATION - GLOBAL" These are plugin-global settings which are configured within \&\f(CW\*(C`plugins => { extmon => { ... } }\*(C'\fR. .IP "\fBhelper_path\fR" 4 .IX Item "helper_path" String pathname, optional. .Sp Normally, this plugin will successfully locate its helper binary \fIgdnsd_extmon_helper\fR in the installation libexec directory at \fI/usr/libexec/gdnsd/gdnsd_extmon_helper\fR. 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. .IP "\fBhelper_failure_action\fR" 4 .IX Item "helper_failure_action" String, either \f(CW\*(C`stasis\*(C'\fR or \f(CW\*(C`kill_daemon\*(C'\fR. Default is \f(CW\*(C`stasis\*(C'\fR. .Sp This configures the behavior of the plugin if the helper process \fIgdnsd_extmon_helper\fR unexpectedly dies, which prevents the gathering of any further legitimate monitoring state updates. .Sp Regardless of this setting, there will be at least one syslog message indicating the failure. .Sp If set to \f(CW\*(C`stasis\*(C'\fR, 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. .Sp If set to \f(CW\*(C`kill_daemon\*(C'\fR, the whole gdnsd daemon will fail fatally. .SH "CONFIGURATION \- PER-SERVICE-TYPE" .IX Header "CONFIGURATION - PER-SERVICE-TYPE" The universal, plugin-neutral service_type parameters all apply in their usual sense: \f(CW\*(C`up_thresh\*(C'\fR, \f(CW\*(C`ok_thresh\*(C'\fR, \f(CW\*(C`down_thresh\*(C'\fR, \&\f(CW\*(C`interval\*(C'\fR, \f(CW\*(C`plugin\*(C'\fR, and \f(CW\*(C`timeout\*(C'\fR. See \fBgdnsd.config\fR\|(5) for basic information on these. The following are specific to this \&\f(CW\*(C`extmon\*(C'\fR plugin: .IP "\fBcmd\fR" 4 .IX Item "cmd" Array of one or more strings, required. .Sp This sets the command and arguments to execute for the monitoring check. The array is passed directly to \f(CW\*(C`execv()\*(C'\fR 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. \f(CW\*(C`"/bin/sh", "\-c", ...\*(C'\fR. .Sp All argument strings are searched for the magic string \f(CW\*(C`%%ITEM%%\*(C'\fR (which can appear multiple times per argument). Everywhere this magic string is found, the \s-1IP\s0 address or \s-1CNAME\s0 text of the resource being monitored will be substituted in its place. .Sp The command must exit with an exit value of zero for success or non-zero for failure. .IP "\fBdirect\fR" 4 .IX Item "direct" Boolean, default false. .Sp Normally extmon's results are processed by the same anti-flap state machine used for traditional monitors like the \s-1HTTP\s0 and \s-1TCP\s0 monitoring plugins. This means the results are subject to the various thresholds (\f(CW\*(C`ok_thresh\*(C'\fR, \f(CW\*(C`up_thresh\*(C'\fR, \&\f(CW\*(C`down_thresh\*(C'\fR) and it may take some time for a new persistent state to actually affect resolution. .Sp If \f(CW\*(C`direct\*(C'\fR is set to \f(CW\*(C`true\*(C'\fR, 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. .IP "\fBmax_proc\fR" 4 .IX Item "max_proc" Integer, default 0 (unlimited). .Sp The maximum number of concurrent processes to spawn. .Sp This sets the limit on the number of concurrent commands that will be run. If the limit is exceeded, excess commands are rescheduled for 0.1 seconds later. After a few runs, the processes will be spread out enough to run without running into the limit. .SH "EXECUTION ENVIRONMENT" .IX Header "EXECUTION ENVIRONMENT" The plugin launches a helper binary \fIgdnsd_extmon_helper\fR 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. .PP The executed scripts will run with the same userid the daemon normally drops privileges to. .PP The stdout, stdin, and stderr descriptors will usually be set to \fI/dev/null\fR. stdout and stderr may be open to the current tty if the main daemon was started in foreground debugging mode via \f(CW\*(C`\-f start\*(C'\fR. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBgdnsd.config\fR\|(5), \fBgdnsd\fR\|(8) .PP The gdnsd manual. .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright (c) 2012 Brandon L Black .PP This file is part of gdnsd. .PP gdnsd is free software: you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. .PP gdnsd is distributed in the hope that it will be useful, but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See the \&\s-1GNU\s0 General Public License for more details. .PP You should have received a copy of the \s-1GNU\s0 General Public License along with gdnsd. If not, see .