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 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 <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
71 The "snmp plugin" queries other hosts using SNMP, the simple network
72 management protocol, and translates the value it receives to collectd's
73 internal format and dispatches them. Depending on the write plugins you
74 have loaded they may be written to disk or submitted to another
75 instance or whatever you configured.
76 Because querying a host via SNMP may produce a timeout multiple threads
78 are used to query hosts in parallel. Depending on the number of hosts
79 between one and ten threads are used.
80
82 Since the aim of the "snmp plugin" is to provide a generic interface to
83 SNMP, its configuration is not trivial and may take some time.
84 Since the "Net-SNMP" library is used you can use all the environment
86 variables that are interpreted by that package. See snmpcmd(1) for more
87 details.
88 There are two types of blocks that can be contained in the
90 "<Plugin snmp>" block: Data and Host:
91 The Data block
93 The Data block defines a list of values or a table of values that are
94 to be queried. The following options can be set:
95 Type type
97 collectd's type that is to be used, e. g. "if_octets" for interface
98 traffic or "users" for a user count. The types are read from the
99 TypesDB (see collectd.conf(5)), so you may want to check for which
100 types are defined. See types.db(5) for a description of the format
101 of this file.
102 Table true|false
104 Define if this is a single list of values or a table of values. The
105 difference is the following:
106 When Table is set to false, the OIDs given to Values (see below)
108 are queried using the "GET" SNMP command (see snmpget(1)) and
109 transmitted to collectd. One value list is dispatched and,
110 eventually, one file will be written.
111 When Table is set to true, the OIDs given to Values (see below) are
113 queried using the "GETNEXT" SNMP command until the subtree is left.
114 After all the lists (think: all columns of the table) have been
115 read several values sets will be dispatches and, eventually,
116 several files will be written. If you configure a Type (see above)
117 which needs more than one data source (for example "if_octets"
118 which needs "rx" and "tx") you will need to specify more than one
119 (two, in the example case) OIDs with the Values option. This has
120 nothing to do with the Table setting.
121 For example, if you want to query the number of users on a system,
123 you can use "HOST-RESOURCES-MIB::hrSystemNumUsers.0". This is one
124 value and belongs to one value list, therefore Table must be set to
125 false. Please note that, in this case, you have to include the
126 sequence number (zero in this case) in the OID.
127 Counter example: If you want to query the interface table provided
129 by the "IF-MIB", e. g. the bytes transmitted. There are potentially
130 many interfaces, so you will want to set Table to true. Because the
131 "if_octets" type needs two values, received and transmitted bytes,
132 you need to specify two OIDs in the Values setting, in this case
133 likely "IF-MIB::ifHCInOctets" and "IF-MIB::ifHCOutOctets". But,
134 this is because of the Type setting, not the Table setting.
135 Since the semantic of Instance and Values depends on this setting
137 you need to set it before setting them. Doing vice verse will
138 result in undefined behavior.
139 Instance Instance
141 Sets the type-instance of the values that are dispatched. The
142 meaning of this setting depends on whether Table is set to true or
143 false:
144 If Table is set to true, Instance is interpreted as an SNMP-prefix
146 that will return a list of values. Those values are then used as
147 the actual type-instance. An example would be the "IF-MIB::ifDescr"
148 subtree. variables(5) from the SNMP distribution describes the
149 format of OIDs.
150 If Table is set to true and Instance is omitted, then "SUBID" will
152 be used as the instance.
153 If Table is set to false the actual string configured for Instance
155 is copied into the value-list. In this case Instance may be empty,
156 i. e. "".
157 InstancePrefix String
159 If Table is set to true, you may feel the need to add something to
160 the instance of the files. If set, String is prepended to the
161 instance as determined by querying the agent. When Table is set to
162 false this option has no effect.
163 The "UPS-MIB" is an example where you need this setting: It has
165 voltages of the inlets, outlets and the battery of an UPS. However,
166 it doesn't provide a descriptive column for these voltages. In this
167 case having 1, 2, ... as instances is not enough, because the inlet
168 voltages and outlet voltages may both have the subids 1, 2, ... You
169 can use this setting to distinguish between the different voltages.
170 Values OID [OID ...]
172 Configures the values to be queried from the SNMP host. The meaning
173 slightly changes with the Table setting. variables(5) from the SNMP
174 distribution describes the format of OIDs.
175 If Table is set to true, each OID must be the prefix of all the
177 values to query, e. g. "IF-MIB::ifInOctets" for all the counters of
178 incoming traffic. This subtree is walked (using "GETNEXT") until a
179 value from outside the subtree is returned.
180 If Table is set to false, each OID must be the OID of exactly one
182 value, e. g. "IF-MIB::ifInOctets.3" for the third counter of
183 incoming traffic.
184 Scale Value
186 The gauge-values returned by the SNMP-agent are multiplied by
187 Value. This is useful when values are transferred as a fixed point
188 real number. For example, thermometers may transfer 243 but
189 actually mean 24.3, so you can specify a scale value of 0.1 to
190 correct this. The default value is, of course, 1.0.
191 This value is not applied to counter-values.
193 Shift Value
195 Value is added to gauge-values returned by the SNMP-agent after
196 they have been multiplied by any Scale value. If, for example, a
197 thermometer returns degrees Kelvin you could specify a shift of
198 273.15 here to store values in degrees Celsius. The default value
199 is, of course, 0.0.
200 This value is not applied to counter-values.
202 Ignore Value [, Value ...]
204 The ignore values allows one to ignore Instances based on their
205 name and the patterns specified by the various values you've
206 entered. The match is a glob-type shell matching.
207 InvertMatch true|false(default)
209 The invertmatch value should be use in combination of the Ignore
210 option. It changes the behaviour of the Ignore option, from a
211 blacklist behaviour when InvertMatch is set to false, to a
212 whitelist when specified to true.
213 The Host block
215 The Host block defines which hosts to query, which SNMP community and
216 version to use and which of the defined Data to query.
217 The argument passed to the Host block is used as the hostname in the
219 data stored by collectd.
220 Address IP-Address|Hostname
222 Set the address to connect to. Address may include transport
223 specifier and/or port number.
224 Version 1|2|3
226 Set the SNMP version to use. When giving 2 version "2c" is actually
227 used.
228 Community Community
230 Pass Community to the host. (Ignored for SNMPv3).
231 Username Username
233 Sets the Username to use for SNMPv3 security.
234 SecurityLevel authPriv|authNoPriv|noAuthNoPriv
236 Selects the security level for SNMPv3 security.
237 Context Context
239 Sets the Context for SNMPv3 security.
240 AuthProtocol MD5|SHA
242 Selects the authentication protocol for SNMPv3 security.
243 AuthPassphrase Passphrase
245 Sets the authentication passphrase for SNMPv3 security.
246 PrivacyProtocol AES|DES
248 Selects the privacy (encryption) protocol for SNMPv3 security.
249 PrivacyPassphrase Passphrase
251 Sets the privacy (encryption) passphrase for SNMPv3 security.
252 Collect Data [Data ...]
254 Defines which values to collect. Data refers to one of the Data
255 block above. Since the config file is read top-down you need to
256 define the data before using it here.
257 Interval Seconds
259 Collect data from this host every Seconds seconds. This option is
260 meant for devices with not much CPU power, e. g. network equipment
261 such as switches, embedded devices, rack monitoring systems and so
262 on. Since the Step of generated RRD files depends on this setting
263 it's wise to select a reasonable value once and never change it.
264 Timeout Seconds
266 How long to wait for a response. The "Net-SNMP" library default is
267 1 second.
268 Retries Integer
270 The number of times that a query should be retried after the
271 Timeout expires. The "Net-SNMP" library default is 5.
272
274 collectd(1), collectd.conf(5), snmpget(1), snmpgetnext(1),
275 variables(5), unix(7)
276
278 Florian Forster <octo@collectd.org> Michael Pilat <mike@mikepilat.com>
2795.8.0.145.gca1cb27 2018-10-23 COLLECTD-SNMP(5)