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       Inverval 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 cann use all the environment
  69 variables that are interpreted by that package. See L<snmpcmd(1)> for more
  70 details.
  71
  72 There are two types of blocks that can be contained in the
  73 C<E<lt>PluginE<nbsp>snmpE<gt>> block: B<Data> and B<Host>:
  74
  75 =head2 The B<Data> block
  76
  77 The B<Data> block defines a list of values or a table of values that are to be
  78 queried. The following options can be set:
  79
  80 =over 4
  81
  82 =item B<Type> I<type>
  83
  84 collectd's type that is to be used, e.E<nbsp>g. "if_octets" for interface
  85 traffic or "users" for a user count. The types are read from the B<TypesDB>
  86 (see L<collectd.conf(5)>), so you may want to check for which types are
  87 defined.
  88
  89 =item B<Table> I<true|false>
  90
  91 Define if this is a single list of values or a table of values. The difference
  92 is the following:
  93
  94 When B<Table> is set to B<false>, the OIDs given to B<Values> (see below) are
  95 queried using the C<GET> SNMP command (see L<snmpget(1)>) and transmitted to
  96 collectd. B<One> value list is dispatched and, eventually, one file will be
  97 written.
  98
  99 When B<Table> is set to B<true>, the OIDs given to B<Values> (see below) are
 100 queried using the C<GETNEXT> SNMP command until the subtree is left. After all
 101 the lists (think: all columns of the table) have been read B<several> values
 102 sets will be dispatches and, eventually, several files will be written. If you
 103 configure a B<Type> (see above) which needs more than one data source (for
 104 example C<if_octets> which needs C<rx> and C<tx>) you will need to specify more
 105 than one (two, in the example case) OIDs with the B<Values> option. This has
 106 nothing to do with the B<Table> setting.
 107
 108 For example, if you want to query the number of users on a system, you can use
 109 C<HOST-RESOURCES-MIB::hrSystemNumUsers.0>. This is one value and belongs to one
 110 value list, therefore B<Table> must be set to B<false>. Please note that, in
 111 this case, you have to include the sequence number (zero in this case) in the
 112 OID.
 113
 114 Counter example: If you want to query the interface table provided by the
 115 C<IF-MIB>, e.E<nbsp>g. the bytes transmitted. There are potentially many
 116 interfaces, so you will want to set B<Table> to B<true>. Because the
 117 C<if_octets> type needs two values, received and transmitted bytes, you need to
 118 specify two OIDs in the B<Values> setting, in this case likely
 119 C<IF-MIB::ifHCInOctets> and C<IF-MIB::ifHCOutOctets>. But, this is because of
 120 the B<Type> setting, not the B<Table> setting.
 121
 122 Since the semantic of B<Instance> and B<Values> depends on this setting you
 123 need to set it before setting them. Doing vice verse will result in undefined
 124 behavior.
 125
 126 =item B<Instance> I<Instance>
 127
 128 Sets the type-instance of the values that are dispatched. The meaning of this
 129 setting depends on whether B<Table> is set to I<true> or I<false>:
 130
 131 If B<Table> is set to I<true>, I<Instance> is interpreted as an SNMP-prefix
 132 that will return a list of strings. Those strings are then used as the actual
 133 type-instance. An example would be the C<IF-MIB::ifDescr> subtree.
 134 L<variables(5)> from the SNMP distribution describes the format of OIDs.
 135
 136 If B<Table> is set to I<false> the actual string configured for I<Instance> is
 137 copied into the value-list. In this case I<Instance> may be empty, i.E<nbsp>e.
 138 "".
 139
 140 =item B<Values> I<OID> [I<OID> ...]
 141
 142 Configures the values to be queried from the SNMP host. The meaning slightly
 143 changes with the B<Table> setting. L<variables(5)> from the SNMP distribution
 144 describes the format of OIDs.
 145
 146 If B<Table> is set to I<true>, each I<OID> must be the prefix of all the
 147 values to query, e.E<nbsp>g. C<IF-MIB::ifInOctets> for all the counters of
 148 incoming traffic. This subtree is walked (using C<GETNEXT>) until a value from
 149 outside the subtree is returned.
 150
 151 If B<Table> is set to I<false>, each I<OID> must be the OID of exactly one
 152 value, e.E<nbsp>g. C<IF-MIB::ifInOctets.3> for the third counter of incoming
 153 traffic.
 154
 155 =back
 156
 157 =head2 The Host block
 158
 159 The B<Host> block defines which hosts to query, which SNMP community and
 160 version to use and which of the defined B<Data> to query.
 161
 162 The argument passed to the B<Host> block is used as the hostname in the data
 163 stored by collectd.
 164
 165 =over 4
 166
 167 =item B<Address> I<IP-Address>|I<Hostname>
 168
 169 Set the address to connect to.
 170
 171 =item B<Version> B<1>|B<2>
 172
 173 Set the SNMP version to use. When giving B<2> version 2c is actually used.
 174 Version 3 is not supported by this plugin.
 175
 176 =item B<Community> I<Community>
 177
 178 Pass I<Community> to the host.
 179
 180 =item B<Collect> I<Data> [I<Data> ...]
 181
 182 Defines which values to collect. I<Data> refers to one of the B<Data> block
 183 above. Since the config file is read top-down you need to define the data
 184 before using it here.
 185
 186 =item B<Interval> I<Seconds>
 187
 188 Collect data from this host every I<Seconds> seconds. This value needs to be a
 189 multiple of the global B<Interval> setting and, if it is not, will be rounded
 190 B<down> to one and a warning is logged in this case. So if your global
 191 B<Interval> is set to I<10> and you configure I<25> here, it's rounded down to
 192 I<20>. By default the global B<Interval> setting will be used.
 193
 194 This option is meant for devices with not much CPU power, e.E<nbsp>g. network
 195 equipment such as switches, embedded devices, rack monitoring systems and so
 196 on. Since the B<Step> of generated RRD files depends on this setting it's
 197 wise to select a reasonable value once and never change it.
 198
 199 =back
 200
 201 =head1 SEE ALSO
 202
 203 L<collectd(1)>,
 204 L<collectd.conf(5)>,
 205 L<snmpget(1)>,
 206 L<snmpgetnext(1)>,
 207 L<variables(5)>,
 208 L<unix(7)>
 209
 210 =head1 AUTHOR
 211
 212 Florian Forster E<lt>octo@verplant.orgE<gt>
 213
 214 =cut