![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/src/collectd.conf.pod b/src/collectd.conf.pod
index 939c72a3c7e56a3ddafef90833b59867c402103e..72c2430c9534101d7887de636d96af3cdae3bb40 100644 (file)
--- a/src/collectd.conf.pod
+++ b/src/collectd.conf.pod
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
+The syntax of this config file is similar to the config file of the famous
+B<Apache Webserver>. Each line contains either a key-value-pair or a
section-start or -end. Empty lines and everything after the hash-symbol `#' is
ignored. Values are either string, enclosed in double-quotes,
-(floating-point-)numbers or a boolean extression, i.E<nbsp>e. either B<true> or
+(floating-point-)numbers or a boolean expression, i.E<nbsp>e. either B<true> or
B<false>. String containing of only alphanumeric characters and underscores do
not need to be quoted.
+The configuration is read and processed in order, i.E<nbsp>e. from top to
+bottom. So the plugins are loaded in the order listed in this config file. It
+is a good idea to load any logging plugins first in order to catch messages
+from plugins during configuration. Also, the C<LoadPlugin> option B<must> occur
+B<before> the C<E<lt>Plugin ...E<gt>> block.
+
=head1 GLOBAL OPTIONS
=over 4
Loads the plugin I<Plugin>. There must be at least one such line or B<collectd>
will be mostly useless.
+=item B<Include> I<File>
+
+Includes the file I<File> as if it was copy and pasted here. To prevent loops
+and shooting yourself in the foot in interesting ways the nesting is limited to
+a depth of 8E<nbsp>levels, which should be sufficient for most uses.
+
+It is no problem to have a block like C<E<lt>Plugin fooE<gt>> in more than one
+file, but you cannot include files from within blocks.
+
=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. Some init-scripts might override this
-setting using the B<-P> commandline option.
+and deleted when the program is stopped. Some init-scripts might override this
+setting using the B<-P> command-line option.
=item B<PluginDir> I<Directory>
=head1 PLUGIN OPTIONS
-Some Plugins may register own options. These options must be inclosed in a
+Some plugins may register own options. These options must be enclosed in a
C<Plugin>-Section. Which options exist depends on the plugin used. Some plugins
require external configuration, too. The C<apache plugin>, for example,
required C<mod_status> to be configured in the webserver you're going to
</Location>
</IfModule>
-Since it's C<mod_status> module is very similar to Apache's, B<lighttpd> is
+Since its C<mod_status> module is very similar to Apache's, B<lighttpd> is
also supported. It introduces a new field, called C<BusyServers>, to count the
number of currently connected clients. This field is also supported.
=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>
+possibly need this option. What CA certificates come bundled with C<libcurl>
and are checked by default depends on the distribution you use.
=back
=item B<DataDir> I<Directory>
-Set the directory to store RRD-files under. Per default RRD-files are generated
+Set the directory to store CSV-files under. Per default CSV-files are generated
beneath the daemon's working directory, i.E<nbsp>e. the B<BaseDir>.
=back
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
+partitions are collected if a selection is made. If no selection is configured
at all, B<all> partitions are selected.
=back
=over 4
+=item B<SocketFile> I<Path>
+
+Sets the socket-file which is to be created.
+
=item B<SocketGroup> I<Group>
-If running as root change the group of the UNIX-socket after it has been
+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>
=head2 Plugin C<exec>
Please make sure to read L<collectd-exec(5)> before using this plugin. It
-contains valueable information on when the executable is executed and the
+contains valuable information on when the executable is executed and the
output that is expected from it.
=over 4
-=item B<Exec> I<User> I<Executable>
+=item B<Exec> I<User>[:[I<Group>]] I<Executable>
-Execute the executable I<Executable> as user I<User>.
+Execute the executable I<Executable> as user I<User>. If the user name is
+followed by a colon and a group name, the effective group is set to that group.
+The real group and saved-set group will be set to the default group of that
+user. If no group is given the effective group ID will be the same as the real
+group ID.
+
+Please note that in order to change the user and/or group the daemon needs
+superuser privileges. If the daemon is run as an unprivileged user you must
+specify the same user/group here. If the daemon is run with superuser
+privileges, you must supply a non-root user here.
=back
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
+interfaces you're interested in. Sometimes, however, it's easier/preferred
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
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
+can use the B<Irq>-option to pick the interrupt you're interested in.
+Sometimes, however, it's easier/preferred to collect all interrupts 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.
+I<true> the effect of B<Irq> is inversed: All selected interrupts are ignored
+and all other interrupts are collected.
=back
Sets the log-level. If, for example, set to B<notice>, then all events with
severity B<notice>, B<warning>, or B<err> will be written to the logfile.
+Please note that B<debug> is only available if collectd has been compiled with
+debugging support.
+
=item B<File> I<File>
Sets the file to write log messages to. The special strings B<stdout> and
channels, respectively. This, of course, only makes much sense when collectd is
running in foreground- or non-daemon-mode.
+=item B<Timestamp> B<true>|B<false>
+
+Prefix all lines printed by the current time. Defaults to B<true>.
+
=back
=head2 Plugin C<mbmon>
=back
+=head2 Plugin C<memcached>
+
+The C<memcached plugin> connects to a memcached server and queries statistics
+about cache utilization, memory and bandwidth used.
+L<http://www.danga.com/memcached/>
+
+=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<11211>.
+
+=back
+
=head2 Plugin C<mysql>
The C<mysql plugin> requires B<mysqlclient> to be installed. It connects to the
database when started and keeps the connection up as long as possible. When the
connection is interrupted for whatever reason it will try to re-connect. The
-plugin logs loud complaints in case anything goes wrong.
+plugin will complaint loudly in case anything goes wrong.
This plugin issues C<SHOW STATUS> and evaluates C<Bytes_{received,sent}>,
C<Com_*> and C<Handler_*> which correspond to F<mysql_octets.rrd>,
=item B<Database> I<Database>
-Select this database. Defaults to I<no database> which is a perfecly reasonable
+Select this database. Defaults to I<no database> which is a perfectly reasonable
option for what this plugin does.
=back
+=head2 Plugin C<netlink>
+
+The C<netlink> plugin uses a netlink socket to query the Linux kernel about
+statistics of various interface and routing aspects.
+
+=over 4
+
+=item B<Interface> I<Interface>
+
+=item B<VerboseInterface> I<Interface>
+
+Instruct the plugin to collect interface statistics. This is basically the same
+as the statistics provided by the C<interface> plugin (see above) but
+potentially much more detailed.
+
+When configuring with B<Interface> only the basic statistics will be collected,
+namely octets, packets, and errors. These statistics are collected by
+the C<interface> plugin, too, so using both at the same time is no benefit.
+
+When configured with B<VerboseInterface> all counters B<except> the basic ones,
+so that no data needs to be collected twice if you use the C<interface> plugin.
+This includes dropped packets, received multicast packets, collisions and a
+whole zoo of differentiated RX and TX errors. You can try the following command
+to get an idea of what awaits you:
+
+ ip -s -s link list
+
+If I<Interface> is B<All>, all interfaces will be selected.
+
+=item B<QDisc> I<Interface> [I<QDisc>]
+
+=item B<Class> I<Interface> [I<Class>]
+
+=item B<Filter> I<Interface> [I<Filter>]
+
+Collect the octets and packets that pass a certain qdisc, class or filter.
+
+QDiscs and classes are identified by their type and handle (or classid).
+Filters don't necessarily have a handle, therefore the parent's handle is used.
+The notation used in collectd differs from that used in tc(1) in that it
+doesn't skip the major or minor number if it's zero and doesn't print special
+ids by their name. So, for example, a qdisc may be identified by
+C<pfifo_fast-1:0> even though the minor number of B<all> qdiscs is zero and
+thus not displayed by tc(1).
+
+If B<QDisc>, B<Class>, or B<Filter> is given without the second argument,
+i.E<nbsp>.e. without an identifier, all qdiscs, classes, or filters that are
+associated with that interface will be collected.
+
+Since a filter itself doesn't necessarily have a handle, the parent's handle is
+used. This may lead to problems when more than one filter is attached to a
+qdisc or class. This isn't nice, but we don't know how this could be done any
+better. If you have a idea, please don't hesitate to tell us.
+
+As with the B<Interface> option you can specify B<All> as the interface,
+meaning all interfaces.
+
+Here are some examples to help you understand the above text more easily:
+
+ <Plugin netlink>
+ VerboseInterface "All"
+ QDisc "eth0" "pfifo_fast-1:0"
+ QDisc "ppp0"
+ Class "ppp0" "htb-1:10"
+ Filter "ppp0" "u32-1:0"
+ </Plugin>
+
+=item B<IgnoreSelected>
+
+The behaviour is the same as with all other similar plugins: If nothing is
+selected at all, everything is collected. If some things are selected using the
+options described above, only these statistics are collected. If you set
+B<IgnoreSelected> to B<true>, this behavior is inversed, i.E<nbsp>e. the
+specified statistics will not be collected.
+
+=back
+
=head2 Plugin C<network>
=over 4
@@ -433,13 +563,13 @@ 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.
+that fails 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
+using a numeric port number or a service name. If the argument is omitted the
default port B<25826> is assumed.
=item B<TimeToLive> I<1-255>
the sending sockets. This should only be activated when the B<Listen>- and
B<Server>-statements differ. Otherwise packets may be send multiple times to
the same multicast group. While this results in more network traffic than
-neccessary it's not a huge problem since the plugin has a duplicate detection,
+necessary it's not a huge problem since the plugin has a duplicate detection,
so the values will not loop.
=item B<CacheFlush> I<Seconds>
=back
+=head2 Plugin C<nginx>
+
+This plugin collects the number of connections and requests handled by the
+C<nginx daemon> (speak: engineE<nbsp>X), a HTTP and mail server/proxy. It
+queries the page provided by the C<ngx_http_stub_status_module> module, which
+isn't compiled by default. Please refer to
+L<http://wiki.codemongers.com/NginxStubStatusModule> for more information on
+how to compile and configure nginx and this module.
+
+The following options are accepted by the C<nginx plugin>:
+
+=over 4
+
+=item B<URL> I<http://host/nginx_status>
+
+Sets the URL of the C<ngx_http_stub_status_module> output.
+
+=item B<User> I<Username>
+
+Optional user name needed for authentication.
+
+=item B<Password> I<Password>
+
+Optional password needed for authentication.
+
+=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 bundled with C<libcurl>
+and are checked by default depends on the distribution you use.
+
+=back
+
=head2 Plugin C<ntpd>
=over 4
=head2 Plugin C<perl>
-=over 4
-
-=item B<LoadPlugin> I<Plugin>
-
-Loads the Perl plugin I<Plugin>. This does basically the same as B<use> would
-do in a Perl program.
-
-=item B<BaseName> I<Name>
-
-Prepends I<Name>B<::> to all plugin names loaded after this option. This is
-provided for convenience to keep plugin names short.
-
-=item B<IncludeDir> I<Dir>
-
-Adds I<Dir> to the B<@INC> array. This is the same as using the B<-IDir>
-command line option or B<use lib Dir> in the source code.
-
-=back
+This plugin embeds a Perl-interpreter into collectd and provides an interface
+to collectd's plugin system. See L<collectd-perl(5)> for its documentation.
=head2 Plugin C<ping>
=head2 Plugin C<rrdtool>
You can use the settings B<StepSize>, B<HeartBeat>, B<RRARows>, and B<XFF> to
-finetune your RRD-files. Please read L<rrdcreate(1)> if you encounter problems
+fine-tune your RRD-files. Please read L<rrdcreate(1)> if you encounter problems
using these settings. If you don't want to dive into the depths of RRDTool, you
-can savely ignore these settings.
+can safely ignore these settings.
=over 4
=item B<DataDir> I<Directory>
-Set the directory to store CSV-files under. Per default CSV-files are generated
+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>.
=item B<StepSize> I<Seconds>
-Sets the stepsize of newly created RRD-files. Ideally (and per default) this
-setting is identical to the global B<Interval>-option and should not be
-smaller. If unsure, don't set this option.
+B<Force> the stepsize of newly created RRD-files. Ideally (and per default)
+this setting is unset and the stepsize is set to the interval in which the data
+is collected. Do not use this option unless you absolutely have to for some
+reason. Setting this option may cause problems with the C<snmp plugin>, the
+C<exec plugin> or when the daemon is set up to receive data from other hosts.
=item B<HeartBeat> I<Seconds>
-Sets the heartbeat of newly created RRD-files. Ideally this setting is bigger
-than the B<Interval>-setting, by default it's twice the B<Interval>-setting. If
-unsure, don't set this option.
+B<Force> the heartbeat of newly created RRD-files. This setting should be unset
+in which case the heartbeat is set to twice the B<StepSize> which should equal
+the interval in which data is collected. Do not set this option unless you have
+a very good reason to do so.
=item B<RRARows> I<NumRows>
=item B<RRATimespan> I<Seconds>
-Adds an RRA-timespan, given in seconds. Use this option mulitple times to have
+Adds an RRA-timespan, given in seconds. Use this option multiple times to have
more then one RRA. If this option is never used, the built-in default of (3600,
86400, 604800, 2678400, 31622400) is used.
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
+The trade off is that the graphs kind of "drag behind" and that more memory is
used.
=back
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
+in. Sometimes, however, it's easier/preferred 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<snmp>
+
+Since the configuration of the C<snmp plugin> is a little more complicated than
+other plugins, its documentation has been moved to an own manpage,
+L<collectd-snmp(5)>. Please see there for details.
+
=head2 Plugin C<syslog>
=over 4
severity B<notice>, B<warning>, or B<err> will be submitted to the
syslog-daemon.
+Please note that B<debug> is only available if collectd has been compiled with
+debugging support.
+
+=back
+
+=head2 Plugin C<tcpconns>
+
+The C<tcpconns plugin> counts the number of currently established TCP
+connections based on the local port and/or the remote port. Since there may be
+a lot of connections the default if to count all connections with a local port,
+for which a listening socket is opened. You can use the following options to
+fine-tune the ports you are interested in:
+
+=over 4
+
+=item B<ListeningPorts> I<true>|I<false>
+
+If this option is set to I<true>, statistics for all local ports for which a
+listening socket exists are collected. The default depends on B<LocalPort> and
+B<RemotePort> (see below): If no port at all is specifically selected, the
+default is to collect listening ports. If specific ports (no matter if local or
+remote ports) are selected, this option defaults to I<false>, i.E<nbsp>e. only
+the selected ports will be collected unless this option is set to I<true>
+specifically.
+
+=item B<LocalPort> I<Port>
+
+Count the connections to a specific local port. This can be used to see how
+many connections are handled by a specific daemon, e.E<nbsp>g. the mailserver.
+You have to specify the port in numeric form, so for the mailserver example
+you'd need to set B<25>.
+
+=item B<RemotePort> I<Port>
+
+Count the connections to a specific remote port. This is useful to see how
+much a remote service is used. This is most useful if you want to know how many
+connections a local service has opened to remote services, e.E<nbsp>g. how many
+connections a mail server or news server has to other mail or news servers, or
+how many connections a web proxy holds to web servers. You have to give the
+port in numeric form.
+
=back
=head2 Plugin C<unixsock>
=item B<SocketGroup> I<Group>
-If running as root change the group of the UNIX-socket after it has been
+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>
L<collectd(1)>,
L<collectd-exec(5)>,
+L<collectd-perl(5)>,
L<collectd-unixsock(5)>,
L<hddtemp(8)>,
L<kstat(3KSTAT)>,