1 collectd on Debian
2 ==================
4 General notes:
5 --------------
7 - Some plugins require additional libraries. To prevent you from having to
8 install dependencies that you don't actually need those libraries are
9 recommendations rather than dependencies. See README.Debian.plugins in the
10 "collectd" package for details.
12 Configuring collectd:
13 ---------------------
15 - See collectd.conf(5) for details about configuring collectd.
17 Access the collected data:
18 --------------------------
20 collectd is able to write data to CSV (comma separated list) and RRD (round
21 robin database - see http://oss.oetiker.ch/rrdtool/) files. However it does
22 not create graphs from these files. This package contains two sample scripts
23 in /usr/share/doc/collectd/examples/ which can be used for this purpose. They
24 are meant to be a starting point for your own experiments - more sophisticated
25 solutions are welcome.
27 - collectd2html.pl: This script by Vincent Stehlé will search for RRD files in
28 "/var/lib/collectd/" and generate a static HTML file and a directory
29 containing several PNG files which are graphs of the RRD files found.
31 - collection.cgi: Sample CGI script that creates graphs on the fly. The Perl
32 modules "RRDs" (package librrds-perl), "URI:Escape" (package liburi-perl),
33 "HTML::Entities" (package libhtml-parser-perl) and a CGI capable web server
34 (e.g. apache2 or boa) are required for this script to run. Simply install
35 the (gunzip'ed) script to a place where the webserver will treat it as a CGI
36 script (/usr/lib/cgi-bin/ by default) and visit that page in a browser
37 (http://localhost/cgi-bin/collection.cgi by default). Please refer to your
38 webserver's documentation for more details.
40 Starting with version 4, collection.cgi requires a small config file, which
41 is installed to /etc/collectd/collection.conf. You should not need to change
42 anything there.
44 - collection3: A graphing front-end for the RRD files created by and filled
45 with collectd. See /usr/share/doc/collectd/examples/collection3/README for
46 details. This is a successor for collection.cgi.
48 Building your own plugins:
49 --------------------------
51 - Originally, plugins for collectd had to be written in C and linked as shared
52 objects. Starting with version 4.0.0, it is also possible to use plugins
53 written in the scripting language Perl or implemented as separate processes.
54 See collectd-perl(5) and collectd-exec(5) for details.
56 - If you want to contribute plugins to the official distribution you should
57 read http://collectd.org/dev-info.shtml.
59 - If you want to build C plugins for your personal use only simply install the
60 collectd-dev package and use /usr/share/doc/collectd-dev/examples/myplugin.c
61 as a starting point (Note: This is already a working example, though it does
62 not collect any useful data).
64 The resulting file can be compiled as follows:
66 gcc -DHAVE_CONFIG_H -shared -fPIC -o myplugin.so myplugin.c
68 Copy myplugin.so to /usr/lib/collectd and add the following line to your
69 collectd config file:
71 LoadPlugin myplugin
73 Restart collectd and you're done.
75 - The collectd-dev package also provides an example Perl plugin that can be
76 used as a starting point for your own development. It can be found in
77 /usr/share/doc/collectd-dev/examples/MyPlugin.pm (Note: This is already a
78 working example, though it does not collect any useful data).
80 To enable the plugin, copy it to a place where Perl can find it (i.e. a
81 subdirectory named "Collectd/Plugin" of a directory listed in @INC) and add
82 the following line to the perl plugin section in your config file:
84 LoadPlugin "Collectd::Plugin::MyPlugin"
86 or
88 BaseName "Collectd::Plugin"
89 LoadPlugin MyPlugin
91 Restart collectd and you're done.
93 Examples:
94 ---------
96 - SpamAssassin/: This directory contains a SpamAssassin plugin which passes
97 statistics to collectd using the email plugin. See the embedded POD
98 documentation for information about setup and configuration: perldoc
99 Collectd.pm.
101 - iptables/: This directory contains a script which will setup iptables to do
102 global logging of all traffic going in and out of an interface. This
103 information can then be collected by collectd's iptables plugin.
105 - collectd-network.py: Python module implementing the collectd network
106 protocol in pure Python. It currently supports to receive data and
107 notifications from collectd.
109 - collectd-unixsock.py: Python module providing an interface to collect's
110 unixsock plugin.
112 - cussh.pl: "Collectd Unix Socket SHell" is a small, interactive front-end for
113 the unixsock plugin. See the embedded POD documentation for details: perldoc
114 cussh.pl.
116 - exec-munin.px: Script to be used with the exec-plugin (see collectd-exec(5)
117 for details) which executes munin plugins, parses the output and translates
118 it to a format the exec-plugin understands. The features are limited -
119 changing the munin plugins to use the output format understood by the
120 exec-plugin is recommended. See the embedded POD documentation for more
121 details: perldoc exec-munin.px.
123 - exec-smartctl: Sample script for the exec plugin. Please refer to the
124 documentation in the file - you will have to adapt it to your needs anyway.
126 - network-proxy.py: A simple unicast proxy for collectd traffic.
128 - snmp-data.conf: Sample configuration for the SNMP plugin. This config
129 includes a few standard <Data ..> definitions that you can include in your
130 own config using the `Include' statement (available since version 4.2.0).
131 The config includes some data that is defined in the IF-MIB, e. g. octet or
132 packet counters, UPS-MIB and whatever people have send in. If you have some
133 more definitions please send them in, so others can profit from it.
135 - snmp-probe-host.px: Script to be used to automatically generate SNMP
136 configuration snippets for the "snmp" plugin. See the embedded POD
137 documentation for more details: perldoc snmp-probe-host.px.
139 Additional helper scripts:
140 --------------------------
142 - add_rra.sh: Before version 3.9.0 collectd used to create a different set of
143 RRAs. The most detailed of these old RRAs had a one minute resolution. This
144 script can be used to add three more RRAs: minimum, maximum and average with
145 a ten second resolution and 2200 rows (~6 hours). This will make hourly
146 statistics much more interesting. Please note that no sanity-checking
147 whatsoever is performed. You can seriously screw up your RRD files if you
148 don't know what you're doing.