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 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.
  12
  13 - The main components of collectd have been split into two packages:
  14
  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/.
  23
  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.
  28
  29 Configuring collectd:
  30 ---------------------
  31
  32 - See collectd.conf(5) for details about configuring collectd.
  33
  34 Access the collected data:
  35 --------------------------
  36
  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.
  43
  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.
  47
  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.
  56
  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.
  59
  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.
  63
  64 Cleanup of old data:
  65 --------------------
  66
  67 collectd itself does not take care of removing any data files (e.g. RRDtool)
  68 that are no longer updated (e.g., no longer existing hosts or instances).
  69 There are a couple of ways to take care of that. In any case, double-check the
  70 list of files to be removed before doing so! We do not take responsibility for
  71 any data loss or similar.
  72
  73 - Check the last modification time of all RRD files:
  74
  75     find /var/lib/collectd/rrd/ -mtime +30 -type f
  76
  77   This will list all files that have not been updated within the last 30 days.
  78   After double-checking the list of files, use a command like the following to
  79   delete old files:
  80
  81     find /var/lib/collectd/rrd/ -mtime +30 -type f | xargs rm
  82
  83   NOTE: Some versions of RRDtool did not update mtime when writing to a file.
  84         This has been fixed in version 1.3.5 of RRDtool. If your version is
  85         affected by that, this approach does not work.
  86
  87 - Check the 'last_update' header of the RRD files:
  88
  89     export IFS="
  90     "
  91     for file in $( find /var/lib/collectd/rrd/ -type f -name '*.rrd' ); do
  92         last_update=$( rrdtool info $file | grep last_update | cut -d' ' -f3 )
  93         if test -n "$last_update" \
  94                 -a $(( $( date +%s ) - $last_update )) -gt 2592000; then
  95             echo $file
  96         fi
  97     done
  98
  99   This will also list all files that have not been updated within the last 30
 100   days. It's a bit more expensive since each and every RRD file will have to
 101   be read from disk rather than checking the file-system meta-data only.
 102
 103 When doing those checks, take into account any caching times configured in the
 104 RRDtool plugin or when using RRDCacheD.
 105
 106 Building your own plugins:
 107 --------------------------
 108
 109 - Originally, plugins for collectd had to be written in C and linked as shared
 110   objects. Starting with version 4.0.0, it is also possible to use plugins
 111   written in the scripting language Perl or implemented as separate processes.
 112   In later versions, support for Java and Python has been added. See the
 113   appropriate collectd-<extension>(5) manual page for details.
 114
 115 - If you want to contribute plugins to the official distribution you should
 116   read https://collectd.org/dev-info.shtml.
 117
 118 - If you want to build C plugins for your personal use only simply install the
 119   collectd-dev package and use /usr/share/doc/collectd-dev/examples/myplugin.c
 120   as a starting point (Note: This is already a working example, though it does
 121   not collect any useful data).
 122
 123   The resulting file can be compiled as follows:
 124
 125     gcc -DHAVE_CONFIG_H -shared -fPIC -o myplugin.so myplugin.c
 126
 127   Copy myplugin.so to /usr/lib/collectd and add the following line to your
 128   collectd config file:
 129
 130     LoadPlugin myplugin
 131
 132   Restart collectd and you're done.
 133
 134 - The collectd-dev package also provides an example Perl plugin that can be
 135   used as a starting point for your own development. It can be found in
 136   /usr/share/doc/collectd-dev/examples/MyPlugin.pm (Note: This is already a
 137   working example, though it does not collect any useful data).
 138
 139   To enable the plugin, copy it to a place where Perl can find it (i.e. a
 140   subdirectory named "Collectd/Plugin" of a directory listed in @INC) and add
 141   the following line to the perl plugin section in your config file:
 142
 143     LoadPlugin "Collectd::Plugin::MyPlugin"
 144
 145   or
 146
 147     BaseName "Collectd::Plugin"
 148     LoadPlugin MyPlugin
 149
 150   Restart collectd and you're done.
 151
 152 Examples:
 153 ---------
 154
 155 - SpamAssassin/: This directory contains a SpamAssassin plugin which passes
 156   statistics to collectd using the email plugin. See the embedded POD
 157   documentation for information about setup and configuration: perldoc
 158   Collectd.pm.
 159
 160 - iptables/: This directory contains a script which will setup iptables to do
 161   global logging of all traffic going in and out of an interface. This
 162   information can then be collected by collectd's iptables plugin.
 163
 164 - collectd-network.py: Python module implementing the collectd network
 165   protocol in pure Python. It currently supports to receive data and
 166   notifications from collectd.
 167
 168 - collectd-unixsock.py: Python module providing an interface to collect's
 169   unixsock plugin.
 170
 171 - cussh.pl: "Collectd Unix Socket SHell" is a small, interactive front-end for
 172   the unixsock plugin. See the embedded POD documentation for details: perldoc
 173   cussh.pl.
 174
 175 - exec-munin.px: Script to be used with the exec-plugin (see collectd-exec(5)
 176   for details) which executes munin plugins, parses the output and translates
 177   it to a format the exec-plugin understands. The features are limited -
 178   changing the munin plugins to use the output format understood by the
 179   exec-plugin is recommended. See the embedded POD documentation for more
 180   details: perldoc exec-munin.px.
 181
 182 - exec-smartctl: Sample script for the exec plugin. Please refer to the
 183   documentation in the file - you will have to adapt it to your needs anyway.
 184
 185 - network-proxy.py: A simple unicast proxy for collectd traffic.
 186
 187 - snmp-data.conf: Sample configuration for the SNMP plugin. This config
 188   includes a few standard <Data ..> definitions that you can include in your
 189   own config using the `Include' statement (available since version 4.2.0).
 190   The config includes some data that is defined in the IF-MIB, e. g. octet or
 191   packet counters, UPS-MIB and whatever people have send in. If you have some
 192   more definitions please send them in, so others can profit from it.
 193
 194 - snmp-probe-host.px: Script to be used to automatically generate SNMP
 195   configuration snippets for the "snmp" plugin. See the embedded POD
 196   documentation for more details: perldoc snmp-probe-host.px.
 197
 198 Additional helper scripts:
 199 --------------------------
 200
 201 - add_rra.sh: Before version 3.9.0 collectd used to create a different set of
 202   RRAs. The most detailed of these old RRAs had a one minute resolution. This
 203   script can be used to add three more RRAs: minimum, maximum and average with
 204   a ten second resolution and 2200 rows (~6 hours). This will make hourly
 205   statistics much more interesting. Please note that no sanity-checking
 206   whatsoever is performed. You can seriously screw up your RRD files if you
 207   don't know what you're doing.
 208