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 internally -
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.domain"
100 The Transport Domain to use for exchanging SNMP messages. The
101 default is UDP/IPv4. Possible values: 'udp', 'udp4', 'udp/ipv4';
102 'udp6', 'udp/ipv6'; 'tcp', 'tcp4', 'tcp/ipv4'; 'tcp6', 'tcp/ipv6'.
103 "env.version"
105 The SNMP version to use for the connection. One of 1, 2, 3, snmpv1,
106 snmpv2c or snmpv3. SNMP v2 is better as it supports bulk
107 operations. Therefore 2 is the default in "Munin::Plugin::SNMP".
108 If your device supports v3 that may be even better as it supports
109 proper security - but the encryption may slow things down.
110 Security is handled differently for versions 1/2c and 3. See
112 below.
113 SNMP 1/2c authentication
115 "env.community"
116 The community name for version 1 and 2c agents. The default is
117 'public'. If this works your device is probably very insecure and
118 needs a security checkup.
119 SNMP 3 authentication
121 SNMP v3 has three security levels. Lowest is "noAuthNoPriv", which
122 provides neither authentication nor encryption. If a username and
123 "authpassword" are given it goes up to "authNoPriv", and the
124 connection is authenticated. If "privpassword" is given the
125 security level becomes "authPriv" - the connection is authenticated
126 and encrypted.
127 Note: Encryption can slow down slow or heavily loaded network
129 devices. For most uses "authNoPriv" will be secure enough -- the
130 password is sent over the network encrypted in any case.
131 "Munin::Plugin::SNMP" does not support ContextEngineIDs and such
133 for authentication/privacy. If you see the need and know how it
134 should be done please send patches!
135 For further reading on SNMP v3 security models please consult
137 RFC3414 and the documentation for Net::SNMP.
138 If version is set to 3 or snmpv3 the following variables are used
140 to define authentication:
141 "env.v3username"
143 Username. There is no default.
144 "env.v3authpassword"
146 Authentication password. Optional when encryption is also
147 enabled, in which case defaults to the privacy password
148 ("env.v3privpassword"). The password is sent encrypted (one
149 way hash) over the network.
150 "env.v3authprotocol"
152 Authentication protocol. One of 'md5' or 'sha' (HMAC-MD5-96,
153 RFC1321 and SHA-1/HMAC-SHA-96, NIST FIPS PIB 180, RFC2264).
154 The default is 'md5'.
155 "env.v3privpassword"
157 Privacy password to enable encryption. An empty ('') password
158 is considered as no password and will not enable encryption.
159 Privacy requires a v3privprotocol as well as a v3authprotocol
161 and a v3authpassword, but all of these are defaulted (to 'des',
162 'md5', and the v3privpassword value, respectively) and may
163 therefore be left unspecified.
164 "env.v3privprotocol"
166 If the v3privpassword is set this setting controls what kind of
167 encryption is used to achieve privacy in the session. Only the
168 very weak 'des' encryption method is supported officially. The
169 default is 'des'.
170 The implementing perl module (Net::SNMP) also supports '3des'
172 (CBC-3DES-EDE aka Triple-DES, NIST FIPS 46-3) as specified in
173 IETF draft-reeder-snmpv3-usm-3desede. Whether or not this
174 works with any particular device, we do not know.
175 get_hash() - retrieve a table as a hash of hashes
177 $result = $session->get_hash(
178 [-callback => sub {},] # non-blocking
179 [-delay => $seconds,] # non-blocking
180 [-contextengineid => $engine_id,] # v3
181 [-contextname => $name,] # v3
182 -baseoid => $oid,
183 -cols => \%columns
184 );
185 This method transforms the -baseoid and -cols to a array of -columns
187 and calls get_entries() with all the other arguments. It then
188 transforms the data into a hash of hashes in the following manner:
189 The keys of the main hash are the last element(s) of the OIDs, after
191 $oid and the matching keys from %columns are removed. The values are
192 hashes with keys corresponding to the values of %columns hash and
193 values from the subtables corresponding to the keys of %columns.
194 For this to work, all the keys of "-cols" must have the same number of
196 elements. Also, don't try to specify a next-to-next-to-leaf-node
197 baseoid, the principle it breaks both "get_entries" and the logic in
198 "get_hash".
199 If (all) the OIDs are unavailable a defined but empty hashref is
201 returned.
202 Example:
204 $session->get_hash(
206 -baseoid => '1.3.6.1.2.1.2.2.1', # IF-MIB
207 -cols => {
208 1 => 'index',
209 2 => 'descr',
210 4 => 'mtu',
211 }
212 );
213 given the following SNMP table:
215 IF-MIB::ifIndex.1 = INTEGER: 1
217 IF-MIB::ifIndex.2 = INTEGER: 2
218 IF-MIB::ifDescr.1 = STRING: lo0
219 IF-MIB::ifDescr.2 = STRING: lna0
220 IF-MIB::ifType.1 = INTEGER: softwareLoopback(24)
221 IF-MIB::ifType.2 = INTEGER: ethernetCsmacd(6)
222 IF-MIB::ifMtu.1 = INTEGER: 32768
223 IF-MIB::ifMtu.2 = INTEGER: 1500
224 ...
225 will return a hash like this:
227 '1' => {
229 'index' => '1',
230 'mtu' => '32768',
231 'descr' => 'lo0'
232 },
233 '2' => {
234 'index' => '2',
235 'descr' => 'lna0',
236 'mtu' => '1500'
237 }
238 get_single() - Retrieve a single value by OID
240 $uptime = $session->get_single("1.3.6.1.2.1.1.3.0") || 'U';
241 If the call fails to get a value the above call sets $uptime to 'U'
243 which Munin interprets as "Undefined" and handles accordingly.
244 If you stop to think about it you should probably use get_hash() (it
246 gets too much, but is good for arrays) or get_entries() - it gets
247 exactly what you want, so you mus
248 get_by_regex() - Retrieve table of values filtered by regex applied to the
250 value
251 This example shows the usage for a netstat plugin.
252 my $tcpConnState = "1.3.6.1.2.1.6.13.1.1.";
254 my $connections = $session->get_by_regex($tcpConnState, "[1-9]");
255 It gets all OIDs based at $tcpConnState and only returns the ones that
257 contain a number in the value.
258
260 Lots.
261
263 Ilmari wrote: get_hash() doesn't handle tables with sparse indices.
264 Nicolai Langfeldt: Actually I think it does.
266
268 Net::SNMP
269
271 Dagfinn Ilmari Mannsåker, Nicolai Langfeldt Rune Nordbøe Skillingstad
272 added timeout support.
273
275 Copyright (c) 2004-2009 Dagfinn Ilmari Mannsåker and Nicolai Langfeldt.
276 All rights reserved. This program is free software; you can
278 redistribute it and/or modify it under the terms of the GNU General
279 Public License as published by the Free Software Foundation; version 2
280 dated June, 1991.
281perl v5.36.1 2023-11-06 Munin::Plugin::SNMP(3)