+=encoding UTF-8
+
=head1 NAME
collectd-exec - Documentation of collectd's C<exec plugin>
=head1 DESCRIPTION
-The C<exec plugin> forks of an executable either to receive values or to
+The C<exec plugin> forks off an executable either to receive values or to
dispatch notifications to the outside world. The syntax of the configuration is
explained in L<collectd.conf(5)> but summarized in the above synopsis.
See L<EXEC DATA FORMAT> below for a description of the output format expected
from these programs.
-B<Warning:> If the executable only writes one value and then exits I will be
+B<Warning:> If the executable only writes one value and then exits it will be
executed every I<Interval> seconds. If I<Interval> is short (the default is 10
seconds) this may result in serious system load.
data-sets is available in the B<types.db> file. See L<types.db(5)> for a
description of the format of this file.
-The I<OptionList> is an optional list of I<Options>, where each option if a
+The I<OptionList> is an optional list of I<Options>, where each option is a
key-value-pair. A list of currently understood options can be found below, all
-other options will be ignored.
+other options will be ignored. Values that contain spaces must be quoted with
+double quotes.
I<Valuelist> is a colon-separated list of the time and the values, each either
an integer if the data-source is a counter, or a double if the data-source is
Since examples usually let one understand a lot better, here are some:
- leeloo/cpu-0/cpu-idle N:2299366
- alice/interface/if_octets-eth0 interval=10 1180647081:421465:479194
-
-Since this action was the only one supported with older versions of the C<exec
-plugin> all lines were treated as if they were prefixed with B<PUTVAL>. This is
-still the case to maintain backwards compatibility but deprecated.
+ PUTVAL leeloo/cpu-0/cpu-idle N:2299366
+ PUTVAL alice/interface/if_octets-eth0 interval=10 1180647081:421465:479194
=item B<PUTNOTIF> [I<OptionList>] B<message=>I<Message>
=item B<message=>I<Message> (B<REQUIRED>)
Sets the message of the notification. This is the message that will be made
-accessible to the user, so it should contain some useful information. This
-option must be the last option because the rest of the line will be its value,
-even if there are spaces and equal-signs following it! This option is
-mandatory.
+accessible to the user, so it should contain some useful information. As with
+all options: If the message includes spaces, it must be quoted with double
+quotes. This option is mandatory.
=item B<severity=failure>|B<warning>|B<okay> (B<REQUIRED>)
or B<type_instance> without B<type> doesn't make much sense and should be
avoided.
+=item B<type:key=>I<value>
+
+Sets user defined meta information. The B<type> key is a single character
+defining the type of the meta information.
+
+The current supported types are:
+
+=over 8
+
+=item B<s> A string passed as-is.
+
+=back
+
=back
=back
HTTP: At first there is a "header" with one line per field. Every line consists
of a field name, ended by a colon, and the associated value until end-of-line.
The "header" is ended by two newlines immediately following another,
-i.E<nbsp>e. an empty line. The rest, basically the "body", is the message of
-the notification.
+i.e. an empty line. The rest, basically the "body", is the message of the
+notification.
The following is an example notification passed to a program:
Severity: FAILURE
- Time: 1200928930
+ Time: 1200928930.515
Host: myhost.mydomain.org
\n
This is a test notification to demonstrate the format
=item B<Time>
-The time in epoch, i.E<nbsp>e. as seconds since 1970-01-01 00:00:00 UTC.
+The time in epoch, i.e. as seconds since 1970-01-01 00:00:00 UTC. The value
+currently has millisecond precision (i.e. three decimal places), but scripts
+should accept arbitrary numbers of decimal places, including no decimal places.
=item B<Host>
=back
+=head1 ENVIRONMENT
+
+The following environment variables are set by the plugin before calling
+I<exec>:
+
+=over 4
+
+=item COLLECTD_INTERVAL
+
+Value of the global interval setting.
+
+=item COLLECTD_HOSTNAME
+
+Hostname used by I<collectd> to dispatch local values.
+
+=back
+
=head1 USING NAGIOS PLUGINS
Though the interface is far from perfect, there are tons of plugins for Nagios.
The user, the binary is executed as, may not have root privileges, i.E<nbsp>e.
must have an UID that is non-zero. This is for your own good.
+=item
+
+Early versions of the plugin did not use a command but treated all lines as if
+they were arguments to the I<PUTVAL> command. When the I<PUTNOTIF> command was
+implemented, this behavior was kept for lines which start with an unknown
+command for backwards compatibility. This compatibility code has been removed
+in I<collectdE<nbsp>5>.
+
=back
=head1 SEE ALSO
=head1 AUTHOR
-Florian Forster E<lt>octo@verplant.orgE<gt>
+Florian Forster E<lt>octo@collectd.orgE<gt>
=cut