You can find the answers to these questions on the FAQ page.
  • It doesn't work. Where can I find diagnostic output?
    Version 3.* writes warnings and error messages using the syslog(3) facility. Depending on your system the syslog-daemon writes these messages to files and/or sends them to another host. On most GNU/Linux distributions the place to look at is either /var/log/syslog or /var/log/messages.
    Version 4.0 and later comes with the logfile and syslog plugins which can be used to write status messages to a file or send it to the syslog daemon.
  • Some lines of the config seem to be ignored..?
    Yes, that's a known bug. You probably have one or more white spaces at the end of the lines being ignored.
    This is a bug in the library used by collectd 3.* to parse the configfile. Versions 4.0 and later use a different library and don't have this problem.
  • Can I adjust the interval in which data is collected?
    Yes, since version 3.9.0 this can be set at compiletime. Keep in mind, though, that this will change the layout of the generated RRD-files. Also, clients and servers should have the same setting here to avoid interesting results.
    Version 4.0 allows this setting to be adjusted in the configfile.
  • I try to use the ping-plugin, but keep getting the message "`ping_host_add' failed.". What's the matter?
    In order to generate ICMP packets one needs to open a so called "RAW socket". On most UNIX systems only the superuser (root) may open such sockets.
    In addition, some virtualization environments, such as VServer and Solaris Zones have been reported to cause some trouble.
  • Who receives the multicast traffic?
    I don't know. That entirely depends on your network setup. By default collectd uses "site local" addresses, that should not be routed to outside your AS. If that's really the case is up to you.
  • What does "Invalid value for config option `Mode': `Local'" mean?
    Is means that the mode "Local" is not available. Most likely the "librrd" library wasn't found. If you want to write to RRD-files install "librrd" or, if you already did that, use the --with-rrdtool option of the ./configure-script to point to the right direction.
  • How to I use --with-rrdtool?
    If you installed libraries in a non-standard (or non-system) path you need to specify them when running the configure script. Otherwise it will not find them and build the binaries without linking against the library.
    You need to set the PATH as given to the --prefix option when compiling the library. The script actually looks for the two subdirectories PATH/include and PATH/lib, so check for their existence if things don't work. If, for example, you installed RRDTool in /opt/rrdtool-x.y.z you need to run configure like this:
    $ ./configure --with-rrdtool=/opt/rrdtool-x.y.z
  • The apache-plugin reports the following error: apache: curl_easy_perform failed: Failed writing body. What's wrong?
    The response received was too big and didn't fit into the buffer. Check the URL-option in the configfile. Especially check that the URL ends in "?auto": collectd requires the machine readable output generated by the Apache-plugin mod_status and will not work with anything else.
  • What do the version numbers mean?
    The version numbers consist of three numbers: The major- and minor-number and the patchlevel.
    • Versions with different major-numbers are basically not compatible. This means that the definitions of RRD-files or config-options have been changed or, in general, that the user has to do something in addition to install the new version. This is not nice and avoided when possible, but sometimes necessary to prevent old mistakes to become ancient mistakes. We try to provide migration scripts, though, to make a switch as easy as possible. See the v3 to v4 migration guide for details.
    • Versions with differing minor-numbers are backwards compatible, i. e. you can replace the lower version with the higher one and everything should still work. This means that features are added, but not removed or changed and that the default behavior does not change.
    • Versions with different patchlevels are both, forward- and backwards-compatible, because no new features have been introduced. The only difference between the two versions is one or more bugfixes, so you should generally install the higher version of the two.
  • I enabled the foo plugin using --enable-foo but now the build process fails. What's wrong?
    Since version 4.0.0 a server process doesn't need to load the plugins from which data should be received - in contrast to versions 3.*. This means, that plugins with unmet dependencies no longer have any purpose. So, we moved dependency checking into the configure script, starting with version 4.1.0. I. e. the configure script now automatically disables all plugins with unmet dependencies and enables all plugins whose dependencies are met.
    So, if a plugin is displayed as disabled, it's dependencies are not met. The normal way to get a plugin compiled is to install the missing dependencies and re-run the configure script.
    You can force it to be build using --enable-foo, but you need to know exactly what you are doing. If you do this you're out in the dark, cold woods and totally on your own!
  • The build process fails with "relocation R_X86_64_32 against `a local symbol' can not be used when making a shared object; recompile with -fPIC". What's wrong?
    Many plugins have to be linked against libraries. A few of them (currently iptables, netlink and nut are known to be affected) link against libraries that are only available as "static libraries" in many distributions. Most distributions (e. g. Debian and SuSE GNU/Linux) do not compile static libraries with the "-fPIC" option. Thus they cannot be linked with shared objects compiled with "-fPIC". Some architectures (among them i386) do not seem to care about that and handle it in some (probably magic) way. However, other architectures (mostly 64bit like amd64 or hppa) cannot handle that and thus the compiler aborts with the error message mentioned above.
    To fix this issue, you need a version of the static library compiled with "-fPIC" (or a shared library). Ask your distributor to provide a suitable version of the library or compile it yourself.
    For more detailed information please refer to:
  • Solaris support is broken! The build aborts! Help!
    There are two known issues with Solaris, but both can be fixed relatively easy:
    If you build a 32bit binary, the configure script will (try to) enable LFS. This will result in an error which looks somehow like this:
    config.h:832:1: error: "_FILE_OFFSET_BITS" redefined
    Also, the swap-plugin has some problems of it's own with this:
    swap.c:197: warning: implicit declaration of function 'swapctl'
    swap.c:197: error: 'SC_AINFO' undeclared (first use in this function)
    The solution is to build a 64bit binary! If you build a 64bit binary LFS is not needed and the swap plugin works as intended. To do this, pass the -m64 flag to the compiler (assuming you're using the Sun C compiler.
    Another problem is that by default Sun defines a version of getgrnam_r that isn't POSIX-compatible. To enable POSIX-compatibility pass the _POSIX_PTHREAD_SEMANTICS define to the compiler.
    Putting all together you need to pass the following flags to the configure-script:
    # Sun CC
    $ ./configure CFLAGS="-m64 -mt -D_POSIX_PTHREAD_SEMANTICS"
    Please note that we only test the Sun C compiler ourselves, but GCC may work, too. When using the GCC you need to substitute the -mt flag with the -pthreads flag. So if you use GCC the above invokation of ./configure becomes:
    # GCC
    $ ./configure CFLAGS="-m64 -pthreads -D_POSIX_PTHREAD_SEMANTICS"
    Thanks to Christophe Kalt for sharing his insights :)
  • Why is the CPU usage split up in so many files? Can I change that?
    The short answer is: That is because otherwise backwards compatibility would be impossible and you would have to re-create your files from scratch regularly. And, "no".
    The long answer and explanation of the short answer is: collectd runs on a variety of operating systems. Each operating system has it's own method for accounting CPU states, memory consumption, swap usage, and so on. If all these data sources where in one data set, every new supported operating system or any addition to an already supported operating system would mean that we need to modify the data set. This cannot be done without breaking backwards compatibility.
    To give you a few examples: Sometime in mid-2.6 the Linux kernel added some Xen-patches which provided a new CPU state: "steal time". When adding support for BSD systems we had to add "wired" memory. NFSv4 added some new procedures that NFSv3 didn't have, etc pp.
    That interface traffic has two data sources is different, because every operating system will account received and transmitted bytes. Likewise for the system load: The 1, 5, and 15 minute averages have been like that for ages and it's very unlikely that any weird UNIX does this different.
    Changing the layout of the data is not just a matter of changing the types.db file. That file describes the layout of the data submitted by plugins. The plugins don't need it - they know what data they submit. It's needed by the daemon and writing plugin to know how to store the data. If you mess with the file without knowing what you do, you will most likely end up with the data not being collected at all anymore.
  • Why doesn't collection.cgi draw foo graphs correctly?
    That script is meant as a starting point for own developments, not as a ready to use web frontend for RRD files written by collectd.
    It is just an example, because it's not really usable as it is. And it's not really useable, because we are UNIX developers and don't enjoy doing web stuff much. Working on the daemon is just so much more fun.. ;) So in the best of free / open source traditions: Patches welcome!
    There are alternatives, though. We've heard from various people using Cacti to render the graphs. Sergiusz Pawlowicz of the BBC has written CollectGraph, a macro for the MoinMoin wiki. And of course there's drraw.

