Merge pull request #2796 from elfiesmelfie/feat_ipmi_SEL_ignore_list
[collectd.git] / 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