=head1 NAME

collectd-exec - Documentation of collectd's C<exec plugin>

=head1 SYNOPSIS

  # See collectd.conf(5)
  LoadPlugin exec
  # ...
  <Plugin exec>
    Exec myuser myprog
    Exec otheruser /path/to/another/binary
  </Plugin>

=head1 DESCRIPTION

The C<exec plugin> forks of an executable and reads back values that it writes
to C<STDOUT>. The executable is forked in a fassion similar to L<init>: It is
forked once and not again until it exits. If it exited, it will be forked again
after at most I<Interval> seconds. It is perfectly legal for the executable to
run for a long time and continuously write values to C<STDOUT>.

=head1 DATA FORMAT

The forked executable is expected to print values to C<STDOUT>. The expected
format is as follows:

=over 4

=item

Each line beginning with a C<#> (hash mark) is ignored.

=item

Any other line must be of the form C<I<type>,I<type-instance>,I<value>>, where
I<type> is either B<counter> or B<gauge>, I<type-instance> may not contain
C<,> (comma), C</> (slash) and C<\0> (null byte) and I<value> is either an
integer (if I<type> is B<counter>) or a floating-point number (if I<type> is
B<gauge>).

=back

The values are always considered to be "fresh", i.E<nbsp>e. the time is set to
"now".

When collectd exits it sends a B<SIGTERM> to all still running
child-processes upon which they have to quit.

=head1 CAVEATS

=over 4

=item

If the executable only writes one value and then exits I will be executed every
I<Interval> seconds. If I<Interval> is short (the default is 10 seconds) this
may result in serious system load.

=item

The user, the binary is executed as, may not have root privileges, i.E<nbsp>e.
must have an UID that is non-zero.

=back

=head1 SEE ALSO

L<collectd(1)>, L<collectd.conf(5)>, L<fork(2)>, L<exec(3)>

=head1 AUTHOR

Florian Forster E<lt>octo@verplant.orgE<gt>

=cut