+=encoding UTF-8
+
=head1 NAME
collectd-exec - Documentation of collectd's C<exec plugin>
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.
-Please note that this is the same format as used in the B<unixsock plugin>, see
-L<collectd-unixsock(5)>.
+=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
+
+Please note that this is the same format as used in the B<unixsock plugin>, see
+L<collectd-unixsock(5)>.
+
When collectd exits it sends a B<SIGTERM> to all still running
child-processes upon which they have to quit.
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