Manpage collectd-snmp(5)

NAME

collectd-snmp - Documentation of collectd's snmp plugin

SYNOPSIS

  LoadPlugin snmp
  # ...
  <Plugin snmp>
    <Data "powerplus_voltge_input">
      Type "voltage"
      Table false
      Instance "input_line1"
      Scale 0.1
      Values "SNMPv2-SMI::enterprises.6050.5.4.1.1.2.1"
    </Data>
    <Data "hr_users">
      Type "users"
      Table false
      Instance ""
      Shift -1
      Values "HOST-RESOURCES-MIB::hrSystemNumUsers.0"
    </Data>
    <Data "std_traffic">
      Type "if_octets"
      Table true
      Instance "IF-MIB::ifDescr"
      Values "IF-MIB::ifInOctets" "IF-MIB::ifOutOctets"
    </Data>
    <Host "some.switch.mydomain.org">
      Address "192.168.0.2"
      Version 1
      Community "community_string"
      Collect "std_traffic"
      Interval 120
    </Host>
    <Host "some.server.mydomain.org">
      Address "192.168.0.42"
      Version 2
      Community "another_string"
      Collect "std_traffic" "hr_users"
    </Host>
    <Host "some.ups.mydomain.org">
      Address "192.168.0.3"
      Version 1
      Community "more_communities"
      Collect "powerplus_voltge_input"
      Interval 300
    </Host>
  </Plugin>

