1Munin::Plugin::SNMP(3)User Contributed Perl DocumentationMunin::Plugin::SNMP(3)
2
6 Munin::Plugin::SNMP - Net::SNMP subclass for Munin plugins
7
9 The Munin::Plugin::SNMP module extends Net::SNMP with methods useful
10 for Munin plugins.
11
13 SNMP plugins (that use this module) share a common configuration
14 interface implemented in the function session(). Please see the
15 documentation for that function for complete instructions and examples
16 on how to configure SNMP. The documentation is located there to ensure
17 that it is up to date and matches the code.
18
20 Additional debugging messages can be enabled by setting
21 $Munin::Plugin::SNMP::DEBUG, $Munin::Plugin::DEBUG, or by exporting the
22 "MUNIN_DEBUG" environment variable before running the plugin (by
23 passing the "--pidebug" option to "munin-run", for instance).
24
26 config_session() - Decode environment to get the needed plugin
27 configuration parameters
28 ($host, $port, $version, $tail) = Munin::Plugin::SNMP->config_session();
29 This is a convenience function for the "config" part of the plugin - it
31 decodes the environment/plugin name to retrieve the information needed
32 in the configuration phase. It returns a 4 tuple consisting of:
33 1) the host name
35 2) the udp port to use
36 3) the SNMP version to use (3 for version 3, 2 for version 1 or 2c)
37 4) the tail of the plugin name: whatever is left of the plugin name
38 after "snmp_<host>_".
39 The tail can be interesting for the "fetch" part of the plugin as well.
41 session([optional Net::SNMP options]) - create new Munin::Plugin::SNMP
43 object
44 $session = Munin::Plugin::SNMP->session();
45 This method overrides the Net::SNMP constructor to get the connection
47 information from the plugin name and/or environment. Please note that
48 no error string is returned. The function handles errors internaly -
49 giving a error message and calling die. Calling die is the right thing
50 to do.
51 The host name is taken from the plugin symlink, which must be on the
53 form "snmp[v3]_<hostname>_<plugin_name>[_args]".
54 The "v3" form is taken to mean that SNMPv3 is to be used. It is also a
56 name trick providing a separate "namespace" for devices that use SNMPv3
57 so it can be configured separately in munin/plugin-conf.d/ files.
58 E.g.:
59 [snmp_*]
61 env.version 2
62 env.community public
63 [snmpv3_*]
65 env.v3username snmpoperator
66 env.v3authpassword s3cr1tpa55w0rd
67 See below for how to configure for each different case. The first case
69 above shows Munin's default configuration.
70 NOTE: munin-node-configure does not yet utilize the "v3" thing.
72 The following environment variables are consulted:
74 env.host
76 If the plugin name (symlink) does not contain the host name this is
77 used as the host name to connect to.
78 The host name must be specified, but is usually specified in the
80 plugin name. If the hostname somehow does not resolve in DNS (or
81 the hosts file) it is possible to do this:
82 [snmp_*]
84 env.version 2c
85 env.community floppa
86 [snmp_switch1.langfeldt.net]
88 env.host 192.168.2.45
89 [snmp_switch2.langfeldt.net]
91 env.host 192.168.2.46
92 env.port
94 The port to connect to. Default 161.
95 env.timeout
97 The timeout in seconds to use. Default 5.
98 env.version
100 The SNMP version to use for the connection. One of 1, 2, 3, snmpv1,
101 snmpv2c or snmpv3. SNMP v2 is better as it supports bulk
102 operations. Therefore 2 is the default in Munin::Plugin::SNMP. If
103 your device supports v3 that may be even better as it supports
104 proper security - but the encryption may slow things down.
105 Security is handled differently for versions 1/2c and 3. See
107 below.
108 env.community
110 The community name for version 1 and 2c agents. The default is
111 'public'. If this works your device is probably very insecure and
112 needs a security checkup.
113 SNMP 3 authentication
115 SNMP v3 has three security levels: "noAuthNoPriv". If a username
116 and password is given it goes up to "authNoPriv".
117 If privpassword is given the security level becomes "authPriv" -
119 the connection is authenticated and encrypted.
120 Note: Encryption can slow down slow or heavily loaded network
122 devices. For most uses authNoPriv will be secure enough --- in
123 SNMP v3 the password is sent over the network encrypted in any
124 case.
125 Munin::Plugin::SNMP does not support ContextEngineIDs and such for
127 authentication/privacy. If you see the need and know how it should
128 be done please send patches!
129 For further reading on SNMP v3 security models please consult
131 RFC3414 and the documentation for Net::SNMP.
132 If version is set to 3 or snmpv3 these variables are used to define
134 authentication:
135 env.v3username
137 SNMPv3 username. There is no default. Empty username ('') is
138 allowed.
139 env.v3authpassword
141 SNMPv3 authentication password. Optional when encryption is
142 also enabled, in which case defaults to the privacy password.
143 Authentication requires a v3authprotocol, but this defaults to
144 "md5" and may therefore be left unspecified.
145 The password is sent encrypted (one way hash) over the network.
147 env.v3authprotocol
149 SNMPv3 authentication protocol. One of 'md5' or 'sha'
150 (HMAC-MD5-96, RFC1321 and SHA-1/HMAC-SHA-96, NIST FIPS PIB 180,
151 RFC2264). The default is 'md5'.
152 env.v3privpassword
154 SNMPv3 privacy password to enable encryption. An empty ('')
155 password is considered as no password and will not enable
156 encryption.
157 Privacy requires a v3privprotocol as well as a v3authprotocol
159 and a v3authpassword, but all of these are defaulted (to 'des',
160 'md5', and the v3privpassword value, respectively) and may
161 therefore be left unspecified.
162 env.v3privprotocol
164 If the v3privpassword is set this setting controls what kind of
165 encryption is used to achive privacy in the session. Only the
166 very weak 'des' encryption method is supported officially. The
167 default is 'des'.
168 The implementing perl module (Net::SNMP) also supports '3des'
170 (CBC-3DES-EDE aka Triple-DES, NIST FIPS 46-3) as specified in
171 IETF draft-reeder-snmpv3-usm-3desede. Whether or not this
172 works with any particular device, we do not know.
173 get_hash() - retrieve a table as a hash of hashes
175 $result = $session->get_hash(
176 [-callback => sub {},] # non-blocking
177 [-delay => $seconds,] # non-blocking
178 [-contextengineid => $engine_id,] # v3
179 [-contextname => $name,] # v3
180 -baseoid => $oid,
181 -cols => \%columns
182 );
183 This method transforms the -baseoid and -cols to a array of -columns
185 and calls "get_entries()" with all the other arguments. It then
186 transforms the data into a hash of hashes in the following manner:
187 The keys of the main hash are the last element(s) of the OIDs, after
189 $oid and the matching keys from %columns are removed. The values are
190 hashes with keys corresponding to the values of %columns hash and
191 values from the subtables corresonding to the keys of %columns.
192 For this to work, all the keys of "-cols" must have the same number of
194 elements. Also, don't try to specify a next-to-next-to-leaf-node
195 baseoid, the principle it breaks both "get_entries" and the logic in
196 "get_hash".
197 If (all) the OIDs are unavailable a defined but empty hashref is
199 returned.
200 Example:
202 $session->get_hash(
204 -baseoid => '1.3.6.1.2.1.2.2.1', # IF-MIB
205 -cols => {
206 1 => 'index',
207 2 => 'descr',
208 4 => 'mtu',
209 }
210 );
211 given the following SNMP table:
213 IF-MIB::ifIndex.1 = INTEGER: 1
215 IF-MIB::ifIndex.2 = INTEGER: 2
216 IF-MIB::ifDescr.1 = STRING: lo0
217 IF-MIB::ifDescr.2 = STRING: lna0
218 IF-MIB::ifType.1 = INTEGER: softwareLoopback(24)
219 IF-MIB::ifType.2 = INTEGER: ethernetCsmacd(6)
220 IF-MIB::ifMtu.1 = INTEGER: 32768
221 IF-MIB::ifMtu.2 = INTEGER: 1500
222 ...
223 will return a hash like this:
225 '1' => {
227 'index' => '1',
228 'mtu' => '32768',
229 'descr' => 'lo0'
230 },
231 '2' => {
232 'index' => '2',
233 'descr' => 'lna0',
234 'mtu' => '1500'
235 }
236 get_single() - Retrieve a single value by OID
238 $uptime = $session->get_single("1.3.6.1.2.1.1.3.0") || 'U';
239 If the call fails to get a value the above call sets $uptime to 'U'
241 which Munin interprets as "Undefined" and handles accordingly.
242 If you stop to think about it you should probably use "get_hash()" (it
244 gets too much, but is good for arrays) or "get_entries()" - it gets
245 exactly what you want, so you mus
246 get_by_regex() - Retrive table of values filtered by regex applied to the
248 value
249 This example shows the usage for a netstat plugin.
250 my $tcpConnState = "1.3.6.1.2.1.6.13.1.1.";
252 my $connections = $session->get_by_regex($tcpConnState, "[1-9]");
253 It gets all OIDs based at $tcpConnState and only returns the ones that
255 contain a number in the value.
256
258 Lots.
259
261 Ilmari wrote: "get_hash()" doesn't handle tables with sparse indices.
262 Nicolai Langfeldt: Actually I think it does.
264
266 Net::SNMP
267
269 Dagfinn Ilmari Mannsaaker, Nicolai Langfeldt Rune Nordboe Skillingstad
270 added timeout support.
271
273 Copyright (c) 2004-2009 Dagfinn Ilmari Mannsaaker and Nicolai
274 Langfeldt.
275 All rights reserved. This program is free software; you can
277 redistribute it and/or modify it under the terms of the GNU General
278 Public License as published by the Free Software Foundation; version 2
279 dated June, 1991.
280perl v5.12.2 2010-12-05 Munin::Plugin::SNMP(3)