+=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.
an integer if the data-source is a counter, or a double if the data-source is
of type "gauge". You can submit an undefined gauge-value by using B<U>. When
submitting B<U> to a counter the behavior is undefined. The time is given as
-epoch (i.E<nbsp>e. standard UNIX time).
+epoch (i.E<nbsp>e. standard UNIX time) or B<N> to use the current time.
You can mix options and values, but the order is important: Options only
effect following values, so specifying an option as last field is allowed, but
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>
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