1COLLECTD-SNMP(5) collectd COLLECTD-SNMP(5)
2
6 collectd-snmp - Documentation of collectd's "snmp plugin"
7
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 <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
88 The "snmp plugin" queries other hosts using SNMP, the simple network
89 management protocol, and translates the value it receives to collectd's
90 internal format and dispatches them. Depending on the write plugins you
91 have loaded they may be written to disk or submitted to another
92 instance or whatever you configured.
93 Because querying a host via SNMP may produce a timeout the "complex
95 reads" polling method is used. The ReadThreads parameter in the main
96 configuration influences the number of parallel polling jobs which can
97 be undertaken. If you expect timeouts or some polling to take a long
98 time, you should increase this parameter. Note that other plugins also
99 use the same threads.
100
102 Since the aim of the "snmp plugin" is to provide a generic interface to
103 SNMP, its configuration is not trivial and may take some time.
104 Since the "Net-SNMP" library is used you can use all the environment
106 variables that are interpreted by that package. See snmpcmd(1) for more
107 details.
108 There are two types of blocks that can be contained in the
110 "<Plugin snmp>" block: Data and Host:
111 The Data block
113 The Data block defines a list of values or a table of values that are
114 to be queried. The following options can be set:
115 Type type
117 collectd's type that is to be used, e. g. "if_octets" for interface
118 traffic or "users" for a user count. The types are read from the
119 TypesDB (see collectd.conf(5)), so you may want to check for which
120 types are defined. See types.db(5) for a description of the format
121 of this file.
122 Table true|false
124 Define if this is a single list of values or a table of values. The
125 difference is the following:
126 When Table is set to false, the OIDs given to Values (see below)
128 are queried using the "GET" SNMP command (see snmpget(1)) and
129 transmitted to collectd. One value list is dispatched and,
130 eventually, one file will be written.
131 When Table is set to true, the OIDs given to Values,
133 TypeInstanceOID, PluginInstanceOID, HostOID and FilterOID (see
134 below) are queried using the "GETNEXT" SNMP command until the
135 subtree is left. After all the lists (think: all columns of the
136 table) have been read, either (Count set to false) several value
137 sets will be dispatched and, eventually, several files will be
138 written, or (Count set to true) one single value will be
139 dispatched. If you configure a Type (see above) which needs more
140 than one data source (for example "if_octets" which needs "rx" and
141 "tx") you will need to specify more than one (two, in the example
142 case) OIDs with the Values option and can't use the Count option.
143 This has nothing to do with the Table setting.
144 For example, if you want to query the number of users on a system,
146 you can use "HOST-RESOURCES-MIB::hrSystemNumUsers.0". This is one
147 value and belongs to one value list, therefore Table must be set to
148 false. Please note that, in this case, you have to include the
149 sequence number (zero in this case) in the OID.
150 Counter example: If you want to query the interface table provided
152 by the "IF-MIB", e. g. the bytes transmitted. There are potentially
153 many interfaces, so you will want to set Table to true. Because the
154 "if_octets" type needs two values, received and transmitted bytes,
155 you need to specify two OIDs in the Values setting, in this case
156 likely "IF-MIB::ifHCInOctets" and "IF-MIB::ifHCOutOctets". But,
157 this is because of the Type setting, not the Table setting.
158 Since the semantic of Instance and Values depends on this setting
160 you need to set it before setting them. Doing vice versa will
161 result in undefined behavior.
162 Plugin Plugin
164 Use Plugin as the plugin name of the values that are dispatched.
165 Defaults to "snmp".
166 PluginInstance Instance
168 Sets the plugin-instance of the values that are dispatched to
169 Instance value.
170 When Table is set to true and PluginInstanceOID is set then this
172 option has no effect.
173 Defaults to an empty string.
175 TypeInstance Instance
177 Sets the type-instance of the values that are dispatched to
178 Instance value.
179 When Table is set to true and TypeInstanceOID is set then this
181 option has no effect.
182 Defaults to an empty string.
184 TypeInstanceOID OID
186 PluginInstanceOID OID
187 HostOID OID
188 If Table is set to true, OID is interpreted as an SNMP-prefix that
189 will return a list of values. Those values are then used as the
190 actual type-instance, plugin-instance or host of dispatched
191 metrics. An example would be the "IF-MIB::ifDescr" subtree.
192 variables(5) from the SNMP distribution describes the format of
193 OIDs. When option is set to empty string, then "SUBID" will be used
194 as the value.
195 Prefix may be set for values with use of appropriate
197 TypeInstancePrefix, PluginInstancePrefix and HostPrefix options.
198 When Table is set to false or Count is set to true, these options
200 have no effect.
201 Defaults: When no one of these options is configured explicitly,
203 TypeInstanceOID defaults to an empty string.
204 TypeInstancePrefix
206 PluginInstancePrefix
207 HostPrefix
208 These options are intented to be used together with
209 TypeInstanceOID, PluginInstanceOID and HostOID respectively.
210 If set, String is preprended to values received by querying the
212 agent.
213 When Table is set to false or Count is set to true, these options
215 have no effect.
216 The "UPS-MIB" is an example where you need this setting: It has
218 voltages of the inlets, outlets and the battery of an UPS. However,
219 it doesn't provide a descriptive column for these voltages. In this
220 case having 1, 2, ... as instances is not enough, because the inlet
221 voltages and outlet voltages may both have the subids 1, 2, ... You
222 can use this setting to distinguish between the different voltages.
223 Instance Instance
225 Attention: this option exists for backwards compatibility only and
226 will be removed in next major release. Please use TypeInstance /
227 TypeInstanceOID instead.
228 The meaning of this setting depends on whether Table is set to true
230 or false.
231 If Table is set to true, option behaves as TypeInstanceOID. If
233 Table is set to false, option behaves as TypeInstance.
234 Note what Table option must be set before setting Instance.
236 InstancePrefix String
238 Attention: this option exists for backwards compatibility only and
239 will be removed in next major release. Please use
240 TypeInstancePrefix instead.
241 Values OID [OID ...]
243 Configures the values to be queried from the SNMP host. The meaning
244 slightly changes with the Table setting. variables(5) from the SNMP
245 distribution describes the format of OIDs.
246 If Table is set to true, each OID must be the prefix of all the
248 values to query, e. g. "IF-MIB::ifInOctets" for all the counters of
249 incoming traffic. This subtree is walked (using "GETNEXT") until a
250 value from outside the subtree is returned.
251 If Table is set to false, each OID must be the OID of exactly one
253 value, e. g. "IF-MIB::ifInOctets.3" for the third counter of
254 incoming traffic.
255 Count true|false
257 Instead of dispatching one or multiple values per Table entry
258 containing the OID(s) given in the Values option, just dispatch a
259 single count giving the number of entries that would have been
260 dispatched. This is especially useful when combined with the
261 filtering options (see below) to count the number of entries in a
262 Table matching certain criteria.
263 When Table is set to false, this option has no effect.
265 Scale Value
267 The gauge-values returned by the SNMP-agent are multiplied by
268 Value. This is useful when values are transferred as a fixed point
269 real number. For example, thermometers may transfer 243 but
270 actually mean 24.3, so you can specify a scale value of 0.1 to
271 correct this. The default value is, of course, 1.0.
272 This value is not applied to counter-values.
274 Shift Value
276 Value is added to gauge-values returned by the SNMP-agent after
277 they have been multiplied by any Scale value. If, for example, a
278 thermometer returns degrees Kelvin you could specify a shift of
279 273.15 here to store values in degrees Celsius. The default value
280 is, of course, 0.0.
281 This value is not applied to counter-values.
283 Ignore Value [, Value ...]
285 The ignore values allows one to ignore TypeInstances based on their
286 name and the patterns specified by the various values you've
287 entered. The match is a glob-type shell matching.
288 When Table is set to false then this option has no effect.
290 InvertMatch true|false(default)
292 The invertmatch value should be use in combination of the Ignore
293 option. It changes the behaviour of the Ignore option, from a
294 blacklist behaviour when InvertMatch is set to false, to a
295 whitelist when specified to true.
296 FilterOID OID
298 FilterValues Value [, Value ...]
299 FilterIgnoreSelected true|false(default)
300 When Table is set to true, these options allow to configure
301 filtering based on MIB values.
302 The FilterOID declares OID to fill table column with values. The
304 FilterValues declares values list to do match. Whether table row
305 will be collected or ignored depends on the FilterIgnoreSelected
306 setting. As with other plugins that use the daemon's ignorelist
307 functionality, a string that starts and ends with a slash is
308 interpreted as a regular expression.
309 If no selection is configured at all, all table rows are selected.
311 When Table is set to false then these options has no effect.
313 See Table and /"IGNORELISTS" for details.
315 The Host block
317 The Host block defines which hosts to query, which SNMP community and
318 version to use and which of the defined Data to query.
319 The argument passed to the Host block is used as the hostname in the
321 data stored by collectd.
322 Address IP-Address|Hostname
324 Set the address to connect to. Address may include transport
325 specifier and/or port number.
326 Version 1|2|3
328 Set the SNMP version to use. When giving 2 version "2c" is actually
329 used.
330 Community Community
332 Pass Community to the host. (Ignored for SNMPv3).
333 Username Username
335 Sets the Username to use for SNMPv3 security.
336 SecurityLevel authPriv|authNoPriv|noAuthNoPriv
338 Selects the security level for SNMPv3 security.
339 Context Context
341 Sets the Context for SNMPv3 security.
342 AuthProtocol MD5|SHA
344 Selects the authentication protocol for SNMPv3 security.
345 AuthPassphrase Passphrase
347 Sets the authentication passphrase for SNMPv3 security.
348 PrivacyProtocol AES|DES
350 Selects the privacy (encryption) protocol for SNMPv3 security.
351 PrivacyPassphrase Passphrase
353 Sets the privacy (encryption) passphrase for SNMPv3 security.
354 Collect Data [Data ...]
356 Defines which values to collect. Data refers to one of the Data
357 block above. Since the config file is read top-down you need to
358 define the data before using it here.
359 Interval Seconds
361 Collect data from this host every Seconds seconds. This option is
362 meant for devices with not much CPU power, e. g. network equipment
363 such as switches, embedded devices, rack monitoring systems and so
364 on. Since the Step of generated RRD files depends on this setting
365 it's wise to select a reasonable value once and never change it.
366 Timeout Seconds
368 How long to wait for a response. The "Net-SNMP" library default is
369 1 second.
370 Retries Integer
372 The number of times that a query should be retried after the
373 Timeout expires. The "Net-SNMP" library default is 5.
374 BulkSize Integer
376 Configures the size of SNMP bulk transfers. The default is 0, which
377 disables bulk transfers altogether.
378
380 collectd(1), collectd.conf(5), snmpget(1), snmpgetnext(1),
381 variables(5), unix(7)
382
384 Florian Forster <octo@collectd.org> Michael Pilat <mike@mikepilat.com>
3855.12.0 2020-09-03 COLLECTD-SNMP(5)