snmp plugin: Rename a variable (missed during merge).
[collectd.git] / README
1  collectd - System information collection daemon
2 =================================================
3 http://collectd.org/
4
5 About
6 -----
7
8   collectd is a small daemon which collects system information periodically
9   and provides mechanisms to store and monitor the values in a variety of
10   ways.
11
12
13 Features
14 --------
15
16   * collectd is able to collect the following data:
17
18     - apache
19       Apache server utilization: Number of bytes transfered, number of
20       requests handled and detailed scoreboard statistics
21
22     - apcups
23       APC UPS Daemon: UPS charge, load, input/output/battery voltage, etc.
24
25     - apple_sensors
26       Sensors in Macs running Mac OS X / Darwin: Temperature, fanspeed and
27       voltage sensors.
28
29     - ascent
30       Statistics about Ascent, a free server for the game `World of Warcraft'.
31
32     - battery
33       Batterycharge, -current and voltage of ACPI and PMU based laptop
34       batteries.
35
36     - bind
37       Name server and resolver statistics from the `statistics-channel'
38       interface of BIND 9.5, 9,6 and later.
39
40     - conntrack
41       Number of nf_conntrack entries.
42
43     - cpu
44       CPU utilization: Time spent in the system, user, nice, idle, and related
45       states.
46
47     - cpufreq
48       CPU frequency (For laptops with speed step or a similar technology)
49
50     - curl
51       Parse statistics from websites using regular expressions.
52
53     - curl_json
54       Retrieves JSON data via cURL and parses it according to user
55       configuration.
56
57     - dbi
58       Executes SQL statements on various databases and interprets the returned
59       data.
60
61     - df
62       Mountpoint usage (Basically the values `df(1)' delivers)
63
64     - disk
65       Disk utilization: Sectors read/written, number of read/write actions,
66       average time an IO-operation took to complete.
67
68     - dns
69       DNS traffic: Query types, response codes, opcodes and traffic/octets
70       transfered.
71
72     - email
73       Email statistics: Count, traffic, spam scores and checks.
74       See collectd-email(5).
75
76     - entropy
77       Amount of entropy available to the system.
78
79     - exec
80       Values gathered by a custom program or script.
81       See collectd-exec(5).
82
83     - filecount
84       Count the number of files in directories.
85
86     - fscache
87       Linux file-system based caching framework statistics.
88
89     - gmond
90       Receive multicast traffic from Ganglia instances.
91
92     - hddtemp
93       Harddisk temperatures using hddtempd.
94
95     - interface
96       Interface traffic: Number of octets, packets and errors for each
97       interface.
98
99     - iptables
100       Iptables' counters: Number of bytes that were matched by a certain
101       iptables rule.
102
103     - ipmi
104       IPMI (Intelligent Platform Management Interface) sensors information.
105
106     - ipvs
107       IPVS connection statistics (number of connections, octets and packets
108       for each service and destination).
109       See http://www.linuxvirtualserver.org/software/index.html.
110
111     - irq
112       IRQ counters: Frequency in which certain interrupts occur.
113
114     - java
115       Integrates a `Java Virtual Machine' (JVM) to execute plugins in Java
116       bytecode. See “Configuring with libjvm” below.
117
118     - load
119       System load average over the last 1, 5 and 15 minutes.
120
121     - libvirt
122       CPU, disk and network I/O statistics from virtual machines.
123
124     - madwifi
125       Queries very detailed usage statistics from wireless LAN adapters and
126       interfaces that use the Atheros chipset and the MadWifi driver.
127
128     - mbmon
129       Motherboard sensors: temperature, fanspeed and voltage information,
130       using mbmon(1).
131
132     - memcachec
133       Query and parse data from a memcache daemon (memcached).
134
135     - memcached
136       Statistics of the memcached distributed caching system.
137       <http://www.danga.com/memcached/>
138
139     - memory
140       Memory utilization: Memory occupied by running processes, page cache,
141       buffer cache and free.
142
143     - multimeter
144       Information provided by serial multimeters, such as the `Metex
145       M-4650CR'.
146
147     - mysql
148       MySQL server statistics: Commands issued, handlers triggered, thread
149       usage, query cache utilization and traffic/octets sent and received.
150
151     - netlink
152       Very detailed Linux network interface and routing statistics. You can get
153       (detailed) information on interfaces, qdiscs, classes, and, if you can
154       make use of it, filters.
155
156     - network
157       Receive values that were collected by other hosts. Large setups will
158       want to collect the data on one dedicated machine, and this is the
159       plugin of choice for that.
160
161     - nfs
162       NFS Procedures: Which NFS command were called how often. Only NFSv2 and
163       NFSv3 right now.
164
165     - nginx
166       Collects statistics from `nginx' (speak: engine X), a HTTP and mail
167       server/proxy.
168
169     - ntpd
170       NTP daemon statistics: Local clock drift, offset to peers, etc.
171
172     - nut
173       Network UPS tools: UPS current, voltage, power, charge, utilisation,
174       temperature, etc. See upsd(8).
175
176     - olsrd
177       Queries routing information from the “Optimized Link State Routing”
178       daemon.
179
180     - onewire (EXPERIMENTAL!)
181       Read onewire sensors using the owcapu library of the owfs project.
182       Please read in collectd.conf(5) why this plugin is experimental.
183
184     - openvpn
185       RX and TX of each client in openvpn-status.log (status-version 2).
186       <http://openvpn.net/index.php/documentation/howto.html>
187
188     - oracle
189       Query data from an Oracle database.
190
191     - perl
192       The perl plugin implements a Perl-interpreter into collectd. You can
193       write your own plugins in Perl and return arbitrary values using this
194       API. See collectd-perl(5).
195
196     - ping
197       Network latency: Time to reach the default gateway or another given
198       host.
199
200     - postgresql
201       PostgreSQL database statistics: active server connections, transaction
202       numbers, block IO, table row manipulations.
203
204     - powerdns
205       PowerDNS name server statistics.
206
207     - processes
208       Process counts: Number of running, sleeping, zombie, ... processes.
209
210     - protocols
211       Counts various aspects of network protocols such as IP, TCP, UDP, etc.
212
213     - rrdcached
214       RRDtool caching daemon (RRDcacheD) statistics.
215
216     - sensors
217       System sensors, accessed using lm_sensors: Voltages, temperatures and
218       fan rotation speeds.
219
220     - serial
221       RX and TX of serial interfaces. Linux only; needs root privileges.
222
223     - snmp
224       Read values from SNMP (Simple Network Management Protocol) enabled
225       network devices such as switches, routers, thermometers, rack monitoring
226       servers, etc. See collectd-snmp(5).
227
228     - swap
229       Pages swapped out onto harddisk or whatever is called `swap' by the OS..
230
231     - table
232       Parse table-like structured files.
233
234     - tail
235       Follows (tails) logfiles, parses them by lines and submits matched
236       values.
237
238     - tape
239       Bytes and operations read and written on tape devices. Solaris only.
240
241     - tcpconns
242       Number of TCP connections to specific local and remote ports.
243
244     - teamspeak2
245       TeamSpeak2 server statistics.
246
247     - ted
248       Plugin to read values from `The Energy Detective' (TED).
249
250     - thermal
251       Linux ACPI thermal zone information.
252
253     - tokyotyrant
254       Reads the number of records and file size from a running Tokyo Tyrant
255       server.
256
257     - uptime
258       System uptime statistics.
259
260     - users
261       Users currently logged in.
262
263     - vmem
264       Virtual memory statistics, e. g. the number of page-ins/-outs or the
265       number of pagefaults.
266
267     - vserver
268       System resources used by Linux VServers.
269       See <http://linux-vserver.org/>.
270
271     - wireless
272       Link quality of wireless cards. Linux only.
273
274     - xmms
275       Bitrate and frequency of music played with XMMS.
276
277     - zfs_arc
278       Statistics for ZFS' “Adaptive Replacement Cache” (ARC).
279
280   * Output can be written or send to various destinations by the following
281     plugins:
282
283     - csv
284       Write to comma separated values (CSV) files. This needs lots of
285       diskspace but is extremely portable and can be analysed with almost
286       every program that can analyse anything. Even Microsoft's Excel..
287
288     - network
289       Send the data to a remote host to save the data somehow. This is useful
290       for large setups where the data should be saved by a dedicated machine.
291
292     - perl
293       Of course the values are propagated to plugins written in Perl, too, so
294       you can easily do weird stuff with the plugins we didn't dare think of
295       ;) See collectd-perl(5).
296
297     - rrdcached
298       Output to round-robin-database (RRD) files using the RRDtool caching
299       daemon (RRDcacheD) - see rrdcached(1). That daemon provides a general
300       implementation of the caching done by the `rrdtool' plugin.
301
302     - rrdtool
303       Output to round-robin-database (RRD) files using librrd. See rrdtool(1).
304       This is likely the most popular destination for such values. Since
305       updates to RRD-files are somewhat expensive this plugin can cache
306       updates to the files and write a bunch of updates at once, which lessens
307       system load a lot.
308
309     - unixsock
310       One can query the values from the unixsock plugin whenever they're
311       needed. Please read collectd-unixsock(5) for a description on how that's
312       done.
313
314     - write_http
315       Sends the values collected by collectd to a web-server using HTTP POST
316       requests. The transmitted data is either in a form understood by the
317       Exec plugin or formatted in JSON.
318
319   * Logging is, as everything in collectd, provided by plugins. The following
320     plugins keep up informed about what's going on:
321
322     - logfile
323       Writes logmessages to a file or STDOUT/STDERR.
324
325     - perl
326       Log messages are propagated to plugins written in Perl as well.
327       See collectd-perl(5).
328
329     - syslog
330       Logs to the standard UNIX logging mechanism, syslog.
331
332   * Notifications can be handled by the following plugins:
333
334     - notify_desktop
335       Send a desktop notification to a notification daemon, as defined in
336       the Desktop Notification Specification. To actually display the
337       notifications, notification-daemon is required.
338       See http://www.galago-project.org/specs/notification/.
339
340     - notify_email
341       Send an E-mail with the notification message to the configured
342       recipients.
343
344     - exec
345       Execute a program or script to handle the notification.
346       See collectd-exec(5).
347
348     - logfile
349       Writes the notification message to a file or STDOUT/STDERR.
350
351     - network
352       Send the notification to a remote host to handle it somehow.
353
354     - perl
355       Notifications are propagated to plugins written in Perl as well.
356       See collectd-perl(5).
357
358   * Value processing can be controlled using the "filter chain" infrastructure
359     and "matches" and "targets". The following plugins are available:
360
361     - match_empty_counter
362       Match counter values which are currently zero.
363
364     - match_regex
365       Match values by their identifier based on regular expressions.
366
367     - match_timediff
368       Match values with an invalid timestamp.
369
370     - match_value
371       Select values by their data sources' values.
372
373     - target_notification
374       Create and dispatch a notification.
375
376     - target_replace
377       Replace parts of an identifier using regular expressions.
378
379     - target_set
380       Set (overwrite) entire parts of an identifier.
381
382   * Miscellaneous plugins:
383
384     - uuid
385       Sets the hostname to an unique identifier. This is meant for setups
386       where each client may migrate to another physical host, possibly going
387       through one or more name changes in the process.
388
389   * Performance: Since collectd is running as a daemon it doesn't spend much
390     time starting up again and again. With the exception of the exec plugin no
391     processes are forked. Caching in output plugins, such as the rrdtool and
392     network plugins, makes sure your resources are used efficiently. Also,
393     since collectd is programmed multithreaded it benefits from hyperthreading
394     and multicore processors and makes sure that the daemon isn't idle if only
395     one plugins waits for an IO-operation to complete.
396
397   * Once set up, hardly any maintenance is necessary. Setup is kept as easy
398     as possible and the default values should be okay for most users.
399
400
401 Operation
402 ---------
403
404   * collectd's configuration file can be found at `sysconfdir'/collectd.conf.
405     Run `collectd -h' for a list of builtin defaults. See `collectd.conf(5)'
406     for a list of options and a syntax description.
407
408   * When the `csv' or `rrdtool' plugins are loaded they'll write the values to
409     files. The usual place for these files is beneath `/var/lib/collectd'.
410
411   * When using some of the plugins, collectd needs to run as user root, since
412     only root can do certain things, such as craft ICMP packages needed to ping
413     other hosts. collectd should NOT be installed setuid root since it can be
414     used to overwrite valuable files!
415
416   * Sample scripts to generate graphs reside in `contrib/' in the source
417     package or somewhere near `/usr/share/doc/collectd' in most distributions.
418     Please be aware that those script are meant as a starting point for your
419     own experiments.. Some of them require the `RRDs' Perl module.
420     (`librrds-perl' on Debian) If you have written a more sophisticated
421     solution please share it with us.
422
423   * The RRAs of the automatically created RRD files depend on the `step'
424     and `heartbeat' settings given. If change these settings you may need to
425     re-create the files, losing all data. Please be aware of that when changing
426     the values and read the rrdtool(1) manpage thoroughly.
427
428
429 collectd and chkrootkit
430 -----------------------
431
432   If you are using the `dns' plugin chkrootkit(1) will report collectd as a
433   packet sniffer ("<iface>: PACKET SNIFFER(/usr/sbin/collectd[<pid>])"). The
434   plugin captures all UDP packets on port 53 to analyze the DNS traffic. In
435   this case, collectd is a legitimate sniffer and the report should be
436   considered to be a false positive. However, you might want to check that
437   this really is collectd and not some other, illegitimate sniffer.
438
439
440 Prerequisites
441 -------------
442
443   To compile collectd from source you will need:
444
445   * Usual suspects: C compiler, linker, preprocessor, make, ...
446
447   * A POSIX-threads (pthread) implementation.
448     Since gathering some statistics is slow (network connections, slow devices,
449     etc) the collectd is parallelized. The POSIX threads interface is being
450     used and should be found in various implementations for hopefully all
451     platforms.
452
453   * CoreFoundation.framework and IOKit.framework (optional)
454     For compiling on Darwin in general and the `apple_sensors' plugin in
455     particular.
456     <http://developer.apple.com/corefoundation/>
457
458   * libclntsh (optional)
459     Used by the `oracle' plugin.
460
461   * libcurl (optional)
462     If you want to use the `apache', `ascent', `curl', `nginx', or `write_http'
463     plugin.
464     <http://curl.haxx.se/>
465
466   * libdbi (optional)
467     Used by the `dbi' plugin to connect to various databases.
468     <http://libdbi.sourceforge.net/>
469
470   * libesmtp (optional)
471     For the `notify_email' plugin.
472     <http://www.stafford.uklinux.net/libesmtp/>
473
474   * libganglia (optional)
475     Used by the `gmond' plugin to process data received from Ganglia.
476     <http://ganglia.info/>
477
478   * libgcrypt (optional)
479     Used by the `network' plugin for encryption and authentication.
480     <http://www.gnupg.org/>
481
482   * libhal (optional)
483     If present, the uuid plugin will check for UUID from HAL.
484     <http://hal.freedesktop.org/>
485
486   * libiptc (optional)
487     For querying iptables counters.
488     <http://netfilter.org/>
489
490     If not found on the system, a version shipped with this distribution can
491     be used. It requires some Linux headers in /usr/include/linux. You can
492     force the build system to use the shipped version by specifying
493       --with-libiptc=shipped
494     when running the configure script.
495
496   * libjvm (optional)
497     Library that encapsulates the `Java Virtual Machine' (JVM). This library is
498     used by the Java plugin to execute Java bytecode. See “Configuring with
499     libjvm” below.
500     <http://openjdk.java.net/> (and others)
501
502   * libmemcached (optional)
503     Used by the `memcachec' plugin to connect to a memcache daemon.
504     <http://tangent.org/552/libmemcached.html>
505
506   * libmysqlclient (optional)
507     Unsurprisingly used by the `mysql' plugin.
508     <http://dev.mysql.com/>
509
510   * libnetlink (optional)
511     Used, obviously, for the `netlink' plugin.
512     <http://www.linuxfoundation.org/en/Net:Iproute2>
513
514   * libnetsnmp (optional)
515     For the `snmp' plugin.
516     <http://www.net-snmp.org/>
517
518   * libnotify (optional)
519     For the `notify_desktop' plugin.
520     <http://www.galago-project.org/>
521
522   * liboping (optional)
523     Used by the `ping' plugin to send and receive ICMP packets.
524     <http://verplant.org/liboping/>
525
526   * libowcapi (optional)
527     Used by the `onewire' plugin to read values from onewire sensors (or the
528     owserver(1) daemon).
529     <http://www.owfs.org/>
530
531   * libpcap (optional)
532     Used to capture packets by the `dns' plugin.
533     <http://www.tcpdump.org/>
534
535   * libperl (optional)
536     Obviously used by the `perl' plugin. The library has to be compiled with
537     ithread support (introduced in Perl 5.6.0).
538     <http://www.perl.org/>
539
540   * libpq (optional)
541     The PostgreSQL C client library used by the `postgresql' plugin.
542     <http://www.postgresql.org/>
543
544   * librrd (optional)
545     Used by the `rrdtool' and `rrdcached' plugins. The latter requires RRDtool
546     client support which was added after version 1.3 of RRDtool. Versions 1.0,
547     1.2 and 1.3 are known to work with the `rrdtool' plugin.
548     <http://oss.oetiker.ch/rrdtool/>
549
550   * librt, libsocket, libkstat, libdevinfo (optional)
551     Various standard Solaris libraries which provide system functions.
552     <http://developers.sun.com/solaris/>
553
554   * libsensors (optional)
555     To read from `lm_sensors', see the `sensors' plugin.
556     <http://www.lm-sensors.org/>
557
558   * libstatgrab (optional)
559     Used by various plugins to collect statistics on systems other than Linux
560     and/or Solaris.
561     <http://www.i-scream.org/libstatgrab/>
562
563   * libtokyotyrant (optional)
564     Used by the tokyotyrant plugin.
565     <http://1978th.net/tokyotyrant/>
566
567   * libupsclient/nut (optional)
568     For the `nut' plugin which queries nut's `upsd'.
569     <http://networkupstools.org/>
570
571   * libvirt (optional)
572     Collect statistics from virtual machines.
573     <http://libvirt.org/>
574
575   * libxml2 (optional)
576     Parse XML data. This is needed for the `ascent' and `libvirt' plugins.
577     <http://xmlsoft.org/>
578
579   * libxmms (optional)
580     <http://www.xmms.org/>
581
582   * libyajl (optional)
583     Parse JSON data. This is needed for the `curl_json' plugin.
584     <http://github.com/lloyd/yajl>
585
586 Configuring / Compiling / Installing
587 ------------------------------------
588
589   To configure, build and install collectd with the default settings, run
590   `./configure && make && make install'.  For detailed, generic instructions
591   see INSTALL. For a complete list of configure options and their description,
592   run `./configure --help'.
593
594   By default, the configure script will check for all build dependencies and
595   disable all plugins whose requirements cannot be fulfilled (any other plugin
596   will be enabled). To enable a plugin, install missing dependencies (see
597   section `Prerequisites' above) and rerun `configure'. If you specify the
598   `--enable-<plugin>' configure option, the script will fail if the depen-
599   dencies for the specified plugin are not met. In that case you can force the
600   plugin to be built using the `--enable-<plugin>=force' configure option.
601   This will most likely fail though unless you're working in a very unusual
602   setup and you really know what you're doing. If you specify the
603   `--disable-<plugin>' configure option, the plugin will not be built. If you
604   specify the `--enable-all-plugins' or `--disable-all-plugins' configure
605   options, all plugins will be enabled or disabled respectively by default.
606   Explicitly enabling or disabling a plugin overwrites the default for the
607   specified plugin. These options are meant for package maintainers and should
608   not be used in everyday situations.
609
610   By default, collectd will be installed into `/opt/collectd'. You can adjust
611   this setting by specifying the `--prefix' configure option - see INSTALL for
612   details. If you pass DESTDIR=<path> to `make install', <path> will be
613   prefixed to all installation directories. This might be useful when creating
614   packages for collectd.
615
616 Configuring with libjvm
617 -----------------------
618
619   To determine the location of the required files of a Java installation is not
620   an easy task, because the locations vary with your kernel (Linux, SunOS, …)
621   and with your architecture (x86, SPARC, …) and there is no ‘java-config’
622   script we could use. Configuration of the JVM library is therefore a bit
623   tricky.
624
625   The easiest way to use the `--with-java=$JAVA_HOME' option, where
626   `$JAVA_HOME' is usually something like:
627     /usr/lib/jvm/java-1.5.0-sun-1.5.0.14
628
629   The configure script will then use find(1) to look for the following files:
630
631     - jni.h
632     - jni_md.h
633     - libjvm.so
634
635   If found, appropriate CPP-flags and LD-flags are set and the following
636   library checks succeed.
637
638   If this doesn't work for you, you have the possibility to specify CPP-flags,
639   C-flags and LD-flags for the ‘Java’ plugin by hand, using the following three
640   (environment) variables:
641
642     - JAVA_CPPFLAGS
643     - JAVA_CFLAGS
644     - JAVA_LDFLAGS
645
646   For example (shortened for demonstration purposes):
647
648     ./configure JAVA_CPPFLAGS="-I$JAVA_HOME/include -I$JAVA_HOME/include/linux"
649
650   Adding "-ljvm" to the JAVA_LDFLAGS is done automatically, you don't have to
651   do that.
652
653 Crosscompiling
654 --------------
655
656   To compile correctly collectd needs to be able to initialize static
657   variables to NAN (Not A Number). Some C libraries, especially the GNU
658   libc, have a problem with that.
659
660   Luckily, with GCC it's possible to work around that problem: One can define
661   NAN as being (0.0 / 0.0) and `isnan' as `f != f'. However, to test this
662   ``implementation'' the configure script needs to compile and run a short
663   test program. Obviously running a test program when doing a cross-
664   compilation is, well, challenging.
665
666   If you run into this problem, you can use the `--with-nan-emulation'
667   configure option to force the use of this implementation. We can't promise
668   that the compiled binary actually behaves as it should, but since NANs
669   are likely never passed to the libm you have a good chance to be lucky.
670
671   Likewise, collectd needs to know the layout of doubles in memory, in order
672   to craft uniform network packets over different architectures. For this, it
673   needs to know how to convert doubles into the memory layout used by x86. The
674   configure script tries to figure this out by compiling and running a few
675   small test programs. This is of course not possible when cross-compiling.
676   You can use the `--with-fp-layout' option to tell the configure script which
677   conversion method to assume. Valid arguments are:
678
679     * `nothing'    (12345678 -> 12345678)
680     * `endianflip' (12345678 -> 87654321)
681     * `intswap'    (12345678 -> 56781234)
682
683
684 Contact
685 -------
686
687   For questions, bug reports, development information and basically all other
688   concerns please send an email to collectd's mailing list at
689   <collectd at verplant.org>.
690
691   For live discussion and more personal contact visit us in IRC, we're in
692   channel #collectd on freenode.
693
694
695 Author
696 ------
697
698   Florian octo Forster <octo at verplant.org>,
699   Sebastian tokkee Harl <sh at tokkee.org>,
700   and many contributors (see `AUTHORS').
701
702   Please send bug reports and patches to the mailing list, see `Contact'
703   above.
704