Code

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