Code

Merge branch 'master' into collectd-4
[collectd.git] / src / collectd.conf.pod
1 =head1 NAME
3 collectd.conf - Configuration for the system statistics collection daemon B<collectd>
5 =head1 SYNOPSIS
7   BaseDir "/path/to/data/"
8   PIDFile "/path/to/pidfile/collectd.pid"
9   Server  "123.123.123.123" 12345
11   LoadPlugin cpu
12   LoadPlugin load
13   LoadPlugin ping
15   <Plugin ping>
16     Host "example.org"
17     Host "provider.net"
18   </Plugin>
20 =head1 DESCRIPTION
22 This config file controls how the system statistics collection daemon
23 B<collectd> behaves. The most significant option is B<LoadPlugin>, which
24 controls which plugins to load. These plugins ultimately define collectd's
25 behavior.
27 The syntax of this config file is similar to the config file of the famos
28 B<Apache Webserver>. Each line containes either a key-value-pair or a
29 section-start or -end. Empty lines and everything after the hash-symbol `#' is
30 ignored. Values are either string, enclosed in double-quotes,
31 (floating-point-)numbers or a boolean extression, i.E<nbsp>e. either B<true> or
32 B<false>. String containing of only alphanumeric characters and underscores do
33 not need to be quoted.
35 =head1 GLOBAL OPTIONS
37 =over 4
39 =item B<BaseDir> I<Directory>
41 Sets the base directory. This is the directory beneath all RRD-files are
42 created. Possibly more subdirectories are created. This is also the working
43 directory for the daemon.
45 =item B<LoadPlugin> I<Plugin>
47 Loads the plugin I<Plugin>. There must be at least one such line or B<collectd>
48 will be mostly useless. The names of the plugins are listed in L<collectd(1)>.
50 =item B<PIDFile> I<File>
52 Sets where to write the PID file to. This file is overwritten when it exists
53 and deleted when the program ist stopped. Some init-scripts might override this
54 setting using the B<-P> commandline option.
56 =item B<Interval> I<Seconds>
58 Configures the interval in which to query the read plugins. Obviously smaller
59 values lead to a higher system load produces by collectd, while higher values
60 lead to more coarse statistics.
62 =item B<ReadThreads> I<Num>
64 Number of threads to start for reading plugins. The default value if B<5>, but
65 you may want to increase this if you have more than five plugins that take a
66 long time to read. Mostly those are plugin that do network-IO. Setting this to
67 a value higher than the number of plugins you've loaded is totally useless.
69 =back
71 =head1 PLUGIN OPTIONS
73 Some Plugins may register own options. These options must be inclosed in a
74 C<Plugin>-Section. Which options exist depends on the plugin used:
76 =head2 Plugin C<apache>
78 To configure the C<apache>-plugin you first need to configure the Apache
79 webserver correctly. The Apache-plugin C<mod_status> needs to be loaded and
80 working and the C<ExtendedStatus> directive needs to be B<enabled>. You can use
81 the following snipped to base your Apache config upon:
83   ExtendedStatus on
84   <IfModule mod_status.c>
85     <Location /mod_status>
86       SetHandler server-status
87     </Location>
88   </IfModule>
90 Since it's C<mod_status> module is very similar to Apache's, B<lighttpd> is
91 also supported. It introduces a new field, called C<BusyServers>, to count the
92 number of currently connected clients. This field is also supported.
94 The following options are accepted by the C<apache>-plugin:
96 =over 4
98 =item B<URL> I<http://host/mod_status?auto>
100 Sets the URL of the C<mod_status> output. This needs to be the output generated
101 by C<ExtendedStatus on> and it needs to be the machine readable output
102 generated by appending the C<?auto> argument.
104 =item B<User> I<Username>
106 Optional user name needed for authentication.
108 =item B<Password> I<Password>
110 Optional password needed for authentication.
112 =item B<CACert> I<File>
114 File that holds one or more SSL certificates. If you want to use HTTPS you will
115 possibly need this option. What CA certificates come bundeled with C<libcurl>
116 and are checked by default depends on the distribution you use.
118 =back
120 =head2 Plugin C<apcups>
122 =over 4
124 =item B<Host> I<Hostname>
126 Hostname of the host running B<apcupsd>. Defaults to B<localhost>. Please note
127 that IPv6 support has been disabled unless someone can confirm or decline that
128 B<apcupsd> can handle it.
130 =item B<Port> I<Port>
132 TCP-Port to connect to. Defaults to B<3551>.
134 =back
136 =head2 Plugin C<csv>
138 =over 4
140 =item B<DataDir> I<Directory>
142 Set the directory to store RRD-files under. Per default RRD-files are generated
143 beneath the daemon's working directory, i.E<nbsp>e. the B<BaseDir>.
145 =back
147 =head2 Plugin C<df>
149 =over 4
151 =item B<Device> I<Device>
153 Select partitions based on the devicename.
155 =item B<MountPoint> I<Directory>
157 Select partitions based on the mountpoint.
159 =item B<FSType> I<FSType>
161 Select partitions based on the filesystem type.
163 =item B<IgnoreSelected> I<true>|I<false>
165 Invert the selection: If set to true, all partitions B<except> the ones that
166 match any one of the criteria are collected. By default only selected
167 partitions are collected if a selection is made. If no selection is conifured
168 at all, B<all> partitions are selected.
170 =back
172 =head2 Plugin C<dns>
174 =over 4
176 =item B<Interface> I<Interface>
178 The dns plugin uses B<libpcap> to capture dns traffic and analyses it. This
179 option sets the interface that should be used. If this option is not set, or
180 set to "any", the plugin will try to get packets from B<all> interfaces. This
181 may not work on certain platforms, such as MacE<nbsp>OSE<nbsp>X.
183 =item B<IgnoreSource> I<IP-address>
185 Ignore packets that originate from this address.
187 =back
189 =head2 Plugin C<email>
191 =over 4
193 =item B<SocketGroup> I<Group>
195 If running as root change the group of the UNIX-socket after it has been 
196 created. Defaults to B<collectd>.
198 =item B<SocketPerms> I<Permissions>
200 Change the file permissions of the UNIX-socket after it has been created. The
201 permissions must be given as a numeric, octal value as you would pass to
202 L<chmod(1)>. Defaults to B<0770>.
204 =item B<MaxConns> I<Number>
206 Sets the maximum number of connections that can be handled in parallel. Since
207 this many threads will be started immediately setting this to a very high
208 value will waste valuable resources. Defaults to B<5> and will be forced to be
209 at most B<16384> to prevent typos and dumb mistakes.
211 =back
213 =head2 Plugin C<exec>
215 Please make sure to read L<collectd/"SPECIAL PLUGINS"> before using this
216 plugin. It containes valueable information on when the executable is executed
217 and the output that is expected from it.
219 =over 4
221 =item B<Exec> I<User> I<Executable>
223 Execute the executable I<Executable> as user I<User>.
225 =back
227 =head2 Plugin C<hddtemp>
229 =over 4
231 =item B<Host> I<Hostname>
233 Hostname to connect to. Defaults to B<127.0.0.1>.
235 =item B<Port> I<Port>
237 TCP-Port to connect to. Defaults to B<7634>.
239 =back
241 =head2 Plugin C<interface>
243 =over 4
245 =item B<Interface> I<Interface>
247 Select this interface. By default these interfaces will then be collected. For
248 a more detailed description see B<IgnoreSelected> below.
250 =item B<IgnoreSelected> I<true>|I<false>
252 If no configuration if given, the B<traffic>-plugin will collect data from
253 all interfaces. This may not be practical, especially for loopback- and
254 similar interfaces. Thus, you can use the B<Interface>-option to pick the
255 interfaces you're interested in. Sometimes, however, it's easier/prefered
256 to collect all interfaces I<except> a few ones. This option enables you to
257 do that: By setting B<IgnoreSelected> to I<true> the effect of
258 B<Interface> is inversed: All selected interfaces are ignored and all
259 other interfaces are collected.
261 =back
263 =head2 Plugin C<iptables>
265 =over 4
267 =item B<Chain> I<Table> I<Chain> [I<Comment|Number> [I<Name>]]
269 Select the rules to count. If only I<Table> and I<Chain> are given, this plugin
270 will collect the counters of all rules which have a comment-match. The comment
271 is then used as type-instance.
273 If I<Comment> or I<Number> is given, only the rule with the matching comment or
274 the I<n>th rule will be collected. Again, the comment (or the number) will be
275 used as the type-instance.
277 If I<Name> is supplied, it will be used as the type-instance instead of the
278 comment or the number.
280 =back
282 =head2 Plugin C<irq>
284 =over 4
286 =item B<Irq> I<Irq>
288 Select this irq. By default these irqs will then be collected. For a more
289 detailed description see B<IgnoreSelected> below.
291 =item B<IgnoreSelected> I<true>|I<false>
293 If no configuration if given, the B<irq>-plugin will collect data from all
294 irqs. This may not be practical, especially if no interrupts happen. Thus, you
295 can use the B<Irq>-option to pick the interupt you're interested in.
296 Sometimes, however, it's easier/prefered to collect all interupts I<except> a
297 few ones. This option enables you to do that: By setting B<IgnoreSelected> to
298 I<true> the effect of B<Irq> is inversed: All selected interupts are ignored
299 and all other interupts are collected.
301 =back
303 =head2 Plugin C<logfile>
305 =over 4
307 =item B<LogLevel> B<debug|info|notice|warning|err>
309 Sets the log-level. If, for example, set to B<notice>, then all events with
310 severity B<notice>, B<warning>, or B<err> will be written to the logfile.
312 =item B<File> I<File>
314 Sets the file to write log messages to. The special strings B<stdout> and
315 B<stderr> can be used to write to the standard output and standard error
316 channels, respectively. This, of course, only makes much sense when collectd is
317 running in foreground- or non-daemon-mode.
319 =back
321 =head2 Plugin C<mbmon>
323 =over 4
325 =item B<Host> I<Hostname>
327 Hostname to connect to. Defaults to B<127.0.0.1>.
329 =item B<Port> I<Port>
331 TCP-Port to connect to. Defaults to B<411>.
333 =back
335 =head2 Plugin C<mysql>
337 =over 4
339 =item B<Host> I<Hostname>
341 Hostname of the database server. Defaults to B<localhost>.
343 =item B<User> I<Username>
345 Username to use when connecting to the database.
347 =item B<Password> I<Password>
349 Password needed to log into the database.
351 =item B<Database> I<Database>
353 Select this database. Defaults to I<no database> which is a perfecly reasonable
354 option for what this plugin does.
356 =back
358 =head2 Plugin C<network>
360 =over 4
362 =item B<Listen> I<Host> [I<Port>]
364 =item B<Server> I<Host> [I<Port>]
366 The B<Server> statement sets the server to send datagrams B<to>.  The statement
367 may occur multiple times to send each datagram to multiple destinations.
369 The B<Listen> statement sets the interfaces to bind to. When multiple
370 statements are found the daemon will bind to multiple interfaces.
372 The argument I<Host> may be a hostname, an IPv4 address or an IPv6 address. If
373 the argument is a multicast address the daemon will join that multicast group.
375 If no B<Listen> statement is found the server tries join both, the default IPv6
376 multicast group and the default IPv4 multicast group. If no B<Server> statement
377 is found the client will try to send data to the IPv6 multicast group first. If
378 that failes the client will try the IPv4 multicast group.
380 The default IPv6 multicast group is C<ff18::efc0:4a42>. The default IPv4
381 multicast group is C<239.192.74.66>.
383 The optional I<Port> argument sets the port to use. It can either be given
384 using a numeric port number or a service name. If the argument is omited the
385 default port B<25826> is assumed.
387 =item B<TimeToLive> I<1-255>
389 Set the time-to-live of sent packets. This applies to all, unicast and
390 multicast, and IPv4 and IPv6 packets. The default is to not change this value.
391 That means that multicast packets will be sent with a TTL of C<1> (one) on most
392 operating systems.
394 =item B<Forward> I<true|false>
396 If set to I<true>, write packets that were received via the network plugin to
397 the sending sockets. This should only be activated when the B<Listen>- and
398 B<Server>-statements differ. Otherwise packets may be send multiple times to
399 the same multicast group. While this results in more network traffic than
400 neccessary it's not a huge problem since the plugin has a duplicate detection,
401 so the values will not loop.
403 =item B<CacheFlush> I<Seconds>
405 For each host/plugin/type combination the C<network plugin> caches the time of
406 the last value being sent or received. Every I<Seconds> seconds the plugin
407 searches and removes all entries that are older than I<Seconds> seconds, thus
408 freeing the unused memory again. Since this process is somewhat expensive and
409 normally doesn't do much, this value should not be too small. The default is
410 1800 seconds, but setting this to 86400 seconds (one day) will not do much harm
411 either.
413 =back
415 =head2 Plugin C<ntpd>
417 =over 4
419 =item B<Host> I<Hostname>
421 Hostname of the host running B<ntpd>. Defaults to B<localhost>.
423 =item B<Port> I<Port>
425 UDP-Port to connect to. Defaults to B<123>.
427 =back
429 =head2 Plugin C<nut>
431 =over 4
433 =item B<UPS> I<upsname>B<@>I<hostname>[B<:>I<port>]
435 Add a UPS to collect data from. The format is identical to the one accepted by
436 L<upsc(8)>.
438 =back
440 =head2 Plugin C<ping>
442 =over 4
444 =item B<Host> I<IP-address>
446 Host to ping periodically. This option may be repeated several times to ping
447 multiple hosts.
449 =item B<TTL> I<0-255>
451 Sets the Time-To-Live of generated ICMP packets.
453 =back
455 =head2 Plugin C<processes>
457 =over 4
459 =item B<Process> I<Name>
461 Select more detailed statistics of processes matching this name. The statistics
462 collected for these selected processes are size of the resident segment size
463 (RSS), user- and system-time used, number of processes and number of threads,
464 and minor and major pagefaults.
466 =back
468 =head2 Plugin C<rrdtool>
470 You can use the settings B<StepSize>, B<HeartBeat>, B<RRARows>, and B<XFF> to
471 finetune your RRD-files. Please read L<rrdcreate(1)> if you encounter problems
472 using these settings. If you don't want to dive into the depths of RRDTool, you
473 can savely ignore these settings.
475 =over 4
477 =item B<DataDir> I<Directory>
479 Set the directory to store CSV-files under. Per default CSV-files are generated
480 beneath the daemon's working directory, i.E<nbsp>e. the B<BaseDir>.
482 =item B<StepSize> I<Seconds>
484 Sets the stepsize of newly created RRD-files. Ideally (and per default) this
485 setting is identical to the global B<Interval>-option and should not be
486 smaller. If unsure, don't set this option.
488 =item B<HeartBeat> I<Seconds>
490 Sets the heartbeat of newly created RRD-files. Ideally this setting is bigger
491 than the B<Interval>-setting, by default it's twice the B<Interval>-setting. If
492 unsure, don't set this option.
494 =item B<RRARows> I<NumRows>
496 The C<rrdtool plugin> calculates the number of PDPs per CDP based on the
497 B<StepSize>, this setting and a timespan. This plugin creates RRD-files with
498 three times five RRAs, i. e. five RRAs with the CFs B<MIN>, B<AVERAGE>, and
499 B<MAX>. The five RRAs are optimized for graphs covering one hour, one day, one
500 week, one month, and one year.
502 So for each timespan, it calculates how many PDPs need to be consolidated into
503 one CDP by calculating:
504   number of PDPs = timespan / (stepsize * rrarows)
506 Bottom line is, set this no smaller than the width of you graphs in pixels. The
507 default is 1200.
509 =item B<XFF> I<Factor>
511 Set the "XFiles Factor". The default is 0.1. If unsure, don't set this option.
513 =item B<CacheFlush> I<Seconds>
515 When the C<rrdtool plugin> uses a cache (by setting B<CacheTimeout>, see below)
516 it writes all values for a certain RRD-file if the oldest value is older than
517 (or equal to) the number of seconds specified. If some RRD-file is not updated
518 anymore for some reason (the computer was shut down, the network is broken,
519 etc.) some values may still be in the cache. If B<CacheFlush> is set, then the
520 entire cache is searched for entries older than B<CacheTimeout> seconds and
521 written to disk every I<Seconds> seconds. Since this is kind of expensive and
522 does nothing under normal circumstances, this value should not be too small.
523 900 seconds might be a good value, though setting this to 7200 seconds doesn't
524 normally do much harm either.
526 =item B<CacheTimeout> I<Seconds>
528 If this option is set to a value greater than zero, the C<rrdtool plugin> will
529 save values in a cache, as described above. Writing multiple values at once
530 reduces IO-operations and thus lessens the load produced by updating the files.
531 The tradeoff is that the graphs kind of "drag behind" and that more memory is
532 used.
534 =back
536 =head2 Plugin C<sensors>
538 =over 4
540 =item B<Sensor> I<chip-bus-address/type-feature>
542 Selects the name of the sensor which you want to collect or ignore, depending
543 on the B<IgnoreSelected> below. For example, the option "B<Sensor>
544 I<it8712-isa-0290/voltage-in1>" will cause collectd to gather data for the
545 voltage sensor I<in1> of the I<it8712> on the isa bus at the address 0290.
547 =item B<IgnoreSelected> I<true>|I<false>
549 If no configuration if given, the B<sensors>-plugin will collect data from all
550 sensors. This may not be practical, especially for uninteresting sensors.
551 Thus, you can use the B<Sensor>-option to pick the sensors you're interested
552 in. Sometimes, however, it's easier/prefered to collect all sensors I<except> a
553 few ones. This option enables you to do that: By setting B<IgnoreSelected> to
554 I<true> the effect of B<Sensor> is inversed: All selected sensors are ignored
555 and all other sensors are collected.
557 =back
559 =head2 Plugin C<syslog>
561 =over 4
563 =item B<LogLevel> B<debug|info|notice|warning|err>
565 Sets the log-level. If, for example, set to B<notice>, then all events with
566 severity B<notice>, B<warning>, or B<err> will be submitted to the
567 syslog-daemon.
569 =back
571 =head2 Plugin C<unixsock>
573 =over 4
575 =item B<SocketFile> I<Path>
577 Sets the socket-file which is to be created.
579 =item B<SocketGroup> I<Group>
581 If running as root change the group of the UNIX-socket after it has been 
582 created. Defaults to B<collectd>.
584 =item B<SocketPerms> I<Permissions>
586 Change the file permissions of the UNIX-socket after it has been created. The
587 permissions must be given as a numeric, octal value as you would pass to
588 L<chmod(1)>. Defaults to B<0770>.
590 =back
592 =head1 SEE ALSO
594 L<collectd(1)>
596 =head1 AUTHOR
598 Florian Forster E<lt>octo@verplant.orgE<gt>
600 =cut