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