=head1 SYNOPSIS
- Mode Client
- DataDir /path/to/data/
- PIDFile /path/to/pidfile/collectd.pid
- LogFile /path/to/logfile/collectd.log
- Server 123.123.123.123
- Port 12345
+ BaseDir "/path/to/data/"
+ PIDFile "/path/to/pidfile/collectd.pid"
+ LogFile "/path/to/logfile/collectd.log"
+ Server "123.123.123.123" 12345
LoadPlugin cpu
LoadPlugin load
LoadPlugin ping
<Plugin ping>
- Host example.org
- Host provider.net
+ Host "example.org"
+ Host "provider.net"
</Plugin>
=head1 DESCRIPTION
This config file controls how the system statistics collection daemon
-B<collectd> behaves. The most significant options are B<Mode>, which controlls
-if the daemon will act as client, server or will be independent in local mode,
-and B<LoadPlugin> which controls which plugins to load.
+B<collectd> behaves. The most significant option is B<LoadPlugin>, which
+controls which plugins to load. These plugins ultimately define collectd's
+behavior.
The syntax of this config file is similar to the config file of the famos
B<Apache Webserver>. Each line containes either a key-value-pair or a
section-start or -end. Empty lines and everything after the hash-symbol `#' is
-ignored.
+ignored. Values are either string, enclosed in double-quotes,
+(floating-point-)numbers or a boolean extression, i.E<nbsp>e. either B<true> or
+B<false>. String containing of only alphanumeric characters and underscores do
+not need to be quoted.
=head1 GLOBAL OPTIONS
=over 4
-=item B<Mode> (B<Local>|B<Client>|B<Server>)
+=item B<BaseDir> I<Directory>
-Sets the operating mode. See the section B<MODES> in L<collectd(1)> for a
-description. This option determines which other options are allowed. Defaults
-to B<Local>.
+Sets the base directory. This is the directory beneath all RRD-files are
+created. Possibly more subdirectories are created. This is also the working
+directory for the daemon.
=item B<LoadPlugin> I<Plugin>
=item B<PIDFile> I<File>
Sets where to write the PID file to. This file is overwritten when it exists
-and deleted when the program ist stopped. Available in B<all modes>.
-
-=item B<DataDir> I<Directory>
-
-Sets the data directory. This is the directory beneath all RRD-files are
-created. Possibly more subdirectories are created. This is also the working
-directory for the daemon. Available in B<all modes>, though the B<Server> mode
-won't write to this directory.
+and deleted when the program ist stopped. Some init-scripts might override this
+setting using the B<-P> commandline option.
=item B<LogFile> I<File>
Sets the file to write debugging output to. This is only used if compiled with
-debugging enabled. It's ignored otherwise. Available in B<all modes>.
+debugging enabled. It's ignored otherwise.
+
+=back
+
+=head1 PLUGIN OPTIONS
+
+Some Plugins may register own options. These options must be inclosed in a
+C<Plugin>-Section. Which options exist depends on the plugin used:
+
+=head2 Plugin C<apache>
+
+To configure the C<apache>-plugin you first need to configure the Apache
+webserver correctly. The Apache-plugin C<mod_status> needs to be loaded and
+working and the C<ExtendedStatus> directive needs to be B<enabled>. You can use
+the following snipped to base your Apache config upon:
+
+ ExtendedStatus on
+ <IfModule mod_status.c>
+ <Location /mod_status>
+ SetHandler server-status
+ </Location>
+ </IfModule>
+
+The following options are accepted by the C<apache>-plugin:
+
+=over 4
+
+=item B<URL> I<http://host/mod_status?auto>
+
+Sets the URL of the C<mod_status> output. This needs to be the output generated
+by C<ExtendedStatus on> and it needs to be the machine readable output
+generated by appending the C<?auto> argument.
+
+=item B<User> I<Username>
-=item B<Server> I<IP-address>
+Optional user name needed for authentication.
-The server to send data to. B<This is not yet implemented!> Maybe a better name
-for this was B<Receiver>, since I plan on detecting multicast groups
-automatically. On the other hand a extra MulticastGroup-option would be of
-interest for the server process. Anyhow, right now this is available for the
-B<Client> mode only.
+=item B<Password> I<Password>
-=item B<Port> I<Port-number>
+Optional password needed for authentication.
-(UDP-)Port to send packages to or to bind to and wait for packages. This option
-is available in the B<Client> and B<Server> mode.
+=item B<CACert> I<File>
+
+File that holds one or more SSL certificates. If you want to use HTTPS you will
+possibly need this option. What CA certificates come bundeled with C<libcurl>
+and are checked by default depends on the distribution you use.
=back
-=head1 PLUGIN OPTIONS
+=head2 Plugin C<apcups>
-Some Plugins may register own options. These options must be inclosed in a
-C<Plugin>-Section. Which options exist depends on the plugin used:
+=over 4
+
+=item B<Host> I<Hostname>
+
+Hostname of the host running B<apcupsd>. Defaults to B<localhost>. Please note
+that IPv6 support has been disabled unless someone can confirm or decline that
+B<apcupsd> can handle it.
+
+=item B<Port> I<Port>
+
+TCP-Port to connect to. Defaults to B<3551>.
+
+=back
+
+=head2 Plugin C<df>
+
+=over 4
+
+=item B<Device> I<Device>
+
+Select partitions based on the devicename.
+
+=item B<MountPoint> I<Directory>
+
+Select partitions based on the mountpoint.
+
+=item B<FSType> I<FSType>
+
+Select partitions based on the filesystem type.
+
+=item B<IgnoreSelected> I<true>|I<false>
+
+Invert the selection: If set to true, all partitions B<except> the ones that
+match any one of the criteria are collected. By default only selected
+partitions are collected if a selection is made. If no selection is conifured
+at all, B<all> partitions are selected.
+
+=back
+
+=head2 Plugin C<dns>
+
+=over 4
+
+=item B<Interface> I<Interface>
+
+The dns plugin uses B<libpcap> to capture dns traffic and analyses it. This
+option sets the interface that should be used. If this option is not set, or
+set to "any", the plugin will try to get packets from B<all> interfaces. This
+may not work on certain platforms, such as MacE<nbsp>OSE<nbsp>X.
+
+=item B<IgnoreSource> I<IP-address>
+
+Ignore packets that originate from this address.
+
+=back
+
+=head2 Plugin C<email>
+
+=over 4
+
+=item B<SocketGroup> I<Group>
+
+If running as root change the group of the UNIX-socket after it has been
+created. Defaults to B<collectd>.
+
+=item B<SocketPerms> I<Permissions>
+
+Change the file permissions of the UNIX-socket after it has been created. The
+permissions must be given as a numeric, octal value as you would pass to
+L<chmod(1)>. Defaults to B<0770>.
+
+=item B<MaxConns> I<Number>
+
+Sets the maximum number of connections that can be handled in parallel. Since
+this many threads will be started immediately setting this to a very high
+value will waste valuable resources. Defaults to B<5> and will be forced to be
+at most B<16384> to prevent typos and dumb mistakes.
+
+=back
+
+=head2 Plugin C<hddtemp>
+
+=over 4
+
+=item B<Host> I<Hostname>
+
+Hostname to connect to. Defaults to B<127.0.0.1>.
+
+=item B<Port> I<Port>
+
+TCP-Port to connect to. Defaults to B<7634>.
+
+=back
+
+=head2 Plugin C<irq>
+
+=over 4
+
+=item B<Irq> I<Irq>
+
+Select this irq. By default these irqs will then be collected. For a more
+detailed description see B<IgnoreSelected> below.
+
+=item B<IgnoreSelected> I<true>|I<false>
+
+If no configuration if given, the B<irq>-plugin will collect data from all
+irqs. This may not be practical, especially if no interrupts happen. Thus, you
+can use the B<Irq>-option to pick the interupt you're interested in.
+Sometimes, however, it's easier/prefered to collect all interupts I<except> a
+few ones. This option enables you to do that: By setting B<IgnoreSelected> to
+I<true> the effect of B<Irq> is inversed: All selected interupts are ignored
+and all other interupts are collected.
+
+=back
+
+=head2 Plugin C<mbmon>
+
+=over 4
+
+=item B<Host> I<Hostname>
+
+Hostname to connect to. Defaults to B<127.0.0.1>.
+
+=item B<Port> I<Port>
+
+TCP-Port to connect to. Defaults to B<411>.
+
+=back
+
+=head2 Plugin C<mysql>
+
+=over 4
+
+=item B<Host> I<Hostname>
+
+Hostname of the database server. Defaults to B<localhost>.
+
+=item B<User> I<Username>
+
+Username to use when connecting to the database.
+
+=item B<Password> I<Password>
+
+Password needed to log into the database.
+
+=item B<Database> I<Database>
+
+Select this database. Defaults to I<no database> which is a perfecly reasonable
+option for what this plugin does.
+
+=back
+
+=head2 Plugin C<network>
+
+=over 4
+
+=item B<Listen> I<Host> [I<Port>]
+
+=item B<Server> I<Host> [I<Port>]
+
+The B<Server> statement sets the server to send datagrams B<to>. The statement
+may occur multiple times to send each datagram to multiple destinations.
+
+The B<Listen> statement sets the interfaces to bind to. When multiple
+statements are found the daemon will bind to multiple interfaces.
+
+The argument I<Host> may be a hostname, an IPv4 address or an IPv6 address. If
+the argument is a multicast address the daemon will join that multicast group.
+
+If no B<Listen> statement is found the server tries join both, the default IPv6
+multicast group and the default IPv4 multicast group. If no B<Server> statement
+is found the client will try to send data to the IPv6 multicast group first. If
+that failes the client will try the IPv4 multicast group.
+
+The default IPv6 multicast group is C<ff18::efc0:4a42>. The default IPv4
+multicast group is C<239.192.74.66>.
+
+The optional I<Port> argument sets the port to use. It can either be given
+using a numeric port number or a service name. If the argument is omited the
+default port B<25826> is assumed.
+
+=item B<TimeToLive> I<1-255>
+
+Set the time-to-live of sent packets. This applies to all, unicast and
+multicast, and IPv4 and IPv6 packets. The default is to not change this value.
+That means that multicast packets will be sent with a TTL of C<1> (one) on most
+operating systems.
+
+=back
+
+=head2 Plugin C<ntpd>
+
+=over 4
+
+=item B<Host> I<Hostname>
+
+Hostname of the host running B<ntpd>. Defaults to B<localhost>.
+
+=item B<Port> I<Port>
+
+UDP-Port to connect to. Defaults to B<123>.
+
+=back
=head2 Plugin C<ping>
Host to ping periodically. This option may be repeated several times to ping
multiple hosts.
+=item B<TTL> I<0-255>
+
+Sets the Time-To-Live of generated ICMP packets.
+
+=back
+
+=head2 Plugin C<rrdtool>
+
+=over 4
+
+=item B<CacheFlush> I<Seconds>
+
+When the C<rrdtool plugin> uses a cache (by setting B<CacheTimeout>, see below)
+it writes all values for a certain RRD-file if the oldest value is older than
+(or equal to) the number of seconds specified. If some RRD-file is not updated
+anymore for some reason (the computer was shut down, the network is broken,
+etc.) some values may still be in the cache. If B<CacheFlush> is set, then the
+entire cache is searched for entries older than B<CacheTimeout> seconds and
+written to disk every I<Seconds> seconds. Since this is kind of expensive and
+does nothing under normal circumstances, this value should not be too small.
+900 seconds might be a good value, though setting this to 7200 seconds doesn't
+normally do much harm either.
+
+=item B<CacheTimeout> I<Seconds>
+
+If this option is set to a value greater than zero, the C<rrdtool plugin> will
+save values in a cache, as described above. Writing multiple values at once
+reduces IO-operations and thus lessens the load produced by updating the files.
+The tradeoff is that the graphs kind of "drag behind" and that more memory is
+used.
+
+=item B<DataDir> I<Directory>
+
+Set the directory to store RRD-files under. Per default RRD-files are generated
+beneath the daemon's working directory, i.E<nbsp>e. the B<BaseDir>.
+
+=back
+
+=head2 Plugin C<sensors>
+
+=over 4
+
+=item B<Sensor> I<chip-bus-address/type-feature>
+
+Selects the name of the sensor which you want to collect or ignore, depending
+on the B<IgnoreSelected> below. For example, the option "B<Sensor>
+I<it8712-isa-0290/voltage-in1>" will cause collectd to gather data for the
+voltage sensor I<in1> of the I<it8712> on the isa bus at the address 0290.
+
+=item B<IgnoreSelected> I<true>|I<false>
+
+If no configuration if given, the B<sensors>-plugin will collect data from all
+sensors. This may not be practical, especially for uninteresting sensors.
+Thus, you can use the B<Sensor>-option to pick the sensors you're interested
+in. Sometimes, however, it's easier/prefered to collect all sensors I<except> a
+few ones. This option enables you to do that: By setting B<IgnoreSelected> to
+I<true> the effect of B<Sensor> is inversed: All selected sensors are ignored
+and all other sensors are collected.
+
+=back
+
+=head2 Plugin C<traffic>
+
+=over 4
+
+=item B<Interface> I<Interface>
+
+Select this interface. By default these interfaces will then be collected. For a more detailed description see B<IgnoreSelected> below.
+
+=item B<IgnoreSelected> I<true>|I<false>
+
+If no configuration if given, the B<traffic>-plugin will collect data from
+all interfaces. This may not be practical, especially for loopback- and
+similar interfaces. Thus, you can use the B<Interface>-option to pick the
+interfaces you're interested in. Sometimes, however, it's easier/prefered
+to collect all interfaces I<except> a few ones. This option enables you to
+do that: By setting B<IgnoreSelected> to I<true> the effect of
+B<Interface> is inversed: All selected interfaces are ignored and all
+other interfaces are collected.
+
=back
=head1 SEE ALSO
projects / collectd.git / blobdiff