1=encoding UTF-8 2 3=head1 NAME 4 5collectd-exec - Documentation of collectd's C<exec plugin> 6 7=head1 SYNOPSIS 8 9 # See collectd.conf(5) 10 LoadPlugin exec 11 # ... 12 <Plugin exec> 13 Exec "myuser:mygroup" "myprog" 14 Exec "otheruser" "/path/to/another/binary" "arg0" "arg1" 15 NotificationExec "user" "/usr/lib/collectd/exec/handle_notification" 16 </Plugin> 17 18=head1 DESCRIPTION 19 20The C<exec plugin> forks off an executable either to receive values or to 21dispatch notifications to the outside world. The syntax of the configuration is 22explained in L<collectd.conf(5)> but summarized in the above synopsis. 23 24If you want/need better performance or more functionality you should take a 25long look at the C<perl plugin>, L<collectd-perl(5)>. 26 27=head1 EXECUTABLE TYPES 28 29There are currently two types of executables that can be executed by the 30C<exec plugin>: 31 32=over 4 33 34=item C<Exec> 35 36These programs are forked and values that it writes to C<STDOUT> are read back. 37The executable is forked in a fashion similar to L<init>: It is forked once and 38not again until it exits. If it exited, it will be forked again after at most 39I<Interval> seconds. It is perfectly legal for the executable to run for a long 40time and continuously write values to C<STDOUT>. 41 42See L<EXEC DATA FORMAT> below for a description of the output format expected 43from these programs. 44 45B<Warning:> If the executable only writes one value and then exits it will be 46executed every I<Interval> seconds. If I<Interval> is short (the default is 10 47seconds) this may result in serious system load. 48 49=item C<NotificationExec> 50 51The program is forked once for each notification that is handled by the daemon. 52The notification is passed to the program on C<STDIN> in a fashion similar to 53HTTP-headers. In contrast to programs specified with C<Exec> the execution of 54this program is not serialized, so that several instances of this program may 55run at once if multiple notifications are received. 56 57See L<NOTIFICATION DATA FORMAT> below for a description of the data passed to 58these programs. 59 60=back 61 62=head1 EXEC DATA FORMAT 63 64The forked executable is expected to print values to C<STDOUT>. The expected 65format is as follows: 66 67=over 4 68 69=item Comments 70 71Each line beginning with a C<#> (hash mark) is ignored. 72 73=item B<PUTVAL> I<Identifier> [I<OptionList>] I<Valuelist> 74 75Submits one or more values (identified by I<Identifier>, see below) to the 76daemon which will dispatch it to all its write-plugins. 77 78An I<Identifier> is of the form 79C<I<host>B</>I<plugin>B<->I<instance>B</>I<type>B<->I<instance>> with both 80I<instance>-parts being optional. If they're omitted the hyphen must be 81omitted, too. I<plugin> and each I<instance>-part may be chosen freely as long 82as the tuple (plugin, plugin instance, type instance) uniquely identifies the 83plugin within collectd. I<type> identifies the type and number of values 84(i.E<nbsp>e. data-set) passed to collectd. A large list of predefined 85data-sets is available in the B<types.db> file. See L<types.db(5)> for a 86description of the format of this file. 87 88The I<OptionList> is an optional list of I<Options>, where each option is a 89key-value-pair. A list of currently understood options can be found below, all 90other options will be ignored. Values that contain spaces must be quoted with 91double quotes. 92 93I<Valuelist> is a colon-separated list of the time and the values, each either 94an integer if the data-source is a counter, or a double if the data-source is 95of type "gauge". You can submit an undefined gauge-value by using B<U>. When 96submitting B<U> to a counter the behavior is undefined. The time is given as 97epoch (i.E<nbsp>e. standard UNIX time) or B<N> to use the current time. 98 99You can mix options and values, but the order is important: Options only 100effect following values, so specifying an option as last field is allowed, but 101useless. Also, an option applies to B<all> following values, so you don't need 102to re-set an option over and over again. 103 104The currently defined B<Options> are: 105 106=over 4 107 108=item B<interval=>I<seconds> 109 110Gives the interval in which the data identified by I<Identifier> is being 111collected. 112 113=item meta:B<key>=I<value> 114 115Add meta data with the key B<key> and the value I<value>. 116 117=back 118 119Please note that this is the same format as used in the B<unixsock plugin>, see 120L<collectd-unixsock(5)>. There's also a bit more information on identifiers in 121case you're confused. 122 123Since examples usually let one understand a lot better, here are some: 124 125 PUTVAL leeloo/cpu-0/cpu-idle N:2299366 126 PUTVAL alice/interface/if_octets-eth0 interval=10 1180647081:421465:479194 127 128=item B<PUTNOTIF> [I<OptionList>] B<message=>I<Message> 129 130Submits a notification to the daemon which will then dispatch it to all plugins 131which have registered for receiving notifications. 132 133The B<PUTNOTIF> if followed by a list of options which further describe the 134notification. The B<message> option is special in that it will consume the rest 135of the line as its value. The B<message>, B<severity>, and B<time> options are 136mandatory. 137 138Valid options are: 139 140=over 4 141 142=item B<message=>I<Message> (B<REQUIRED>) 143 144Sets the message of the notification. This is the message that will be made 145accessible to the user, so it should contain some useful information. As with 146all options: If the message includes spaces, it must be quoted with double 147quotes. This option is mandatory. 148 149=item B<severity=failure>|B<warning>|B<okay> (B<REQUIRED>) 150 151Sets the severity of the notification. This option is mandatory. 152 153=item B<time=>I<Time> (B<REQUIRED>) 154 155Sets the time of the notification. The time is given as "epoch", i.E<nbsp>e. as 156seconds since January 1st, 1970, 00:00:00. This option is mandatory. 157 158=item B<host=>I<Hostname> 159 160=item B<plugin=>I<Plugin> 161 162=item B<plugin_instance=>I<Plugin-Instance> 163 164=item B<type=>I<Type> 165 166=item B<type_instance=>I<Type-Instance> 167 168These "associative" options establish a relation between this notification and 169collected performance data. This connection is purely informal, i.E<nbsp>e. the 170daemon itself doesn't do anything with this information. However, websites or 171GUIs may use this information to place notifications near the affected graph or 172table. All the options are optional, but B<plugin_instance> without B<plugin> 173or B<type_instance> without B<type> doesn't make much sense and should be 174avoided. 175 176=item B<type:key=>I<value> 177 178Sets user defined meta information. The B<type> key is a single character 179defining the type of the meta information. 180 181The current supported types are: 182 183=over 8 184 185=item B<s> A string passed as-is. 186 187=back 188 189=back 190 191=back 192 193Please note that this is the same format as used in the B<unixsock plugin>, see 194L<collectd-unixsock(5)>. 195 196When collectd exits it sends a B<SIGTERM> to all still running 197child-processes upon which they have to quit. 198 199=head1 NOTIFICATION DATA FORMAT 200 201The notification executables receive values rather than providing them. In 202fact, after the program is started C<STDOUT> is connected to C</dev/null>. 203 204The data is passed to the executables over C<STDIN> in a format very similar to 205HTTP: At first there is a "header" with one line per field. Every line consists 206of a field name, ended by a colon, and the associated value until end-of-line. 207The "header" is ended by two newlines immediately following another, 208i.e. an empty line. The rest, basically the "body", is the message of the 209notification. 210 211The following is an example notification passed to a program: 212 213 Severity: FAILURE 214 Time: 1200928930.515 215 Host: myhost.mydomain.org 216 \n 217 This is a test notification to demonstrate the format 218 219The following header files are currently used. Please note, however, that you 220should ignore unknown header files to be as forward-compatible as possible. 221 222=over 4 223 224=item B<Severity> 225 226Severity of the notification. May either be B<FAILURE>, B<WARNING>, or B<OKAY>. 227 228=item B<Time> 229 230The time in epoch, i.e. as seconds since 1970-01-01 00:00:00 UTC. The value 231currently has millisecond precision (i.e. three decimal places), but scripts 232should accept arbitrary numbers of decimal places, including no decimal places. 233 234=item B<Host> 235 236=item B<Plugin> 237 238=item B<PluginInstance> 239 240=item B<Type> 241 242=item B<TypeInstance> 243 244Identification of the performance data this notification is associated with. 245All of these fields are optional because notifications do not B<need> to be 246associated with a certain value. 247 248=back 249 250=head1 ENVIRONMENT 251 252The following environment variables are set by the plugin before calling 253I<exec>: 254 255=over 4 256 257=item COLLECTD_INTERVAL 258 259Value of the global interval setting. 260 261=item COLLECTD_HOSTNAME 262 263Hostname used by I<collectd> to dispatch local values. 264 265=back 266 267=head1 USING NAGIOS PLUGINS 268 269Though the interface is far from perfect, there are tons of plugins for Nagios. 270You can use these plugins with collectd by using a simple transition layer, 271C<exec-nagios.px>, which is shipped with the collectd distribution in the 272C<contrib/> directory. It is a simple Perl script that comes with embedded 273documentation. To see it, run the following command: 274 275 perldoc exec-nagios.px 276 277This script expects a configuration file, C<exec-nagios.conf>. You can find an 278example in the C<contrib/> directory, too. 279 280Even a simple mechanism to submit "performance data" to collectd is 281implemented. If you need a more sophisticated setup, please rewrite the plugin 282to make use of collectd's more powerful interface. 283 284=head1 CAVEATS 285 286=over 4 287 288=item * 289 290The user, the binary is executed as, may not have root privileges, i.E<nbsp>e. 291must have an UID that is non-zero. This is for your own good. 292 293=item * 294 295Early versions of the plugin did not use a command but treated all lines as if 296they were arguments to the I<PUTVAL> command. When the I<PUTNOTIF> command was 297implemented, this behavior was kept for lines which start with an unknown 298command for backwards compatibility. This compatibility code has been removed 299in I<collectdE<nbsp>5>. 300 301=back 302 303=head1 SEE ALSO 304 305L<collectd(1)>, 306L<collectd.conf(5)>, 307L<collectd-perl(5)>, 308L<collectd-unixsock(5)>, 309L<fork(2)>, L<exec(3)> 310 311=head1 AUTHOR 312 313Florian Forster E<lt>octo@collectd.orgE<gt> 314 315=cut 316