1Munin::Plugin::SNMP(3)User Contributed Perl DocumentationMunin::Plugin::SNMP(3)
2
3
4

NAME

6       Munin::Plugin::SNMP - Net::SNMP subclass for Munin plugins
7

SYNOPSIS

9       The Munin::Plugin::SNMP module extends Net::SNMP with methods useful
10       for Munin plugins.
11

SNMP CONFIGURATION

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

DEBUGGING

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

METHODS

26   config_session() - Decode environment to get the needed plugin
27       configuration parameters
28         ($host, $port, $version, $tail) = Munin::Plugin::SNMP->config_session();
29
30       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
34       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
40       The tail can be interesting for the "fetch" part of the plugin as well.
41
42   session([optional Net::SNMP options]) - create new Munin::Plugin::SNMP
43       object
44         $session = Munin::Plugin::SNMP->session();
45
46       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
52       The host name is taken from the plugin symlink, which must be on the
53       form "snmp[v3]_<hostname>_<plugin_name>[_args]".
54
55       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
60         [snmp_*]
61            env.version 2
62            env.community public
63
64         [snmpv3_*]
65            env.v3username snmpoperator
66            env.v3authpassword s3cr1tpa55w0rd
67
68       See below for how to configure for each different case.  The first case
69       above shows Munin's default configuration.
70
71       NOTE: munin-node-configure does not yet utilize the "v3" thing.
72
73       The following environment variables are consulted:
74
75       "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
79           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
83             [snmp_*]
84                env.version 2c
85                env.community floppa
86
87             [snmp_switch1.langfeldt.net]
88                env.host 192.168.2.45
89
90             [snmp_switch2.langfeldt.net]
91                env.host 192.168.2.46
92
93       "env.port"
94           The port to connect to.  Default 161.
95
96       "env.timeout"
97           The timeout in seconds to use. Default 5.
98
99       "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
104       "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
111           Security is handled differently for versions 1/2c and 3.  See
112           below.
113
114       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
120       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
128           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
132           "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
136           For further reading on SNMP v3 security models please consult
137           RFC3414 and the documentation for Net::SNMP.
138
139           If version is set to 3 or snmpv3 the following variables are used
140           to define authentication:
141
142           "env.v3username"
143               Username.  There is no default.
144
145           "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
151           "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
156           "env.v3privpassword"
157               Privacy password to enable encryption.  An empty ('') password
158               is considered as no password and will not enable encryption.
159
160               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
165           "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
171               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
176   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
186       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
190       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
195       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
200       If (all) the OIDs are unavailable a defined but empty hashref is
201       returned.
202
203       Example:
204
205         $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
214       given the following SNMP table:
215
216         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
226       will return a hash like this:
227
228         '1' => {
229                 'index' => '1',
230                 'mtu' => '32768',
231                 'descr' => 'lo0'
232                },
233         '2' => {
234                 'index' => '2',
235                 'descr' => 'lna0',
236                 'mtu' => '1500'
237                }
238
239   get_single() - Retrieve a single value by OID
240         $uptime = $session->get_single("1.3.6.1.2.1.1.3.0") || 'U';
241
242       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
245       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
249   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
253         my $tcpConnState = "1.3.6.1.2.1.6.13.1.1.";
254         my $connections = $session->get_by_regex($tcpConnState, "[1-9]");
255
256       It gets all OIDs based at $tcpConnState and only returns the ones that
257       contain a number in the value.
258

TODO

260       Lots.
261

BUGS

263       Ilmari wrote: get_hash() doesn't handle tables with sparse indices.
264
265       Nicolai Langfeldt: Actually I think it does.
266

SEE ALSO

268       Net::SNMP
269

AUTHOR

271       Dagfinn Ilmari Mannsåker, Nicolai Langfeldt Rune Nordbøe Skillingstad
272       added timeout support.
273

COPYRIGHT/License.

275       Copyright (c) 2004-2009 Dagfinn Ilmari Mannsåker and Nicolai Langfeldt.
276
277       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.
281
282
283
284perl v5.36.1                      2023-11-06            Munin::Plugin::SNMP(3)
Impressum