| 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 |
Table false |
| 14 |
Type "voltage" |
| 15 |
TypeInstance "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 |
Table false |
| 21 |
Type "users" |
| 22 |
Shift -1 |
| 23 |
Values "HOST-RESOURCES-MIB::hrSystemNumUsers.0" |
| 24 |
</Data> |
| 25 |
<Data "std_traffic"> |
| 26 |
Table true |
| 27 |
Type "if_octets" |
| 28 |
TypeInstanceOID "IF-MIB::ifDescr" |
| 29 |
#FilterOID "IF-MIB::ifOperStatus" |
| 30 |
#FilterValues "1", "2" |
| 31 |
Values "IF-MIB::ifInOctets" "IF-MIB::ifOutOctets" |
| 32 |
</Data> |
| 33 |
<Data "lancom_stations_total"> |
| 34 |
Type "counter" |
| 35 |
PluginInstance "stations_total" |
| 36 |
Table true |
| 37 |
Count true |
| 38 |
Values "SNMPv2-SMI::enterprises.2356.11.1.3.32.1.10" # SNMPv2-SMI::enterprises.lancom-systems.lcos.lcsStatus.lcsStatusWlan.lcsStatusWlanStationTableTable.lcsStatusWlanStationTableEntry.lcsStatusWlanStationTableEntryState |
| 39 |
</Data> |
| 40 |
<Data "lancom_stations_connected"> |
| 41 |
Type "counter" |
| 42 |
PluginInstance "stations_connected" |
| 43 |
Table true |
| 44 |
Count true |
| 45 |
Values "SNMPv2-SMI::enterprises.2356.11.1.3.32.1.10" # SNMPv2-SMI::enterprises.lancom-systems.lcos.lcsStatus.lcsStatusWlan.lcsStatusWlanStationTableTable.lcsStatusWlanStationTableEntry.lcsStatusWlanStationTableEntryState |
| 46 |
FilterOID "SNMPv2-SMI::enterprises.2356.11.1.3.32.1.10" |
| 47 |
FilterValues "3" # eConnected |
| 48 |
</Data> |
| 49 |
|
| 50 |
<Host "some.switch.mydomain.org"> |
| 51 |
Address "192.168.0.2" |
| 52 |
Version 1 |
| 53 |
Community "community_string" |
| 54 |
Collect "std_traffic" |
| 55 |
Interval 120 |
| 56 |
Timeout 10 |
| 57 |
Retries 1 |
| 58 |
</Host> |
| 59 |
<Host "some.server.mydomain.org"> |
| 60 |
Address "192.168.0.42" |
| 61 |
Version 2 |
| 62 |
Community "another_string" |
| 63 |
Collect "std_traffic" "hr_users" |
| 64 |
</Host> |
| 65 |
<Host "secure.router.mydomain.org"> |
| 66 |
Address "192.168.0.7:165" |
| 67 |
Version 3 |
| 68 |
SecurityLevel "authPriv" |
| 69 |
Username "cosmo" |
| 70 |
AuthProtocol "SHA" |
| 71 |
AuthPassphrase "setec_astronomy" |
| 72 |
PrivacyProtocol "AES" |
| 73 |
PrivacyPassphrase "too_many_secrets" |
| 74 |
Collect "std_traffic" |
| 75 |
</Host> |
| 76 |
<Host "some.ups.mydomain.org"> |
| 77 |
Address "tcp:192.168.0.3" |
| 78 |
Version 1 |
| 79 |
Community "more_communities" |
| 80 |
Collect "powerplus_voltge_input" |
| 81 |
Interval 300 |
| 82 |
Timeout 5 |
| 83 |
Retries 5 |
| 84 |
</Host> |
| 85 |
</Plugin> |
| 86 |
|
| 87 |
=head1 DESCRIPTION |
| 88 |
|
| 89 |
The C<snmp plugin> queries other hosts using SNMP, the simple network |
| 90 |
management protocol, and translates the value it receives to collectd's |
| 91 |
internal format and dispatches them. Depending on the write plugins you have |
| 92 |
loaded they may be written to disk or submitted to another instance or |
| 93 |
whatever you configured. |
| 94 |
|
| 95 |
Because querying a host via SNMP may produce a timeout the "complex reads" |
| 96 |
polling method is used. The ReadThreads parameter in the main configuration |
| 97 |
influences the number of parallel polling jobs which can be undertaken. If |
| 98 |
you expect timeouts or some polling to take a long time, you should increase |
| 99 |
this parameter. Note that other plugins also use the same threads. |
| 100 |
|
| 101 |
=head1 CONFIGURATION |
| 102 |
|
| 103 |
Since the aim of the C<snmp plugin> is to provide a generic interface to SNMP, |
| 104 |
its configuration is not trivial and may take some time. |
| 105 |
|
| 106 |
Since the C<Net-SNMP> library is used you can use all the environment variables |
| 107 |
that are interpreted by that package. See L<snmpcmd(1)> for more details. |
| 108 |
|
| 109 |
There are two types of blocks that can be contained in the |
| 110 |
C<E<lt>PluginE<nbsp>snmpE<gt>> block: B<Data> and B<Host>: |
| 111 |
|
| 112 |
=head2 The B<Data> block |
| 113 |
|
| 114 |
The B<Data> block defines a list of values or a table of values that are to be |
| 115 |
queried. The following options can be set: |
| 116 |
|
| 117 |
=over 4 |
| 118 |
|
| 119 |
=item B<Type> I<type> |
| 120 |
|
| 121 |
collectd's type that is to be used, e.E<nbsp>g. "if_octets" for interface |
| 122 |
traffic or "users" for a user count. The types are read from the B<TypesDB> |
| 123 |
(see L<collectd.conf(5)>), so you may want to check for which types are |
| 124 |
defined. See L<types.db(5)> for a description of the format of this file. |
| 125 |
|
| 126 |
=item B<Table> I<true|false> |
| 127 |
|
| 128 |
Define if this is a single list of values or a table of values. The difference |
| 129 |
is the following: |
| 130 |
|
| 131 |
When B<Table> is set to B<false>, the OIDs given to B<Values> (see below) are |
| 132 |
queried using the C<GET> SNMP command (see L<snmpget(1)>) and transmitted to |
| 133 |
collectd. B<One> value list is dispatched and, eventually, one file will be |
| 134 |
written. |
| 135 |
|
| 136 |
When B<Table> is set to B<true>, the OIDs given to B<Values>, B<TypeInstanceOID>, |
| 137 |
B<PluginInstanceOID>, B<HostOID> and B<FilterOID> (see below) are queried using |
| 138 |
the C<GETNEXT> SNMP command until the subtree is left. After all the lists |
| 139 |
(think: all columns of the table) have been read, either (B<Count> set to B<false>) |
| 140 |
B<several> value sets will be dispatched and, eventually, several files will be |
| 141 |
written, or (B<Count> set to B<true>) one single value will be dispatched. If you |
| 142 |
configure a B<Type> (see above) which needs more than one data source (for |
| 143 |
example C<if_octets> which needs C<rx> and C<tx>) you will need to specify more |
| 144 |
than one (two, in the example case) OIDs with the B<Values> option and can't use |
| 145 |
the B<Count> option. This has nothing to do with the B<Table> setting. |
| 146 |
|
| 147 |
For example, if you want to query the number of users on a system, you can use |
| 148 |
C<HOST-RESOURCES-MIB::hrSystemNumUsers.0>. This is one value and belongs to one |
| 149 |
value list, therefore B<Table> must be set to B<false>. Please note that, in |
| 150 |
this case, you have to include the sequence number (zero in this case) in the |
| 151 |
OID. |
| 152 |
|
| 153 |
Counter example: If you want to query the interface table provided by the |
| 154 |
C<IF-MIB>, e.E<nbsp>g. the bytes transmitted. There are potentially many |
| 155 |
interfaces, so you will want to set B<Table> to B<true>. Because the |
| 156 |
C<if_octets> type needs two values, received and transmitted bytes, you need to |
| 157 |
specify two OIDs in the B<Values> setting, in this case likely |
| 158 |
C<IF-MIB::ifHCInOctets> and C<IF-MIB::ifHCOutOctets>. But, this is because of |
| 159 |
the B<Type> setting, not the B<Table> setting. |
| 160 |
|
| 161 |
Since the semantic of B<Instance> and B<Values> depends on this setting you |
| 162 |
need to set it before setting them. Doing vice versa will result in undefined |
| 163 |
behavior. |
| 164 |
|
| 165 |
=item B<Plugin> I<Plugin> |
| 166 |
|
| 167 |
Use I<Plugin> as the plugin name of the values that are dispatched. |
| 168 |
Defaults to C<snmp>. |
| 169 |
|
| 170 |
=item B<PluginInstance> I<Instance> |
| 171 |
|
| 172 |
Sets the plugin-instance of the values that are dispatched to I<Instance> value. |
| 173 |
|
| 174 |
When B<Table> is set to I<true> and B<PluginInstanceOID> is set then this option |
| 175 |
has no effect. |
| 176 |
|
| 177 |
Defaults to an empty string. |
| 178 |
|
| 179 |
=item B<TypeInstance> I<Instance> |
| 180 |
|
| 181 |
Sets the type-instance of the values that are dispatched to I<Instance> value. |
| 182 |
|
| 183 |
When B<Table> is set to I<true> and B<TypeInstanceOID> is set then this option |
| 184 |
has no effect. |
| 185 |
|
| 186 |
Defaults to an empty string. |
| 187 |
|
| 188 |
=item B<TypeInstanceOID> I<OID> |
| 189 |
|
| 190 |
=item B<PluginInstanceOID> I<OID> |
| 191 |
|
| 192 |
=item B<HostOID> I<OID> |
| 193 |
|
| 194 |
If B<Table> is set to I<true>, I<OID> is interpreted as an SNMP-prefix that will |
| 195 |
return a list of values. Those values are then used as the actual type-instance, |
| 196 |
plugin-instance or host of dispatched metrics. An example would be the |
| 197 |
C<IF-MIB::ifDescr> subtree. L<variables(5)> from the SNMP distribution describes |
| 198 |
the format of OIDs. When option is set to empty string, then "SUBID" will be used |
| 199 |
as the value. |
| 200 |
|
| 201 |
Prefix may be set for values with use of appropriate B<TypeInstancePrefix>, |
| 202 |
B<PluginInstancePrefix> and B<HostPrefix> options. |
| 203 |
|
| 204 |
When B<Table> is set to I<false> or B<Count> is set to I<true>, these options |
| 205 |
have no effect. |
| 206 |
|
| 207 |
Defaults: When no one of these options is configured explicitly, |
| 208 |
B<TypeInstanceOID> defaults to an empty string. |
| 209 |
|
| 210 |
=item B<TypeInstancePrefix> |
| 211 |
|
| 212 |
=item B<PluginInstancePrefix> |
| 213 |
|
| 214 |
=item B<HostPrefix> |
| 215 |
|
| 216 |
These options are intented to be used together with B<TypeInstanceOID>, |
| 217 |
B<PluginInstanceOID> and B<HostOID> respectively. |
| 218 |
|
| 219 |
If set, I<String> is preprended to values received by querying the agent. |
| 220 |
|
| 221 |
When B<Table> is set to I<false> or B<Count> is set to I<true>, these options |
| 222 |
have no effect. |
| 223 |
|
| 224 |
The C<UPS-MIB> is an example where you need this setting: It has voltages of |
| 225 |
the inlets, outlets and the battery of an UPS. However, it doesn't provide a |
| 226 |
descriptive column for these voltages. In this case having 1, 2,E<nbsp>... as |
| 227 |
instances is not enough, because the inlet voltages and outlet voltages may |
| 228 |
both have the subids 1, 2,E<nbsp>... You can use this setting to distinguish |
| 229 |
between the different voltages. |
| 230 |
|
| 231 |
=item B<Instance> I<Instance> |
| 232 |
|
| 233 |
Attention: this option exists for backwards compatibility only and will be |
| 234 |
removed in next major release. Please use B<TypeInstance> / B<TypeInstanceOID> |
| 235 |
instead. |
| 236 |
|
| 237 |
The meaning of this setting depends on whether B<Table> is set to I<true> or |
| 238 |
I<false>. |
| 239 |
|
| 240 |
If B<Table> is set to I<true>, option behaves as B<TypeInstanceOID>. |
| 241 |
If B<Table> is set to I<false>, option behaves as B<TypeInstance>. |
| 242 |
|
| 243 |
Note what B<Table> option must be set before setting B<Instance>. |
| 244 |
|
| 245 |
=item B<InstancePrefix> I<String> |
| 246 |
|
| 247 |
Attention: this option exists for backwards compatibility only and will be |
| 248 |
removed in next major release. Please use B<TypeInstancePrefix> instead. |
| 249 |
|
| 250 |
=item B<Values> I<OID> [I<OID> ...] |
| 251 |
|
| 252 |
Configures the values to be queried from the SNMP host. The meaning slightly |
| 253 |
changes with the B<Table> setting. L<variables(5)> from the SNMP distribution |
| 254 |
describes the format of OIDs. |
| 255 |
|
| 256 |
If B<Table> is set to I<true>, each I<OID> must be the prefix of all the |
| 257 |
values to query, e.E<nbsp>g. C<IF-MIB::ifInOctets> for all the counters of |
| 258 |
incoming traffic. This subtree is walked (using C<GETNEXT>) until a value from |
| 259 |
outside the subtree is returned. |
| 260 |
|
| 261 |
If B<Table> is set to I<false>, each I<OID> must be the OID of exactly one |
| 262 |
value, e.E<nbsp>g. C<IF-MIB::ifInOctets.3> for the third counter of incoming |
| 263 |
traffic. |
| 264 |
|
| 265 |
=item B<Count> I<true|false> |
| 266 |
|
| 267 |
Instead of dispatching one or multiple values per Table entry containing the |
| 268 |
I<OID>(s) given in the B<Values> option, just dispatch a single count giving the |
| 269 |
number of entries that would have been dispatched. This is especially useful when |
| 270 |
combined with the filtering options (see below) to count the number of entries in |
| 271 |
a Table matching certain criteria. |
| 272 |
|
| 273 |
When B<Table> is set to I<false>, this option has no effect. |
| 274 |
|
| 275 |
=item B<Scale> I<Value> |
| 276 |
|
| 277 |
The gauge-values returned by the SNMP-agent are multiplied by I<Value>. This |
| 278 |
is useful when values are transferred as a fixed point real number. For example, |
| 279 |
thermometers may transfer B<243> but actually mean B<24.3>, so you can specify |
| 280 |
a scale value of B<0.1> to correct this. The default value is, of course, |
| 281 |
B<1.0>. |
| 282 |
|
| 283 |
This value is not applied to counter-values. |
| 284 |
|
| 285 |
=item B<Shift> I<Value> |
| 286 |
|
| 287 |
I<Value> is added to gauge-values returned by the SNMP-agent after they have |
| 288 |
been multiplied by any B<Scale> value. If, for example, a thermometer returns |
| 289 |
degrees Kelvin you could specify a shift of B<273.15> here to store values in |
| 290 |
degrees Celsius. The default value is, of course, B<0.0>. |
| 291 |
|
| 292 |
This value is not applied to counter-values. |
| 293 |
|
| 294 |
=item B<Ignore> I<Value> [, I<Value> ...] |
| 295 |
|
| 296 |
The ignore values allows one to ignore TypeInstances based on their name and |
| 297 |
the patterns specified by the various values you've entered. The match is a |
| 298 |
glob-type shell matching. |
| 299 |
|
| 300 |
When B<Table> is set to I<false> then this option has no effect. |
| 301 |
|
| 302 |
=item B<InvertMatch> I<true|false(default)> |
| 303 |
|
| 304 |
The invertmatch value should be use in combination of the Ignore option. |
| 305 |
It changes the behaviour of the Ignore option, from a blacklist behaviour |
| 306 |
when InvertMatch is set to false, to a whitelist when specified to true. |
| 307 |
|
| 308 |
=item B<FilterOID> I<OID> |
| 309 |
|
| 310 |
=item B<FilterValues> I<Value> [, I<Value> ...] |
| 311 |
|
| 312 |
=item B<FilterIgnoreSelected> I<true|false(default)> |
| 313 |
|
| 314 |
When B<Table> is set to I<true>, these options allow to configure filtering |
| 315 |
based on MIB values. |
| 316 |
|
| 317 |
The B<FilterOID> declares I<OID> to fill table column with values. |
| 318 |
The B<FilterValues> declares values list to do match. Whether table row will be |
| 319 |
collected or ignored depends on the B<FilterIgnoreSelected> setting. |
| 320 |
As with other plugins that use the daemon's ignorelist functionality, a string |
| 321 |
that starts and ends with a slash is interpreted as a regular expression. |
| 322 |
|
| 323 |
If no selection is configured at all, B<all> table rows are selected. |
| 324 |
|
| 325 |
When B<Table> is set to I<false> then these options has no effect. |
| 326 |
|
| 327 |
See B<Table> and F</"IGNORELISTS"> for details. |
| 328 |
|
| 329 |
=back |
| 330 |
|
| 331 |
=head2 The Host block |
| 332 |
|
| 333 |
The B<Host> block defines which hosts to query, which SNMP community and |
| 334 |
version to use and which of the defined B<Data> to query. |
| 335 |
|
| 336 |
The argument passed to the B<Host> block is used as the hostname in the data |
| 337 |
stored by collectd. |
| 338 |
|
| 339 |
=over 4 |
| 340 |
|
| 341 |
=item B<Address> I<IP-Address>|I<Hostname> |
| 342 |
|
| 343 |
Set the address to connect to. Address may include transport specifier and/or |
| 344 |
port number. |
| 345 |
|
| 346 |
=item B<Version> B<1>|B<2>|B<3> |
| 347 |
|
| 348 |
Set the SNMP version to use. When giving B<2> version C<2c> is actually used. |
| 349 |
|
| 350 |
=item B<Community> I<Community> |
| 351 |
|
| 352 |
Pass I<Community> to the host. (Ignored for SNMPv3). |
| 353 |
|
| 354 |
=item B<Username> I<Username> |
| 355 |
|
| 356 |
Sets the I<Username> to use for SNMPv3 security. |
| 357 |
|
| 358 |
=item B<SecurityLevel> I<authPriv>|I<authNoPriv>|I<noAuthNoPriv> |
| 359 |
|
| 360 |
Selects the security level for SNMPv3 security. |
| 361 |
|
| 362 |
=item B<Context> I<Context> |
| 363 |
|
| 364 |
Sets the I<Context> for SNMPv3 security. |
| 365 |
|
| 366 |
=item B<AuthProtocol> I<MD5>|I<SHA> |
| 367 |
|
| 368 |
Selects the authentication protocol for SNMPv3 security. |
| 369 |
|
| 370 |
=item B<AuthPassphrase> I<Passphrase> |
| 371 |
|
| 372 |
Sets the authentication passphrase for SNMPv3 security. |
| 373 |
|
| 374 |
=item B<PrivacyProtocol> I<AES>|I<DES> |
| 375 |
|
| 376 |
Selects the privacy (encryption) protocol for SNMPv3 security. |
| 377 |
|
| 378 |
=item B<PrivacyPassphrase> I<Passphrase> |
| 379 |
|
| 380 |
Sets the privacy (encryption) passphrase for SNMPv3 security. |
| 381 |
|
| 382 |
=item B<Collect> I<Data> [I<Data> ...] |
| 383 |
|
| 384 |
Defines which values to collect. I<Data> refers to one of the B<Data> block |
| 385 |
above. Since the config file is read top-down you need to define the data |
| 386 |
before using it here. |
| 387 |
|
| 388 |
=item B<Interval> I<Seconds> |
| 389 |
|
| 390 |
Collect data from this host every I<Seconds> seconds. This option is meant for |
| 391 |
devices with not much CPU power, e.E<nbsp>g. network equipment such as |
| 392 |
switches, embedded devices, rack monitoring systems and so on. Since the |
| 393 |
B<Step> of generated RRD files depends on this setting it's wise to select a |
| 394 |
reasonable value once and never change it. |
| 395 |
|
| 396 |
=item B<Timeout> I<Seconds> |
| 397 |
|
| 398 |
How long to wait for a response. The C<Net-SNMP> library default is 1 second. |
| 399 |
|
| 400 |
=item B<Retries> I<Integer> |
| 401 |
|
| 402 |
The number of times that a query should be retried after the Timeout expires. |
| 403 |
The C<Net-SNMP> library default is 5. |
| 404 |
|
| 405 |
=item B<BulkSize> I<Integer> |
| 406 |
|
| 407 |
Configures the size of SNMP bulk transfers. The default is 0, which disables bulk transfers altogether. |
| 408 |
|
| 409 |
=back |
| 410 |
|
| 411 |
=head1 SEE ALSO |
| 412 |
|
| 413 |
L<collectd(1)>, |
| 414 |
L<collectd.conf(5)>, |
| 415 |
L<snmpget(1)>, |
| 416 |
L<snmpgetnext(1)>, |
| 417 |
L<variables(5)>, |
| 418 |
L<unix(7)> |
| 419 |
|
| 420 |
=head1 AUTHORS |
| 421 |
|
| 422 |
Florian Forster E<lt>[email protected]<gt> |
| 423 |
Michael Pilat E<lt>[email protected]<gt> |
| 424 |
|
| 425 |
=cut |