src/collectd-exec.5

   1 .\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is turned on, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{
  60 .    if \nF \{
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "COLLECTD-EXEC 5"
 136 .TH COLLECTD-EXEC 5 "2015-05-20" "5.4.2.911.g0c88d3b" "collectd"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 collectd\-exec \- Documentation of collectd's "exec plugin"
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 8
 146 \&  # See collectd.conf(5)
 147 \&  LoadPlugin exec
 148 \&  # ...
 149 \&  <Plugin exec>
 150 \&    Exec "myuser:mygroup" "myprog"
 151 \&    Exec "otheruser" "/path/to/another/binary" "arg0" "arg1"
 152 \&    NotificationExec "user" "/usr/lib/collectd/exec/handle_notification"
 153 \&  </Plugin>
 154 .Ve
 155 .SH "DESCRIPTION"
 156 .IX Header "DESCRIPTION"
 157 The \f(CW\*(C`exec plugin\*(C'\fR forks of an executable either to receive values or to
 158 dispatch notifications to the outside world. The syntax of the configuration is
 159 explained in \fIcollectd.conf\fR\|(5) but summarized in the above synopsis.
 160 .PP
 161 If you want/need better performance or more functionality you should take a
 162 long look at the \f(CW\*(C`perl plugin\*(C'\fR, \fIcollectd\-perl\fR\|(5).
 163 .SH "EXECUTABLE TYPES"
 164 .IX Header "EXECUTABLE TYPES"
 165 There are currently two types of executables that can be executed by the
 166 \&\f(CW\*(C`exec plugin\*(C'\fR:
 167 .ie n .IP """Exec""" 4
 168 .el .IP "\f(CWExec\fR" 4
 169 .IX Item "Exec"
 170 These programs are forked and values that it writes to \f(CW\*(C`STDOUT\*(C'\fR are read back.
 171 The executable is forked in a fashion similar to init: It is forked once and
 172 not again until it exits. If it exited, it will be forked again after at most
 173 \&\fIInterval\fR seconds. It is perfectly legal for the executable to run for a long
 174 time and continuously write values to \f(CW\*(C`STDOUT\*(C'\fR.
 175 .Sp
 176 See \*(L"\s-1EXEC DATA FORMAT\*(R"\s0 below for a description of the output format expected
 177 from these programs.
 178 .Sp
 179 \&\fBWarning:\fR If the executable only writes one value and then exits I will be
 180 executed every \fIInterval\fR seconds. If \fIInterval\fR is short (the default is 10
 181 seconds) this may result in serious system load.
 182 .ie n .IP """NotificationExec""" 4
 183 .el .IP "\f(CWNotificationExec\fR" 4
 184 .IX Item "NotificationExec"
 185 The program is forked once for each notification that is handled by the daemon.
 186 The notification is passed to the program on \f(CW\*(C`STDIN\*(C'\fR in a fashion similar to
 187 HTTP-headers. In contrast to programs specified with \f(CW\*(C`Exec\*(C'\fR the execution of
 188 this program is not serialized, so that several instances of this program may
 189 run at once if multiple notifications are received.
 190 .Sp
 191 See \*(L"\s-1NOTIFICATION DATA FORMAT\*(R"\s0 below for a description of the data passed to
 192 these programs.
 193 .SH "EXEC DATA FORMAT"
 194 .IX Header "EXEC DATA FORMAT"
 195 The forked executable is expected to print values to \f(CW\*(C`STDOUT\*(C'\fR. The expected
 196 format is as follows:
 197 .IP "Comments" 4
 198 .IX Item "Comments"
 199 Each line beginning with a \f(CW\*(C`#\*(C'\fR (hash mark) is ignored.
 200 .IP "\fB\s-1PUTVAL\s0\fR \fIIdentifier\fR [\fIOptionList\fR] \fIValuelist\fR" 4
 201 .IX Item "PUTVAL Identifier [OptionList] Valuelist"
 202 Submits one or more values (identified by \fIIdentifier\fR, see below) to the
 203 daemon which will dispatch it to all it's write-plugins.
 204 .Sp
 205 An \fIIdentifier\fR is of the form
 206 \&\f(CW\*(C`\f(CIhost\f(CW\f(CB/\f(CW\f(CIplugin\f(CW\f(CB\-\f(CW\f(CIinstance\f(CW\f(CB/\f(CW\f(CItype\f(CW\f(CB\-\f(CW\f(CIinstance\f(CW\*(C'\fR with both
 207 \&\fIinstance\fR\-parts being optional. If they're omitted the hyphen must be
 208 omitted, too. \fIplugin\fR and each \fIinstance\fR\-part may be chosen freely as long
 209 as the tuple (plugin, plugin instance, type instance) uniquely identifies the
 210 plugin within collectd. \fItype\fR identifies the type and number of values
 211 (i.\ e. data-set) passed to collectd. A large list of predefined
 212 data-sets is available in the \fBtypes.db\fR file. See \fItypes.db\fR\|(5) for a
 213 description of the format of this file.
 214 .Sp
 215 The \fIOptionList\fR is an optional list of \fIOptions\fR, where each option is a
 216 key-value-pair. A list of currently understood options can be found below, all
 217 other options will be ignored. Values that contain spaces must be quoted with
 218 double quotes.
 219 .Sp
 220 \&\fIValuelist\fR is a colon-separated list of the time and the values, each either
 221 an integer if the data-source is a counter, or a double if the data-source is
 222 of type \*(L"gauge\*(R". You can submit an undefined gauge-value by using \fBU\fR. When
 223 submitting \fBU\fR to a counter the behavior is undefined. The time is given as
 224 epoch (i.\ e. standard \s-1UNIX\s0 time).
 225 .Sp
 226 You can mix options and values, but the order is important: Options only
 227 effect following values, so specifying an option as last field is allowed, but
 228 useless. Also, an option applies to \fBall\fR following values, so you don't need
 229 to re-set an option over and over again.
 230 .Sp
 231 The currently defined \fBOptions\fR are:
 232 .RS 4
 233 .IP "\fBinterval=\fR\fIseconds\fR" 4
 234 .IX Item "interval=seconds"
 235 Gives the interval in which the data identified by \fIIdentifier\fR is being
 236 collected.
 237 .RE
 238 .RS 4
 239 .Sp
 240 Please note that this is the same format as used in the \fBunixsock plugin\fR, see
 241 \&\fIcollectd\-unixsock\fR\|(5). There's also a bit more information on identifiers in
 242 case you're confused.
 243 .Sp
 244 Since examples usually let one understand a lot better, here are some:
 245 .Sp
 246 .Vb 2
 247 \&  PUTVAL leeloo/cpu\-0/cpu\-idle N:2299366
 248 \&  PUTVAL alice/interface/if_octets\-eth0 interval=10 1180647081:421465:479194
 249 .Ve
 250 .RE
 251 .IP "\fB\s-1PUTNOTIF\s0\fR [\fIOptionList\fR] \fBmessage=\fR\fIMessage\fR" 4
 252 .IX Item "PUTNOTIF [OptionList] message=Message"
 253 Submits a notification to the daemon which will then dispatch it to all plugins
 254 which have registered for receiving notifications.
 255 .Sp
 256 The \fB\s-1PUTNOTIF\s0\fR if followed by a list of options which further describe the
 257 notification. The \fBmessage\fR option is special in that it will consume the rest
 258 of the line as its value. The \fBmessage\fR, \fBseverity\fR, and \fBtime\fR options are
 259 mandatory.
 260 .Sp
 261 Valid options are:
 262 .RS 4
 263 .IP "\fBmessage=\fR\fIMessage\fR (\fB\s-1REQUIRED\s0\fR)" 4
 264 .IX Item "message=Message (REQUIRED)"
 265 Sets the message of the notification. This is the message that will be made
 266 accessible to the user, so it should contain some useful information. As with
 267 all options: If the message includes spaces, it must be quoted with double
 268 quotes. This option is mandatory.
 269 .IP "\fBseverity=failure\fR|\fBwarning\fR|\fBokay\fR (\fB\s-1REQUIRED\s0\fR)" 4
 270 .IX Item "severity=failure|warning|okay (REQUIRED)"
 271 Sets the severity of the notification. This option is mandatory.
 272 .IP "\fBtime=\fR\fITime\fR (\fB\s-1REQUIRED\s0\fR)" 4
 273 .IX Item "time=Time (REQUIRED)"
 274 Sets the time of the notification. The time is given as \*(L"epoch\*(R", i.\ e. as
 275 seconds since January 1st, 1970, 00:00:00. This option is mandatory.
 276 .IP "\fBhost=\fR\fIHostname\fR" 4
 277 .IX Item "host=Hostname"
 278 .PD 0
 279 .IP "\fBplugin=\fR\fIPlugin\fR" 4
 280 .IX Item "plugin=Plugin"
 281 .IP "\fBplugin_instance=\fR\fIPlugin-Instance\fR" 4
 282 .IX Item "plugin_instance=Plugin-Instance"
 283 .IP "\fBtype=\fR\fIType\fR" 4
 284 .IX Item "type=Type"
 285 .IP "\fBtype_instance=\fR\fIType-Instance\fR" 4
 286 .IX Item "type_instance=Type-Instance"
 287 .PD
 288 These \*(L"associative\*(R" options establish a relation between this notification and
 289 collected performance data. This connection is purely informal, i.\ e. the
 290 daemon itself doesn't do anything with this information. However, websites or
 291 GUIs may use this information to place notifications near the affected graph or
 292 table. All the options are optional, but \fBplugin_instance\fR without \fBplugin\fR
 293 or \fBtype_instance\fR without \fBtype\fR doesn't make much sense and should be
 294 avoided.
 295 .IP "\fBtype:key=\fR\fIvalue\fR" 4
 296 .IX Item "type:key=value"
 297 Sets user defined meta information. The \fBtype\fR key is a single character
 298 defining the type of the meta information.
 299 .Sp
 300 The current supported types are:
 301 .RS 4
 302 .IP "\fBs\fR A string passed as-is." 8
 303 .IX Item "s A string passed as-is."
 304 .RE
 305 .RS 4
 306 .RE
 307 .RE
 308 .RS 4
 309 .RE
 310 .PP
 311 Please note that this is the same format as used in the \fBunixsock plugin\fR, see
 312 \&\fIcollectd\-unixsock\fR\|(5).
 313 .PP
 314 When collectd exits it sends a \fB\s-1SIGTERM\s0\fR to all still running
 315 child-processes upon which they have to quit.
 316 .SH "NOTIFICATION DATA FORMAT"
 317 .IX Header "NOTIFICATION DATA FORMAT"
 318 The notification executables receive values rather than providing them. In
 319 fact, after the program is started \f(CW\*(C`STDOUT\*(C'\fR is connected to \f(CW\*(C`/dev/null\*(C'\fR.
 320 .PP
 321 The data is passed to the executables over \f(CW\*(C`STDIN\*(C'\fR in a format very similar to
 322 \&\s-1HTTP:\s0 At first there is a \*(L"header\*(R" with one line per field. Every line consists
 323 of a field name, ended by a colon, and the associated value until end-of-line.
 324 The \*(L"header\*(R" is ended by two newlines immediately following another,
 325 i.e. an empty line. The rest, basically the \*(L"body\*(R", is the message of the
 326 notification.
 327 .PP
 328 The following is an example notification passed to a program:
 329 .PP
 330 .Vb 5
 331 \&  Severity: FAILURE
 332 \&  Time: 1200928930.515
 333 \&  Host: myhost.mydomain.org
 334 \&  \en
 335 \&  This is a test notification to demonstrate the format
 336 .Ve
 337 .PP
 338 The following header files are currently used. Please note, however, that you
 339 should ignore unknown header files to be as forward-compatible as possible.
 340 .IP "\fBSeverity\fR" 4
 341 .IX Item "Severity"
 342 Severity of the notification. May either be \fB\s-1FAILURE\s0\fR, \fB\s-1WARNING\s0\fR, or \fB\s-1OKAY\s0\fR.
 343 .IP "\fBTime\fR" 4
 344 .IX Item "Time"
 345 The time in epoch, i.e. as seconds since 1970\-01\-01 00:00:00 \s-1UTC.\s0 The value
 346 currently has millisecond precision (i.e. three decimal places), but scripts
 347 should accept arbitrary numbers of decimal places, including no decimal places.
 348 .IP "\fBHost\fR" 4
 349 .IX Item "Host"
 350 .PD 0
 351 .IP "\fBPlugin\fR" 4
 352 .IX Item "Plugin"
 353 .IP "\fBPluginInstance\fR" 4
 354 .IX Item "PluginInstance"
 355 .IP "\fBType\fR" 4
 356 .IX Item "Type"
 357 .IP "\fBTypeInstance\fR" 4
 358 .IX Item "TypeInstance"
 359 .PD
 360 Identification of the performance data this notification is associated with.
 361 All of these fields are optional because notifications do not \fBneed\fR to be
 362 associated with a certain value.
 363 .SH "ENVIRONMENT"
 364 .IX Header "ENVIRONMENT"
 365 The following environment variables are set by the plugin before calling
 366 \&\fIexec\fR:
 367 .IP "\s-1COLLECTD_INTERVAL\s0" 4
 368 .IX Item "COLLECTD_INTERVAL"
 369 Value of the global interval setting.
 370 .IP "\s-1COLLECTD_HOSTNAME\s0" 4
 371 .IX Item "COLLECTD_HOSTNAME"
 372 Hostname used by \fIcollectd\fR to dispatch local values.
 373 .SH "USING NAGIOS PLUGINS"
 374 .IX Header "USING NAGIOS PLUGINS"
 375 Though the interface is far from perfect, there are tons of plugins for Nagios.
 376 You can use these plugins with collectd by using a simple transition layer,
 377 \&\f(CW\*(C`exec\-nagios.px\*(C'\fR, which is shipped with the collectd distribution in the
 378 \&\f(CW\*(C`contrib/\*(C'\fR directory. It is a simple Perl script that comes with embedded
 379 documentation. To see it, run the following command:
 380 .PP
 381 .Vb 1
 382 \&  perldoc exec\-nagios.px
 383 .Ve
 384 .PP
 385 This script expects a configuration file, \f(CW\*(C`exec\-nagios.conf\*(C'\fR. You can find an
 386 example in the \f(CW\*(C`contrib/\*(C'\fR directory, too.
 387 .PP
 388 Even a simple mechanism to submit \*(L"performance data\*(R" to collectd is
 389 implemented. If you need a more sophisticated setup, please rewrite the plugin
 390 to make use of collectd's more powerful interface.
 391 .SH "CAVEATS"
 392 .IX Header "CAVEATS"
 393 .IP "\(bu" 4
 394 The user, the binary is executed as, may not have root privileges, i.\ e.
 395 must have an \s-1UID\s0 that is non-zero. This is for your own good.
 396 .IP "\(bu" 4
 397 Early versions of the plugin did not use a command but treated all lines as if
 398 they were arguments to the \fI\s-1PUTVAL\s0\fR command. When the \fI\s-1PUTNOTIF\s0\fR command was
 399 implemented, this behavior was kept for lines which start with an unknown
 400 command for backwards compatibility. This compatibility code has been removed
 401 in \fIcollectd\ 5\fR.
 402 .SH "SEE ALSO"
 403 .IX Header "SEE ALSO"
 404 \&\fIcollectd\fR\|(1),
 405 \&\fIcollectd.conf\fR\|(5),
 406 \&\fIcollectd\-perl\fR\|(5),
 407 \&\fIcollectd\-unixsock\fR\|(5),
 408 \&\fIfork\fR\|(2), \fIexec\fR\|(3)
 409 .SH "AUTHOR"
 410 .IX Header "AUTHOR"
 411 Florian Forster <octo@collectd.org>