debian/README.Debian

   1 collectd on Debian
   2 ==================
   3
   4 General notes:
   5 --------------
   6
   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.
  11
  12 Configuring collectd:
  13 ---------------------
  14
  15 - See collectd.conf(5) for details about configuring collectd.
  16
  17 Access the collected data:
  18 --------------------------
  19
  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.
  26
  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.
  30
  31   This script was intended to be used with version 3 of collectd but still
  32   seems to be in use by some people. To get it working with version 4, you
  33   have to call it once for each subdirectory containing RRD files. A sample
  34   wrapper might look like this:
  35
  36     for dir in /var/lib/collectd/rrd/$hostname/*; do
  37         out_dir=`basename "$dir"`
  38         mkdir -p $out_dir
  39         ( cd $out_dir && collectd2html.pl --data-dir="$dir" )
  40     done
  41
  42 - collection.cgi: Sample CGI script that creates graphs on the fly. The Perl
  43   modules "RRDs" (package librrds-perl), "URI:Escape" (package liburi-perl),
  44   "HTML::Entities" (package libhtml-parser-perl) and a CGI capable web server
  45   (e.g. apache2 or boa) are required for this script to run. Simply install
  46   the (gunzip'ed) script to a place where the webserver will treat it as a CGI
  47   script (/usr/lib/cgi-bin/ by default) and visit that page in a browser
  48   (http://localhost/cgi-bin/collection.cgi by default). Please refer to your
  49   webserver's documentation for more details.
  50
  51   Starting with version 4, collection.cgi requires a small config file, which
  52   is installed to /etc/collectd/collection.conf. You should not need to change
  53   anything there.
  54
  55 - collection3: A graphing front-end for the RRD files created by and filled
  56   with collectd. See /usr/share/doc/collectd/examples/collection3/README for
  57   details. This is a successor for collection.cgi.
  58
  59 Building your own plugins:
  60 --------------------------
  61
  62 - Originally, plugins for collectd had to be written in C and linked as shared
  63   objects. Starting with version 4.0.0, it is also possible to use plugins
  64   written in the scripting language Perl or implemented as separate processes.
  65   See collectd-perl(5) and collectd-exec(5) for details.
  66
  67 - If you want to contribute plugins to the official distribution you should
  68   read http://collectd.org/dev-info.shtml.
  69
  70 - If you want to build C plugins for your personal use only simply install the
  71   collectd-dev package and use /usr/share/doc/collectd-dev/examples/myplugin.c
  72   as a starting point (Note: This is already a working example, though it does
  73   not collect any useful data).
  74
  75   The resulting file can be compiled as follows:
  76
  77     gcc -DHAVE_CONFIG_H -shared -fPIC -o myplugin.so myplugin.c
  78
  79   Copy myplugin.so to /usr/lib/collectd and add the following line to your
  80   collectd config file:
  81
  82     LoadPlugin myplugin
  83
  84   Restart collectd and you're done.
  85
  86 - The collectd-dev package also provides an example Perl plugin that can be
  87   used as a starting point for your own development. It can be found in
  88   /usr/share/doc/collectd-dev/examples/MyPlugin.pm (Note: This is already a
  89   working example, though it does not collect any useful data).
  90
  91   To enable the plugin, copy it to a place where Perl can find it (i.e. a
  92   subdirectory named "Collectd/Plugin" of a directory listed in @INC) and add
  93   the following line to the perl plugin section in your config file:
  94
  95     LoadPlugin "Collectd::Plugin::MyPlugin"
  96
  97   or
  98
  99     BaseName "Collectd::Plugin"
 100     LoadPlugin MyPlugin
 101
 102   Restart collectd and you're done.
 103
 104 Examples:
 105 ---------
 106
 107 - SpamAssassin/: This directory contains a SpamAssassin plugin which passes
 108   statistics to collectd using the email plugin. See the embedded POD
 109   documentation for information about setup and configuration: perldoc
 110   Collectd.pm.
 111
 112 - iptables/: This directory contains a script which will setup iptables to do
 113   global logging of all traffic going in and out of an interface. This
 114   information can then be collected by collectd's iptables plugin.
 115
 116 - collectd-network.py: Python module implementing the collectd network
 117   protocol in pure Python. It currently supports to receive data and
 118   notifications from collectd.
 119
 120 - cussh.pl: "Collectd Unix Socket SHell" is a small, interactive front-end for
 121   the unixsock plugin. See the embedded POD documentation for details: perldoc
 122   cussh.pl.
 123
 124 - exec-munin.px: Script to be used with the exec-plugin (see collectd-exec(5)
 125   for details) which executes munin plugins, parses the output and translates
 126   it to a format the exec-plugin understands. The features are limited -
 127   changing the munin plugins to use the output format understood by the
 128   exec-plugin is recommended. See the embedded POD documentation for more
 129   details: perldoc exec-munin.px.
 130
 131 - exec-smartctl: Sample script for the exec plugin. Please refer to the
 132   documentation in the file - you will have to adapt it to your needs anyway.
 133
 134 - network-proxy.py: A simple unicast proxy for collectd traffic.
 135
 136 - snmp-data.conf: Sample configuration for the SNMP plugin. This config
 137   includes a few standard <Data ..> definitions that you can include in your
 138   own config using the `Include' statement (available since version 4.2.0).
 139   The config includes some data that is defined in the IF-MIB, e. g. octet or
 140   packet counters, UPS-MIB and whatever people have send in. If you have some
 141   more definitions please send them in, so others can profit from it.
 142
 143 - snmp-probe-host.px: Script to be used to automatically generate SNMP
 144   configuration snippets for the "snmp" plugin. See the embedded POD
 145   documentation for more details: perldoc snmp-probe-host.px.
 146
 147 Additional helper scripts:
 148 --------------------------
 149
 150 - add_rra.sh: Before version 3.9.0 collectd used to create a different set of
 151   RRAs. The most detailed of these old RRAs had a one minute resolution. This
 152   script can be used to add three more RRAs: minimum, maximum and average with
 153   a ten second resolution and 2200 rows (~6 hours). This will make hourly
 154   statistics much more interesting. Please note that no sanity-checking
 155   whatsoever is performed. You can seriously screw up your RRD files if you
 156   don't know what you're doing.
 157