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. I<plugin> and each I<instance>-part may be chosen freely as long
  91 as the tuple (plugin, plugin instance, type instance) uniquely identifies the
  92 plugin within collectd. I<type> identifies the type and number of values
  93 (i.E<nbsp>e. data-set) passed to collectd. A large list of predefined
  94 data-sets is available in the B<types.db> file. See L<types.db(5)> for a
  95 description of the format of this file.
  96
  97 The I<OptionList> is an optional list of I<Options>, where each option if a
  98 key-value-pair. A list of currently understood options can be found below, all
  99 other options will be ignored.
 100
 101 I<Valuelist> is a colon-separated list of the time and the values, each either
 102 an integer if the data-source is a counter, of a double if the data-source if
 103 of type "gauge". You can submit an undefined gauge-value by using B<U>. When
 104 submitting B<U> to a counter the behavior is undefined. The time is given as
 105 epoch (i.E<nbsp>e. standard UNIX time).
 106
 107 You can mix options and values, but the order is important: Options only
 108 effect following values, so specifying an option as last field is allowed, but
 109 useless. Also, an option applies to B<all> following values, so you don't need
 110 to re-set an option over and over again.
 111
 112 The currently defined B<Options> are:
 113
 114 =over 4
 115
 116 =item B<interval=>I<seconds>
 117
 118 Gives the interval in which the data identified by I<Identifier> is being
 119 collected.
 120
 121 =back
 122
 123 Please note that this is the same format as used in the B<unixsock plugin>, see
 124 L<collectd-unixsock(5)>. There's also a bit more information on identifiers in
 125 case you're confused.
 126
 127 Since examples usually let one understand a lot better, here are some:
 128
 129   leeloo/cpu-0/cpu-idle N:2299366
 130   alice/interface/if_octets-eth0 interval=10 1180647081:421465:479194
 131
 132 =back
 133
 134 When collectd exits it sends a B<SIGTERM> to all still running
 135 child-processes upon which they have to quit.
 136
 137 =head1 NOTIFICATION DATA FORMAT
 138
 139 The notification executables receive values rather than providing them. In
 140 fact, after the program is started C<STDOUT> is connected to C</dev/null>.
 141
 142 The data is passed to the executables over C<STDIN> in a format very similar to
 143 HTTP-headers: There is one line per field. Every line consists of a field name,
 144 ended by a colon, and the associated value until end-of-line. The input is
 145 ended by two newlines immediately following another.
 146
 147 The following is an example notification passed to a program:
 148
 149   Severity: FAILURE
 150   Time: 1200928930
 151   Host: myhost.mydomain.org
 152   Message: This is a test notification to demonstrate the format
 153   <newline>
 154
 155 The following header files are currently used. Please note, however, that you
 156 should ignore unknown header files to be as forward-compatible as possible.
 157
 158 =over 4
 159
 160 =item B<Severity>
 161
 162 Severity of the notification. May either be B<FAILURE>, B<WARNING>, or B<OKAY>.
 163
 164 =item B<Time>
 165
 166 The time in epoch, i.E<nbsp>e. as seconds since 1970-01-01 00:00:00 UTC.
 167
 168 =item B<Host>
 169
 170 Name of the host concerned.
 171
 172 =item B<Message>
 173
 174 Message of the notification. This message should be made accessible to the
 175 user somehow.
 176
 177 =back
 178
 179 =head1 CAVEATS
 180
 181 =over 4
 182
 183 =item
 184
 185 The user, the binary is executed as, may not have root privileges, i.E<nbsp>e.
 186 must have an UID that is non-zero. This is for your own good.
 187
 188 =back
 189
 190 =head1 SEE ALSO
 191
 192 L<collectd(1)>,
 193 L<collectd.conf(5)>,
 194 L<collectd-perl(5)>,
 195 L<collectd-unixsock(5)>,
 196 L<fork(2)>, L<exec(3)>
 197
 198 =head1 AUTHOR
 199
 200 Florian Forster E<lt>octo@verplant.orgE<gt>
 201
 202 =cut