src/collectd-snmp.pod

   1 =head1 NAME
   2
   3 collectd-snmp - Documentation of collectd's C<snmp plugin>
   4
   5 =head1 SYNOPSIS
   6
   7   LoadPlugin snmp
   8   # ...
   9   <Plugin snmp>
  10     <Data "powerplus_voltge_input">
  11       Type "voltage"
  12       Table false
  13       Instance "input_line1"
  14       Values "SNMPv2-SMI::enterprises.6050.5.4.1.1.2.1"
  15     </Data>
  16     <Data "hr_users">
  17       Type "users"
  18       Table false
  19       Instance ""
  20       Values "HOST-RESOURCES-MIB::hrSystemNumUsers.0"
  21     </Data>
  22     <Data "std_traffic">
  23       Type "if_octets"
  24       Table true
  25       Instance "IF-MIB::ifDescr"
  26       Values "IF-MIB::ifInOctets" "IF-MIB::ifOutOctets"
  27     </Data>
  28
  29     <Host "some.switch.mydomain.org">
  30       Address "192.168.0.2"
  31       Version 1
  32       Community "community_string"
  33       Collect "std_traffic"
  34       Interval 120
  35     </Host>
  36     <Host "some.server.mydomain.org">
  37       Address "192.168.0.42"
  38       Version 2
  39       Community "another_string"
  40       Collect "std_traffic" "hr_users"
  41     </Host>
  42     <Host "some.ups.mydomain.org">
  43       Address "192.168.0.3"
  44       Version 1
  45       Community "more_communities"
  46       Collect "powerplus_voltge_input"
  47       Interval 300
  48     </Host>
  49   </Plugin>
  50
  51 =head1 DESCRIPTION
  52
  53 The C<snmp plugin> queries other hosts using SNMP, the simple network
  54 management protocol, and translates the value it receives to collectd's
  55 internal format and dispatches them. Depending on the write plugins you have
  56 loaded they may be written to disk or submitted to another instance or
  57 whatever you configured.
  58
  59 Because querying a host via SNMP may produce a timeout multiple threads are
  60 used to query hosts in parallel. Depending on the number of hosts between one
  61 and ten threads are used.
  62
  63 =head1 CONFIGURATION
  64
  65 Since the aim of the C<snmp plugin> is to provide a generic interface to SNMP,
  66 it's configuration is not trivial and may take some time.
  67
  68 Since the C<Net-SNMP> library is used you can use all the environment variables
  69 that are interpreted by that package. See L<snmpcmd(1)> for more details.
  70
  71 There are two types of blocks that can be contained in the
  72 C<E<lt>PluginE<nbsp>snmpE<gt>> block: B<Data> and B<Host>:
  73
  74 =head2 The B<Data> block
  75
  76 The B<Data> block defines a list of values or a table of values that are to be
  77 queried. The following options can be set:
  78
  79 =over 4
  80
  81 =item B<Type> I<type>
  82
  83 collectd's type that is to be used, e.E<nbsp>g. "if_octets" for interface
  84 traffic or "users" for a user count. The types are read from the B<TypesDB>
  85 (see L<collectd.conf(5)>), so you may want to check for which types are
  86 defined.
  87
  88 =item B<Table> I<true|false>
  89
  90 Define if this is a single list of values or a table of values. The difference
  91 is the following:
  92
  93 When B<Table> is set to B<false>, the OIDs given to B<Values> (see below) are
  94 queried using the C<GET> SNMP command (see L<snmpget(1)>) and transmitted to
  95 collectd. B<One> value list is dispatched and, eventually, one file will be
  96 written.
  97
  98 When B<Table> is set to B<true>, the OIDs given to B<Values> (see below) are
  99 queried using the C<GETNEXT> SNMP command until the subtree is left. After all
 100 the lists (think: all columns of the table) have been read B<several> values
 101 sets will be dispatches and, eventually, several files will be written. If you
 102 configure a B<Type> (see above) which needs more than one data source (for
 103 example C<if_octets> which needs C<rx> and C<tx>) you will need to specify more
 104 than one (two, in the example case) OIDs with the B<Values> option. This has
 105 nothing to do with the B<Table> setting.
 106
 107 For example, if you want to query the number of users on a system, you can use
 108 C<HOST-RESOURCES-MIB::hrSystemNumUsers.0>. This is one value and belongs to one
 109 value list, therefore B<Table> must be set to B<false>. Please note that, in
 110 this case, you have to include the sequence number (zero in this case) in the
 111 OID.
 112
 113 Counter example: If you want to query the interface table provided by the
 114 C<IF-MIB>, e.E<nbsp>g. the bytes transmitted. There are potentially many
 115 interfaces, so you will want to set B<Table> to B<true>. Because the
 116 C<if_octets> type needs two values, received and transmitted bytes, you need to
 117 specify two OIDs in the B<Values> setting, in this case likely
 118 C<IF-MIB::ifHCInOctets> and C<IF-MIB::ifHCOutOctets>. But, this is because of
 119 the B<Type> setting, not the B<Table> setting.
 120
 121 Since the semantic of B<Instance> and B<Values> depends on this setting you
 122 need to set it before setting them. Doing vice verse will result in undefined
 123 behavior.
 124
 125 =item B<Instance> I<Instance>
 126
 127 Sets the type-instance of the values that are dispatched. The meaning of this
 128 setting depends on whether B<Table> is set to I<true> or I<false>:
 129
 130 If B<Table> is set to I<true>, I<Instance> is interpreted as an SNMP-prefix
 131 that will return a list of strings. Those strings are then used as the actual
 132 type-instance. An example would be the C<IF-MIB::ifDescr> subtree.
 133 L<variables(5)> from the SNMP distribution describes the format of OIDs.
 134
 135 If B<Table> is set to I<false> the actual string configured for I<Instance> is
 136 copied into the value-list. In this case I<Instance> may be empty, i.E<nbsp>e.
 137 "".
 138
 139 =item B<Values> I<OID> [I<OID> ...]
 140
 141 Configures the values to be queried from the SNMP host. The meaning slightly
 142 changes with the B<Table> setting. L<variables(5)> from the SNMP distribution
 143 describes the format of OIDs.
 144
 145 If B<Table> is set to I<true>, each I<OID> must be the prefix of all the
 146 values to query, e.E<nbsp>g. C<IF-MIB::ifInOctets> for all the counters of
 147 incoming traffic. This subtree is walked (using C<GETNEXT>) until a value from
 148 outside the subtree is returned.
 149
 150 If B<Table> is set to I<false>, each I<OID> must be the OID of exactly one
 151 value, e.E<nbsp>g. C<IF-MIB::ifInOctets.3> for the third counter of incoming
 152 traffic.
 153
 154 =back
 155
 156 =head2 The Host block
 157
 158 The B<Host> block defines which hosts to query, which SNMP community and
 159 version to use and which of the defined B<Data> to query.
 160
 161 The argument passed to the B<Host> block is used as the hostname in the data
 162 stored by collectd.
 163
 164 =over 4
 165
 166 =item B<Address> I<IP-Address>|I<Hostname>
 167
 168 Set the address to connect to.
 169
 170 =item B<Version> B<1>|B<2>
 171
 172 Set the SNMP version to use. When giving B<2> version C<2c> is actually used.
 173 Version 3 is not supported by this plugin.
 174
 175 =item B<Community> I<Community>
 176
 177 Pass I<Community> to the host.
 178
 179 =item B<Collect> I<Data> [I<Data> ...]
 180
 181 Defines which values to collect. I<Data> refers to one of the B<Data> block
 182 above. Since the config file is read top-down you need to define the data
 183 before using it here.
 184
 185 =item B<Interval> I<Seconds>
 186
 187 Collect data from this host every I<Seconds> seconds. This value needs to be a
 188 multiple of the global B<Interval> setting and, if it is not, will be rounded
 189 B<down> to one and a warning is logged in this case. So if your global
 190 B<Interval> is set to I<10> and you configure I<25> here, it's rounded down to
 191 I<20>. By default the global B<Interval> setting will be used.
 192
 193 This option is meant for devices with not much CPU power, e.E<nbsp>g. network
 194 equipment such as switches, embedded devices, rack monitoring systems and so
 195 on. Since the B<Step> of generated RRD files depends on this setting it's
 196 wise to select a reasonable value once and never change it.
 197
 198 =back
 199
 200 =head1 SEE ALSO
 201
 202 L<collectd(1)>,
 203 L<collectd.conf(5)>,
 204 L<snmpget(1)>,
 205 L<snmpgetnext(1)>,
 206 L<variables(5)>,
 207 L<unix(7)>
 208
 209 =head1 AUTHOR
 210
 211 Florian Forster E<lt>octo@verplant.orgE<gt>
 212
 213 =cut