DESCRIPTION

The snmp plugin queries other hosts using SNMP, the simple network management protocol, and translates the value it receives to collectd's internal format and dispatches them. Depending on the write plugins you have loaded they may be written to disk or submitted to another instance or whatever you configured.

Because querying a host via SNMP may produce a timeout multiple threads are used to query hosts in parallel. Depending on the number of hosts between one and ten threads are used.

CONFIGURATION

Since the aim of the snmp plugin is to provide a generic interface to SNMP, it's configuration is not trivial and may take some time.

Since the Net-SNMP library is used you can use all the environment variables that are interpreted by that package. See snmpcmd(1) for more details.

There are two types of blocks that can be contained in the <Pluginsnmp> block: Data and Host:

The Data block

The Data block defines a list of values or a table of values that are to be queried. The following options can be set:

Type type

collectd's type that is to be used, e. g. ``if_octets'' for interface traffic or ``users'' for a user count. The types are read from the TypesDB (see collectd.conf(5)), so you may want to check for which types are defined. See types.db(5) for a description of the format of this file.

Table true|false

Define if this is a single list of values or a table of values. The difference is the following:

When Table is set to false, the OIDs given to Values (see below) are queried using the GET SNMP command (see snmpget(1)) and transmitted to collectd. One value list is dispatched and, eventually, one file will be written.

When Table is set to true, the OIDs given to Values (see below) are queried using the GETNEXT SNMP command until the subtree is left. After all the lists (think: all columns of the table) have been read several values sets will be dispatches and, eventually, several files will be written. If you configure a Type (see above) which needs more than one data source (for example if_octets which needs rx and tx) you will need to specify more than one (two, in the example case) OIDs with the Values option. This has nothing to do with the Table setting.

For example, if you want to query the number of users on a system, you can use HOST-RESOURCES-MIB::hrSystemNumUsers.0. This is one value and belongs to one value list, therefore Table must be set to false. Please note that, in this case, you have to include the sequence number (zero in this case) in the OID.

