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<Plugin> I<Plugin>
 145
 146 Use I<Plugin> as the plugin name of the values that are dispatched.
 147 Defaults to C<snmp>.
 148
 149 =item B<Instance> I<Instance>
 150
 151 Sets the type-instance of the values that are dispatched. The meaning of this
 152 setting depends on whether B<Table> is set to I<true> or I<false>:
 153
 154 If B<Table> is set to I<true>, I<Instance> is interpreted as an SNMP-prefix
 155 that will return a list of values. Those values are then used as the actual
 156 type-instance. An example would be the C<IF-MIB::ifDescr> subtree.
 157 L<variables(5)> from the SNMP distribution describes the format of OIDs.
 158
 159 If B<Table> is set to I<true> and B<Instance> is omitted, then "SUBID" will be
 160 used as the instance.
 161
 162 If B<Table> is set to I<false> the actual string configured for I<Instance> is
 163 copied into the value-list. In this case I<Instance> may be empty, i.E<nbsp>e.
 164 "".
 165
 166 =item B<InstancePrefix> I<String>
 167
 168 If B<Table> is set to I<true>, you may feel the need to add something to the
 169 instance of the files. If set, I<String> is prepended to the instance as
 170 determined by querying the agent. When B<Table> is set to I<false> this option
 171 has no effect.
 172
 173 The C<UPS-MIB> is an example where you need this setting: It has voltages of
 174 the inlets, outlets and the battery of an UPS. However, it doesn't provide a
 175 descriptive column for these voltages. In this case having 1, 2,E<nbsp>... as
 176 instances is not enough, because the inlet voltages and outlet voltages may
 177 both have the subids 1, 2,E<nbsp>... You can use this setting to distinguish
 178 between the different voltages.
 179
 180 =item B<Values> I<OID> [I<OID> ...]
 181
 182 Configures the values to be queried from the SNMP host. The meaning slightly
 183 changes with the B<Table> setting. L<variables(5)> from the SNMP distribution
 184 describes the format of OIDs.
 185
 186 If B<Table> is set to I<true>, each I<OID> must be the prefix of all the
 187 values to query, e.E<nbsp>g. C<IF-MIB::ifInOctets> for all the counters of
 188 incoming traffic. This subtree is walked (using C<GETNEXT>) until a value from
 189 outside the subtree is returned.
 190
 191 If B<Table> is set to I<false>, each I<OID> must be the OID of exactly one
 192 value, e.E<nbsp>g. C<IF-MIB::ifInOctets.3> for the third counter of incoming
 193 traffic.
 194
 195 =item B<Scale> I<Value>
 196
 197 The gauge-values returned by the SNMP-agent are multiplied by I<Value>.  This
 198 is useful when values are transferred as a fixed point real number. For example,
 199 thermometers may transfer B<243> but actually mean B<24.3>, so you can specify
 200 a scale value of B<0.1> to correct this. The default value is, of course,
 201 B<1.0>.
 202
 203 This value is not applied to counter-values.
 204
 205 =item B<Shift> I<Value>
 206
 207 I<Value> is added to gauge-values returned by the SNMP-agent after they have
 208 been multiplied by any B<Scale> value. If, for example, a thermometer returns
 209 degrees Kelvin you could specify a shift of B<273.15> here to store values in
 210 degrees Celsius. The default value is, of course, B<0.0>.
 211
 212 This value is not applied to counter-values.
 213
 214 =item B<Ignore> I<Value> [, I<Value> ...]
 215
 216 The ignore values allows one to ignore Instances based on their name and the
 217 patterns specified by the various values you've entered. The match is a
 218 glob-type shell matching.
 219
 220 =item B<InvertMatch> I<true|false(default)>
 221
 222 The invertmatch value should be use in combination of the Ignore option.
 223 It changes the behaviour of the Ignore option, from a blacklist behaviour
 224 when InvertMatch is set to false, to a whitelist when specified to true.
 225
 226 =back
 227
 228 =head2 The Host block
 229
 230 The B<Host> block defines which hosts to query, which SNMP community and
 231 version to use and which of the defined B<Data> to query.
 232
 233 The argument passed to the B<Host> block is used as the hostname in the data
 234 stored by collectd.
 235
 236 =over 4
 237
 238 =item B<Address> I<IP-Address>|I<Hostname>
 239
 240 Set the address to connect to. Address may include transport specifier and/or
 241 port number.
 242
 243 =item B<Version> B<1>|B<2>|B<3>
 244
 245 Set the SNMP version to use. When giving B<2> version C<2c> is actually used.
 246
 247 =item B<Community> I<Community>
 248
 249 Pass I<Community> to the host. (Ignored for SNMPv3).
 250
 251 =item B<Username> I<Username>
 252
 253 Sets the I<Username> to use for SNMPv3 security.
 254
 255 =item B<SecurityLevel> I<authPriv>|I<authNoPriv>|I<noAuthNoPriv>
 256
 257 Selects the security level for SNMPv3 security.
 258
 259 =item B<Context> I<Context>
 260
 261 Sets the I<Context> for SNMPv3 security.
 262
 263 =item B<AuthProtocol> I<MD5>|I<SHA>
 264
 265 Selects the authentication protocol for SNMPv3 security.
 266
 267 =item B<AuthPassphrase> I<Passphrase>
 268
 269 Sets the authentication passphrase for SNMPv3 security.
 270
 271 =item B<PrivacyProtocol> I<AES>|I<DES>
 272
 273 Selects the privacy (encryption) protocol for SNMPv3 security.
 274
 275 =item B<PrivacyPassphrase> I<Passphrase>
 276
 277 Sets the privacy (encryption) passphrase for SNMPv3 security.
 278
 279 =item B<Collect> I<Data> [I<Data> ...]
 280
 281 Defines which values to collect. I<Data> refers to one of the B<Data> block
 282 above. Since the config file is read top-down you need to define the data
 283 before using it here.
 284
 285 =item B<Interval> I<Seconds>
 286
 287 Collect data from this host every I<Seconds> seconds. This option is meant for
 288 devices with not much CPU power, e.E<nbsp>g. network equipment such as
 289 switches, embedded devices, rack monitoring systems and so on. Since the
 290 B<Step> of generated RRD files depends on this setting it's wise to select a
 291 reasonable value once and never change it.
 292
 293 =item B<Timeout> I<Seconds>
 294
 295 How long to wait for a response. The C<Net-SNMP> library default is 1 second.
 296
 297 =item B<Retries> I<Integer>
 298
 299 The number of times that a query should be retried after the Timeout expires.
 300 The C<Net-SNMP> library default is 5.
 301
 302 =back
 303
 304 =head1 SEE ALSO
 305
 306 L<collectd(1)>,
 307 L<collectd.conf(5)>,
 308 L<snmpget(1)>,
 309 L<snmpgetnext(1)>,
 310 L<variables(5)>,
 311 L<unix(7)>
 312
 313 =head1 AUTHORS
 314
 315 Florian Forster E<lt>octo@collectd.orgE<gt>
 316 Michael Pilat E<lt>mike@mikepilat.comE<gt>
 317
 318 =cut