src/collectd-snmp.pod

   1 =encoding UTF-8
   2
   3 =head1 NAME
   4
   5 collectd-snmp - Documentation of collectd's C<snmp plugin>
   6
   7 =head1 SYNOPSIS
   8
   9   LoadPlugin snmp
  10   # ...
  11   <Plugin snmp>
  12     <Data "powerplus_voltge_input">
  13       Type "voltage"
  14       Table false
  15       Instance "input_line1"
  16       Scale 0.1
  17       Values "SNMPv2-SMI::enterprises.6050.5.4.1.1.2.1"
  18     </Data>
  19     <Data "hr_users">
  20       Type "users"
  21       Table false
  22       Instance ""
  23       Shift -1
  24       Values "HOST-RESOURCES-MIB::hrSystemNumUsers.0"
  25     </Data>
  26     <Data "std_traffic">
  27       Type "if_octets"
  28       Table true
  29       Instance "IF-MIB::ifDescr"
  30       Values "IF-MIB::ifInOctets" "IF-MIB::ifOutOctets"
  31     </Data>
  32
  33     <Host "some.switch.mydomain.org">
  34       Address "192.168.0.2"
  35       Version 1
  36       Community "community_string"
  37       Collect "std_traffic"
  38       Interval 120
  39       Timeout 10
  40       Retries 1
  41     </Host>
  42     <Host "some.server.mydomain.org">
  43       Address "192.168.0.42"
  44       Version 2
  45       Community "another_string"
  46       Collect "std_traffic" "hr_users"
  47     </Host>
  48     <Host "secure.router.mydomain.org">
  49       Address "192.168.0.7:165"
  50       Version 3
  51       SecurityLevel "authPriv"
  52       Username "cosmo"
  53       AuthProtocol "SHA"
  54       AuthPassphrase "setec_astronomy"
  55       PrivacyProtocol "AES"
  56       PrivacyPassphrase "too_many_secrets"
  57       Collect "std_traffic"
  58     </Host>
  59     <Host "some.ups.mydomain.org">
  60       Address "tcp:192.168.0.3"
  61       Version 1
  62       Community "more_communities"
  63       Collect "powerplus_voltge_input"
  64       Interval 300
  65       Timeout 5
  66       Retries 5
  67     </Host>
  68   </Plugin>
  69
  70 =head1 DESCRIPTION
  71
  72 The C<snmp plugin> queries other hosts using SNMP, the simple network
  73 management protocol, and translates the value it receives to collectd's
  74 internal format and dispatches them. Depending on the write plugins you have
  75 loaded they may be written to disk or submitted to another instance or
  76 whatever you configured.
  77
  78 Because querying a host via SNMP may produce a timeout multiple threads are
  79 used to query hosts in parallel. Depending on the number of hosts between one
  80 and ten threads are used.
  81
  82 =head1 CONFIGURATION
  83
  84 Since the aim of the C<snmp plugin> is to provide a generic interface to SNMP,
  85 its configuration is not trivial and may take some time.
  86
  87 Since the C<Net-SNMP> library is used you can use all the environment variables
  88 that are interpreted by that package. See L<snmpcmd(1)> for more details.
  89
  90 There are two types of blocks that can be contained in the
  91 C<E<lt>PluginE<nbsp>snmpE<gt>> block: B<Data> and B<Host>:
  92
  93 =head2 The B<Data> block
  94
  95 The B<Data> block defines a list of values or a table of values that are to be
  96 queried. The following options can be set:
  97
  98 =over 4
  99
 100 =item B<Type> I<type>
 101
 102 collectd's type that is to be used, e.E<nbsp>g. "if_octets" for interface
 103 traffic or "users" for a user count. The types are read from the B<TypesDB>
 104 (see L<collectd.conf(5)>), so you may want to check for which types are
 105 defined. See L<types.db(5)> for a description of the format of this file.
 106
 107 =item B<Table> I<true|false>
 108
 109 Define if this is a single list of values or a table of values. The difference
 110 is the following:
 111
 112 When B<Table> is set to B<false>, the OIDs given to B<Values> (see below) are
 113 queried using the C<GET> SNMP command (see L<snmpget(1)>) and transmitted to
 114 collectd. B<One> value list is dispatched and, eventually, one file will be
 115 written.
 116
 117 When B<Table> is set to B<true>, the OIDs given to B<Values> (see below) are
 118 queried using the C<GETNEXT> SNMP command until the subtree is left. After all
 119 the lists (think: all columns of the table) have been read B<several> values
 120 sets will be dispatches and, eventually, several files will be written. If you
 121 configure a B<Type> (see above) which needs more than one data source (for
 122 example C<if_octets> which needs C<rx> and C<tx>) you will need to specify more
 123 than one (two, in the example case) OIDs with the B<Values> option. This has
 124 nothing to do with the B<Table> setting.
 125
 126 For example, if you want to query the number of users on a system, you can use
 127 C<HOST-RESOURCES-MIB::hrSystemNumUsers.0>. This is one value and belongs to one
 128 value list, therefore B<Table> must be set to B<false>. Please note that, in
 129 this case, you have to include the sequence number (zero in this case) in the
 130 OID.
 131
 132 Counter example: If you want to query the interface table provided by the
 133 C<IF-MIB>, e.E<nbsp>g. the bytes transmitted. There are potentially many
 134 interfaces, so you will want to set B<Table> to B<true>. Because the
 135 C<if_octets> type needs two values, received and transmitted bytes, you need to
 136 specify two OIDs in the B<Values> setting, in this case likely
 137 C<IF-MIB::ifHCInOctets> and C<IF-MIB::ifHCOutOctets>. But, this is because of
 138 the B<Type> setting, not the B<Table> setting.
 139
 140 Since the semantic of B<Instance> and B<Values> depends on this setting you
 141 need to set it before setting them. Doing vice verse will result in undefined
 142 behavior.
 143
 144 =item B<Instance> I<Instance>
 145
 146 Sets the type-instance of the values that are dispatched. The meaning of this
 147 setting depends on whether B<Table> is set to I<true> or I<false>:
 148
 149 If B<Table> is set to I<true>, I<Instance> is interpreted as an SNMP-prefix
 150 that will return a list of values. Those values are then used as the actual
 151 type-instance. An example would be the C<IF-MIB::ifDescr> subtree.
 152 L<variables(5)> from the SNMP distribution describes the format of OIDs.
 153
 154 If B<Table> is set to I<true> and B<Instance> is omitted, then "SUBID" will be
 155 used as the instance.
 156
 157 If B<Table> is set to I<false> the actual string configured for I<Instance> is
 158 copied into the value-list. In this case I<Instance> may be empty, i.E<nbsp>e.
 159 "".
 160
 161 =item B<InstancePrefix> I<String>
 162
 163 If B<Table> is set to I<true>, you may feel the need to add something to the
 164 instance of the files. If set, I<String> is prepended to the instance as
 165 determined by querying the agent. When B<Table> is set to I<false> this option
 166 has no effect.
 167
 168 The C<UPS-MIB> is an example where you need this setting: It has voltages of
 169 the inlets, outlets and the battery of an UPS. However, it doesn't provide a
 170 descriptive column for these voltages. In this case having 1, 2,E<nbsp>... as
 171 instances is not enough, because the inlet voltages and outlet voltages may
 172 both have the subids 1, 2,E<nbsp>... You can use this setting to distinguish
 173 between the different voltages.
 174
 175 =item B<Values> I<OID> [I<OID> ...]
 176
 177 Configures the values to be queried from the SNMP host. The meaning slightly
 178 changes with the B<Table> setting. L<variables(5)> from the SNMP distribution
 179 describes the format of OIDs.
 180
 181 If B<Table> is set to I<true>, each I<OID> must be the prefix of all the
 182 values to query, e.E<nbsp>g. C<IF-MIB::ifInOctets> for all the counters of
 183 incoming traffic. This subtree is walked (using C<GETNEXT>) until a value from
 184 outside the subtree is returned.
 185
 186 If B<Table> is set to I<false>, each I<OID> must be the OID of exactly one
 187 value, e.E<nbsp>g. C<IF-MIB::ifInOctets.3> for the third counter of incoming
 188 traffic.
 189
 190 =item B<Scale> I<Value>
 191
 192 The gauge-values returned by the SNMP-agent are multiplied by I<Value>.  This
 193 is useful when values are transferred as a fixed point real number. For example,
 194 thermometers may transfer B<243> but actually mean B<24.3>, so you can specify
 195 a scale value of B<0.1> to correct this. The default value is, of course,
 196 B<1.0>.
 197
 198 This value is not applied to counter-values.
 199
 200 =item B<Shift> I<Value>
 201
 202 I<Value> is added to gauge-values returned by the SNMP-agent after they have
 203 been multiplied by any B<Scale> value. If, for example, a thermometer returns
 204 degrees Kelvin you could specify a shift of B<273.15> here to store values in
 205 degrees Celsius. The default value is, of course, B<0.0>.
 206
 207 This value is not applied to counter-values.
 208
 209 =item B<Ignore> I<Value> [, I<Value> ...]
 210
 211 The ignore values allows one to ignore Instances based on their name and the
 212 patterns specified by the various values you've entered. The match is a
 213 glob-type shell matching.
 214
 215 =item B<InvertMatch> I<true|false(default)>
 216
 217 The invertmatch value should be use in combination of the Ignore option.
 218 It changes the behaviour of the Ignore option, from a blacklist behaviour
 219 when InvertMatch is set to false, to a whitelist when specified to true.
 220
 221 =back
 222
 223 =head2 The Host block
 224
 225 The B<Host> block defines which hosts to query, which SNMP community and
 226 version to use and which of the defined B<Data> to query.
 227
 228 The argument passed to the B<Host> block is used as the hostname in the data
 229 stored by collectd.
 230
 231 =over 4
 232
 233 =item B<Address> I<IP-Address>|I<Hostname>
 234
 235 Set the address to connect to. Address may include transport specifier and/or
 236 port number.
 237
 238 =item B<Version> B<1>|B<2>|B<3>
 239
 240 Set the SNMP version to use. When giving B<2> version C<2c> is actually used.
 241
 242 =item B<Community> I<Community>
 243
 244 Pass I<Community> to the host. (Ignored for SNMPv3).
 245
 246 =item B<Username> I<Username>
 247
 248 Sets the I<Username> to use for SNMPv3 security.
 249
 250 =item B<SecurityLevel> I<authPriv>|I<authNoPriv>|I<noAuthNoPriv>
 251
 252 Selects the security level for SNMPv3 security.
 253
 254 =item B<Context> I<Context>
 255
 256 Sets the I<Context> for SNMPv3 security.
 257
 258 =item B<AuthProtocol> I<MD5>|I<SHA>
 259
 260 Selects the authentication protocol for SNMPv3 security.
 261
 262 =item B<AuthPassphrase> I<Passphrase>
 263
 264 Sets the authentication passphrase for SNMPv3 security.
 265
 266 =item B<PrivacyProtocol> I<AES>|I<DES>
 267
 268 Selects the privacy (encryption) protocol for SNMPv3 security.
 269
 270 =item B<PrivacyPassphrase> I<Passphrase>
 271
 272 Sets the privacy (encryption) passphrase for SNMPv3 security.
 273
 274 =item B<Collect> I<Data> [I<Data> ...]
 275
 276 Defines which values to collect. I<Data> refers to one of the B<Data> block
 277 above. Since the config file is read top-down you need to define the data
 278 before using it here.
 279
 280 =item B<Interval> I<Seconds>
 281
 282 Collect data from this host every I<Seconds> seconds. This option is meant for
 283 devices with not much CPU power, e.E<nbsp>g. network equipment such as
 284 switches, embedded devices, rack monitoring systems and so on. Since the
 285 B<Step> of generated RRD files depends on this setting it's wise to select a
 286 reasonable value once and never change it.
 287
 288 =item B<Timeout> I<Seconds>
 289
 290 How long to wait for a response. The C<Net-SNMP> library default is 1 second.
 291
 292 =item B<Retries> I<Integer>
 293
 294 The number of times that a query should be retried after the Timeout expires.
 295 The C<Net-SNMP> library default is 5.
 296
 297 =back
 298
 299 =head1 SEE ALSO
 300
 301 L<collectd(1)>,
 302 L<collectd.conf(5)>,
 303 L<snmpget(1)>,
 304 L<snmpgetnext(1)>,
 305 L<variables(5)>,
 306 L<unix(7)>
 307
 308 =head1 AUTHORS
 309
 310 Florian Forster E<lt>octo@collectd.orgE<gt>
 311 Michael Pilat E<lt>mike@mikepilat.comE<gt>
 312
 313 =cut