Counter example: If you want to query the interface table provided by the IF-MIB, e. g. the bytes transmitted. There are potentially many interfaces, so you will want to set Table to true. Because the if_octets type needs two values, received and transmitted bytes, you need to specify two OIDs in the Values setting, in this case likely IF-MIB::ifHCInOctets and IF-MIB::ifHCOutOctets. But, this is because of the Type setting, not the Table setting.

Since the semantic of Instance and Values depends on this setting you need to set it before setting them. Doing vice verse will result in undefined behavior.

Instance Instance

Sets the type-instance of the values that are dispatched. The meaning of this setting depends on whether Table is set to true or false:

If Table is set to true, Instance is interpreted as an SNMP-prefix that will return a list of values. Those values are then used as the actual type-instance. An example would be the IF-MIB::ifDescr subtree. variables(5) from the SNMP distribution describes the format of OIDs.

If Table is set to true and Instance is omitted, then ``SUBID'' will be used as the instance.

If Table is set to false the actual string configured for Instance is copied into the value-list. In this case Instance may be empty, i. e. ``''.

InstancePrefix String

If Table is set to true, you may feel the need to add something to the instance of the files. If set, String is prepended to the instance as determined by querying the agent. When Table is set to false this option has no effect.

The UPS-MIB is an example where you need this setting: It has voltages of the inlets, outlets and the battery of an UPS. However, it doesn't provide a descriptive column for these voltages. In this case having 1, 2, ... as instances is not enough, because the inlet voltages and outlet voltages may both have the subids 1, 2, ... You can use this setting to distinguish between the different voltages.

Values OID [OID ...]

Configures the values to be queried from the SNMP host. The meaning slightly changes with the Table setting. variables(5) from the SNMP distribution describes the format of OIDs.

If Table is set to true, each OID must be the prefix of all the values to query, e. g. IF-MIB::ifInOctets for all the counters of incoming traffic. This subtree is walked (using GETNEXT) until a value from outside the subtree is returned.

If Table is set to false, each OID must be the OID of exactly one value, e. g. IF-MIB::ifInOctets.3 for the third counter of incoming traffic.

Scale Value

The gauge-values returned by the SNMP-agent are multiplied by Value. This is useful when values are transfered as a fixed point real number. For example, thermometers may transfer 243 but actually mean 24.3, so you can specify a scale value of 0.1 to correct this. The default value is of course 1.0.

This value is not applied to counter-values.

Shift Value

Value is added to gauge-values returned by the SNMP-agent after they have been multiplied by any Scale value. If, for example, a thermometer returns degrees Kelvin you could specify a shift of 273.15 here to store values in degrees Celsius. The default value is is course 0.0.

This value is not applied to counter-values.

The Host block

The Host block defines which hosts to query, which SNMP community and version to use and which of the defined Data to query.

The argument passed to the Host block is used as the hostname in the data stored by collectd.

Address IP-Address|Hostname

Set the address to connect to.

Version 1|2

Set the SNMP version to use. When giving 2 version 2c is actually used. Version 3 is not supported by this plugin.

Community Community

Pass Community to the host.

Collect Data [Data ...]

Defines which values to collect. Data refers to one of the Data block above. Since the config file is read top-down you need to define the data before using it here.

Interval Seconds

Collect data from this host every Seconds seconds. This value needs to be a multiple of the global Interval setting and, if it is not, will be rounded down to one and a warning is logged in this case. So if your global Interval is set to 10 and you configure 25 here, it's rounded down to 20. By default the global Interval setting will be used.

This option is meant for devices with not much CPU power, e. g. network equipment such as switches, embedded devices, rack monitoring systems and so on. Since the Step of generated RRD files depends on this setting it's wise to select a reasonable value once and never change it.

SEE ALSO

collectd(1), collectd.conf(5), snmpget(1), snmpgetnext(1), variables(5), unix(7)

AUTHOR

Florian Forster <octo@verplant.org>