src/collectd-exec.pod

   1 =head1 NAME
   2
   3 collectd-exec - Documentation of collectd's C<exec plugin>
   4
   5 =head1 SYNOPSIS
   6
   7   # See collectd.conf(5)
   8   LoadPlugin exec
   9   # ...
  10   <Plugin exec>
  11     Exec "myuser:mygroup" "myprog"
  12     Exec "otheruser" "/path/to/another/binary"
  13     NotificationExec "user" "/usr/lib/collectd/exec/handle_notification"
  14     NagiosExec "nagios:nagios" "/usr/lib/nagios/plugins/check_something"
  15   </Plugin>
  16
  17 =head1 DESCRIPTION
  18
  19 The C<exec plugin> forks of an executable either to receive values, to dispatch
  20 notifications to the outside world or to be able to use Nagios plugins.
  21
  22 If you want/need better performance or more functionality you should take a
  23 long look at the C<perl plugin>, L<collectd-perl(5)>.
  24
  25 =head1 EXECUTABLE TYPES
  26
  27 There are currently three types of executables that can be executed by the
  28 C<exec plugin>:
  29
  30 =over 4
  31
  32 =item C<Exec>
  33
  34 These programs are forked and values that it writes to C<STDOUT> are read back.
  35 The executable is forked in a fashion similar to L<init>: It is forked once and
  36 not again until it exits. If it exited, it will be forked again after at most
  37 I<Interval> seconds. It is perfectly legal for the executable to run for a long
  38 time and continuously write values to C<STDOUT>.
  39
  40 See L<EXEC DATA FORMAT> below for a description of the output format expected
  41 from these programs.
  42
  43 B<Warning:> If the executable only writes one value and then exits I will be
  44 executed every I<Interval> seconds. If I<Interval> is short (the default is 10
  45 seconds) this may result in serious system load.
  46
  47 =item C<NotificationExec>
  48
  49 The program is forked once for each notification that is handled by the daemon.
  50 The notification is passed to the program on C<STDIN> in a fashion similar to
  51 HTTP-headers. In contrast to programs specified with C<Exec> the execution of
  52 this program is not serialized, so that several instances of this program may
  53 run at once if multiple notifications are received.
  54
  55 See L<NOTIFICATION DATA FORMAT> below for a description of the data passed to
  56 these programs.
  57
  58 =item C<NagiosExec>
  59
  60 The executable is treated as a Nagios plugin. That means that the first line
  61 printed to C<STDOUT> by this program is used as the text of a notification and
  62 the severity of the notification depends on the exit status of the executable
  63 only.
  64
  65 For information on how to write Nagios plugins please refer to the Nagios
  66 documentation. If a plugin works with Nagios but not with collectd please
  67 complain on the collectd mailing list instead.
  68
  69 =back
  70
  71 =head1 EXEC DATA FORMAT
  72
  73 The forked executable is expected to print values to C<STDOUT>. The expected
  74 format is as follows:
  75
  76 =over 4
  77
  78 =item
  79
  80 Each line beginning with a C<#> (hash mark) is ignored.
  81
  82 =item
  83
  84 Other lines must consist of an I<Identifier>, an optional I<Option-List> and a
  85 I<Value-List>, separated by a spaces. A description of these two parts follows:
  86
  87 An I<Identifier> is of the form
  88 C<I<host>B</>I<plugin>B<->I<instance>B</>I<type>B<->I<instance>> with both
  89 I<instance>-parts being optional. If they're omitted the hyphen must be
  90 omitted, too.
  91
  92 The I<OptionList> is an optional list of I<Options>, where each option if a
  93 key-value-pair. A list of currently understood options can be found below, all
  94 other options will be ignored.
  95
  96 I<Valuelist> is a colon-separated list of the time and the values, each either
  97 an integer if the data-source is a counter, of a double if the data-source if
  98 of type "gauge". You can submit an undefined gauge-value by using B<U>. When
  99 submitting B<U> to a counter the behavior is undefined. The time is given as
 100 epoch (i.E<nbsp>e. standard UNIX time).
 101
 102 You can mix options and values, but the order is important: Options only
 103 effect following values, so specifying an option as last field is allowed, but
 104 useless. Also, an option applies to B<all> following values, so you don't need
 105 to re-set an option over and over again.
 106
 107 The currently defined B<Options> are:
 108
 109 =over 4
 110
 111 =item B<interval=>I<seconds>
 112
 113 Gives the interval in which the data identified by I<Identifier> is being
 114 collected.
 115
 116 =back
 117
 118 Please note that this is the same format as used in the B<unixsock plugin>, see
 119 L<collectd-unixsock(5)>. There's also a bit more information on identifiers in
 120 case you're confused.
 121
 122 Since examples usually let one understand a lot better, here are some:
 123
 124   leeloo/cpu-0/cpu-idle N:2299366
 125   alice/interface/if_octets-eth0 interval=10 1180647081:421465:479194
 126
 127 =back
 128
 129 When collectd exits it sends a B<SIGTERM> to all still running
 130 child-processes upon which they have to quit.
 131
 132 =head1 NOTIFICATION DATA FORMAT
 133
 134 The notification executables receive values rather than providing them. In
 135 fact, after the program is started C<STDOUT> is connected to C</dev/null>.
 136
 137 The data is passed to the executables over C<STDIN> in a format very similar to
 138 HTTP-headers: There is one line per field. Every line consists of a field name,
 139 ended by a colon, and the associated value until end-of-line. The input is
 140 ended by two newlines immediately following another.
 141
 142 The following is an example notification passed to a program:
 143
 144   Severity: FAILURE
 145   Time: 1200928930
 146   Host: myhost.mydomain.org
 147   Message: This is a test notification to demonstrate the format
 148   <newline>
 149
 150 The following header files are currently used. Please note, however, that you
 151 should ignore unknown header files to be as forward-compatible as possible.
 152
 153 =over 4
 154
 155 =item B<Severity>
 156
 157 Severity of the notification. May either be B<FAILURE>, B<WARNING>, or B<OKAY>.
 158
 159 =item B<Time>
 160
 161 The time in epoch, i.E<nbsp>e. as seconds since 1970-01-01 00:00:00 UTC.
 162
 163 =item B<Host>
 164
 165 Name of the host concerned.
 166
 167 =item B<Message>
 168
 169 Message of the notification. This message should be made accessible to the
 170 user somehow.
 171
 172 =back
 173
 174 =head1 CAVEATS
 175
 176 =over 4
 177
 178 =item
 179
 180 The user, the binary is executed as, may not have root privileges, i.E<nbsp>e.
 181 must have an UID that is non-zero. This is for your own good.
 182
 183 =back
 184
 185 =head1 SEE ALSO
 186
 187 L<collectd(1)>,
 188 L<collectd.conf(5)>,
 189 L<collectd-perl(5)>,
 190 L<collectd-unixsock(5)>,
 191 L<fork(2)>, L<exec(3)>
 192
 193 =head1 AUTHOR
 194
 195 Florian Forster E<lt>octo@verplant.orgE<gt>
 196
 197 =cut