1Net_SNMP_util(3) User Contributed Perl Documentation Net_SNMP_util(3)
2
6 Net_SNMP_util - SNMP utilities based on Net::SNMP
7
9 The Net_SNMP_util module implements SNMP utilities using the Net::SNMP
10 module. It implements snmpget, snmpgetnext, snmpwalk, snmpset,
11 snmptrap, and snmpgetbulk. The Net_SNMP_util module assumes that the
12 user has a basic understanding of the Simple Network Management
13 Protocol and related network management concepts.
14
16 The Net_SNMP_util module simplifies SNMP queries even more than
17 Net::SNMP alone. Easy-to-use "get", "getnext", "walk", "set", "trap",
18 and "getbulk" routines are provided, hiding all the details of a SNMP
19 query.
20
22 host Parameter
23 SNMP parameters can be specified as part of the hostname/ip address
24 passed as the first argument. The syntax is
25 community@host:port:timeout:retries:backoff:version
27 If the community is left off, it defaults to "public". If the port
29 is left off, it defaults to 161 for everything but snmptrap(). The
30 snmptrap() routine uses a default port of 162. Timeout and retries
31 defaults to whatever Net::SNMP uses, currently 5.0 seconds and 1
32 retry (2 tries total). The backoff parameter is currently
33 unimplemented. The version parameter defaults to SNMP version 1.
34 Some SNMP values such as 64-bit counters have to be queried using
35 SNMP version 2. Specifying "2" or "2c" as the version parameter
36 will accomplish this. The snmpgetbulk routine is only supported in
37 SNMP version 2 and higher. Additional security features are
38 available under SNMP version 3.
39 Some machines have additional security features that only allow
41 SNMP queries to come from certain IP addresses. If the host doing
42 the query has multiple interfaces, it may be necessary to specify
43 the interface the query should come from. The port parameter is
44 further broken down into
45 remote_port!local_address!local_port
47 Here are some examples:
49 somehost
51 somehost:161
52 somehost:161!192.168.2.4!4000 use 192.168.2.4 and port 4000 as source
53 somehost:!192.168.2.4 use 192.168.2.4 as source
54 somehost:!!4000 use port 4000 as source
55 Most people will only need to use the first form ("somehost").
57 OBJECT IDENTIFIERs
59 To further simplify SNMP queries, the query routines use a small
60 table that maps the textual representation of OBJECT IDENTIFIERs to
61 their dotted notation. The OBJECT IDENTIFIERs from RFC1213 (MIB-
62 II) and RFC1315 (Frame Relay) are preloaded. This allows OBJECT
63 IDENTIFIERs like "ifInOctets.4" to be used instead of the more
64 cumbersome "1.3.6.1.2.1.2.2.1.10.4".
65 Several functions are provided to manage the mapping table.
67 Mapping entries can be added directly, SNMP MIB files can be read,
68 and a cache file with the text-to-OBJECT-IDENTIFIER mappings are
69 maintained. By default, the file "OID_cache.txt" is loaded, but it
70 can by changed by setting the variable $Net_SNMP_util::CacheFile to
71 the desired file name. The functions to manipulate the mappings
72 are:
73 snmpmapOID Add a textual OID mapping directly
75 snmpMIB_to_OID Read a SNMP MIB file
76 snmpLoad_OID_Cache Load an OID-mapping cache file
77 snmpQueue_MIB_File Queue a SNMP MIB file for loading on demand
78 Net::SNMP extensions
80 This module is built on top of Net::SNMP. Net::SNMP has a
81 different method of specifying SNMP parameters. To support this
82 different method, this module will accept an optional hash
83 reference containing the SNMP parameters. The hash may contain the
84 following:
85 [-port => $port,]
87 [-localaddr => $localaddr,]
88 [-localport => $localport,]
89 [-version => $version,]
90 [-domain => $domain,]
91 [-timeout => $seconds,]
92 [-retries => $count,]
93 [-maxmsgsize => $octets,]
94 [-debug => $bitmask,]
95 [-community => $community,] # v1/v2c
96 [-username => $username,] # v3
97 [-authkey => $authkey,] # v3
98 [-authpassword => $authpasswd,] # v3
99 [-authprotocol => $authproto,] # v3
100 [-privkey => $privkey,] # v3
101 [-privpassword => $privpasswd,] # v3
102 [-privprotocol => $privproto,] # v3
103 [-contextengineid => $engine_id,] # v3
104 [-contextname => $name,] # v3
105 Please see the documentation for Net::SNMP for a description of
107 these parameters.
108 SNMPv3 Arguments
110 A SNMP context is a collection of management information accessible
111 by a SNMP entity. An item of management information may exist in
112 more than one context and a SNMP entity potentially has access to
113 many contexts. The combination of a contextEngineID and a
114 contextName unambiguously identifies a context within an
115 administrative domain. In a SNMPv3 message, the contextEngineID
116 and contextName are included as part of the scopedPDU. All methods
117 that generate a SNMP message optionally take a -contextengineid and
118 -contextname argument to configure these fields.
119 Context Engine ID
121 The -contextengineid argument expects a hexadecimal string
122 representing the desired contextEngineID. The string must be
123 10 to 64 characters (5 to 32 octets) long and can be prefixed
124 with an optional "0x". Once the -contextengineid is specified
125 it stays with the object until it is changed again or reset to
126 default by passing in the undefined value. By default, the
127 contextEngineID is set to match the authoritativeEngineID of
128 the authoritative SNMP engine.
129 Context Name
131 The contextName is passed as a string which must be 0 to 32
132 octets in length using the -contextname argument. The
133 contextName stays with the object until it is changed. The
134 contextName defaults to an empty string which represents the
135 "default" context.
136
138 snmpget() - send a SNMP get-request to the remote agent
139 @result = snmpget(
140 [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
141 [\%param_hash],
142 @oids
143 );
144 This function performs a SNMP get-request query to gather data from the
146 remote agent on the host specified. The message is built using the
147 list of OBJECT IDENTIFIERs passed as an array. Each OBJECT IDENTIFIER
148 is placed into a single SNMP GetRequest-PDU in the same order that it
149 held in the original list.
150 The requested values are returned in an array in the same order as they
152 were requested. In scalar context the first requested value is
153 returned.
154 snmpgetnext() - send a SNMP get-next-request to the remote agent
156 @result = snmpgetnext(
157 [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
158 [\%param_hash],
159 @oids
160 );
161 This function performs a SNMP get-next-request query to gather data
163 from the remote agent on the host specified. The message is built
164 using the list of OBJECT IDENTIFIERs passed as an array. Each OBJECT
165 IDENTIFIER is placed into a single SNMP GetNextRequest-PDU in the same
166 order that it held in the original list.
167 The requested values are returned in an array in the same order as they
169 were requested. The OBJECT IDENTIFIER number is added as a prefix to
170 each value using a colon as a separator, like
171 '1.3.6.1.2.1.2.2.1.2.1:ethernet'. In scalar context the first
172 requested value is returned.
173 snmpgetbulk() - send a SNMP get-bulk-request to the remote agent
175 @result = snmpgetbulk(
176 [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
177 $nonrepeaters,
178 $maxrepetitions,
179 [\%param_hash],
180 @oids
181 );
182 This function performs a SNMP get-bulk-request query to gather data
184 from the remote agent on the host specified.
185 • The $nonrepeaters value specifies the number of variables in the
187 @oids list for which a single successor is to be returned. If it
188 is null or undefined, a value of 0 is used.
189 • The $maxrepetitions value specifies the number of successors to be
191 returned for the remaining variables in the @oids list. If it is
192 null or undefined, the default value of 12 is used.
193 • The message is built using the list of OBJECT IDENTIFIERs passed as
195 an array. Each OBJECT IDENTIFIER is placed into a single SNMP
196 GetNextRequest-PDU in the same order that it held in the original
197 list.
198 The requested values are returned in an array in the same order as they
200 were requested.
201 NOTE: This function can only be used when the SNMP version is set to
203 SNMPv2c or SNMPv3.
204 snmpwalk() - walk OBJECT IDENTIFIER tree(s) on the remote agent
206 @result = snmpwalk(
207 [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
208 [\%param_hash],
209 @oids
210 );
211 This function performs a sequence of SNMP get-next-request or get-bulk-
213 request (if the SNMP version is 2 or higher) queries to gather data
214 from the remote agent on the host specified. The initial message is
215 built using the list of OBJECT IDENTIFIERs passed as an array. Each
216 OBJECT IDENTIFIER is placed into a single SNMP GetNextRequest-PDU in
217 the same order that it held in the original list. Queries continue
218 until all the returned OBJECT IDENTIFIERs are no longer a child of the
219 base OBJECT IDENTIFIERs.
220 The requested values are returned in an array in the same order as they
222 were requested. The OBJECT IDENTIFIER number is added as a prefix to
223 each value using a colon as a separator, like
224 '1.3.6.1.2.1.2.2.1.2.1:ethernet'. If only one OBJECT IDENTIFIER is
225 requested, just the "instance" part of the OBJECT IDENTIFIER is added
226 as a prefix, like '1:ethernet', '2:ethernet', '3:fddi'.
227 snmpset() - send a SNMP set-request to the remote agent
229 @result = snmpset(
230 [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
231 [\%param_hash],
232 $oid1, $type1, $value1,
233 [$oid2, $type2, $value2 ...]
234 );
235 This function is used to modify data on the remote agent using a SNMP
237 set-request. The message is built using the list of values consisting
238 of groups of an OBJECT IDENTIFIER, an object type, and the actual value
239 to be set. The object type can be one of the following strings:
240 integer | int
242 string | octetstring | octet string
243 oid | object id | object identifier
244 ipaddr | ip addr4ess
245 timeticks
246 uint | uinteger | uinteger32 | unsigned int | unsigned integer | unsigned integer32
247 counter | counter 32
248 counter64
249 gauge | gauge32
250 The object type may also be an octet corresponding to the ASN.1 type.
252 See the Net::SNMP documentation for more information.
253 The requested values are returned in an array in the same order as they
255 were requested. In scalar context the first requested value is
256 returned.
257 snmptrap() - send a SNMP trap to the remote manager
259 @result = snmptrap(
260 [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
261 $enterprise,
262 $agentaddr,
263 $generictrap,
264 $specifictrap,
265 [\%param_hash],
266 $oid1, $type1, $value1,
267 [$oid2, $type2, $value2 ...]
268 );
269 This function sends a SNMP trap to the remote manager on the host
271 specified. The message is built using the list of values consisting of
272 groups of an OBJECT IDENTIFIER, an object type, and the actual value to
273 be set. The object type can be one of the following strings:
274 integer | int
276 string | octetstring | octet string
277 oid | object id | object identifier
278 ipaddr | ip addr4ess
279 timeticks
280 uint | uinteger | uinteger32 | unsigned int | unsigned integer | unsigned integer32
281 counter | counter 32
282 counter64
283 gauge | gauge32
284 The object type may also be an octet corresponding to the ASN.1 type.
286 See the Net::SNMP documentation for more information.
287 A true value is returned if sending the trap is successful. The
289 undefined value is returned when a failure has occurred.
290 When the trap is sent as SNMPv2c, the $enterprise, $agentaddr,
292 $generictrap, and $specifictrap arguments are ignored. Furthermore,
293 the first two (oid, type, value) tuples should be:
294 • sysUpTime.0 - ('1.3.6.1.2.1.1.3.0', 'timeticks', $timeticks)
296 • snmpTrapOID.0 - ('1.3.6.1.6.3.1.1.4.1.0', 'oid', $oid)
298 NOTE: This function can only be used when the SNMP version is set to
300 SNMPv1 or SNMPv2c.
301 snmpmaptable() - walk OBJECT IDENTIFIER tree(s) on the remote agent
303 $result = snmpmaptable(
304 [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
305 \&function,
306 [\%param_hash],
307 @oids
308 );
309 This function performs a sequence of SNMP get-next-request or get-bulk-
311 request (if the SNMP version is 2 or higher) queries to gather data
312 from the remote agent on the host specified. The initial message is
313 built using the list of OBJECT IDENTIFIERs passed as an array. Each
314 OBJECT IDENTIFIER is placed into a single SNMP GetNextRequest-PDU in
315 the same order that it held in the original list. Queries continue
316 until all the returned OBJECT IDENTIFIERs are no longer a child of the
317 base OBJECT IDENTIFIERs. The OBJECT IDENTIFIERs must correspond to
318 column entries for a conceptual row in a table. They may however be
319 columns in different tables as long as each table is indexed the same
320 way.
321 • The \&function argument will be called once per row of the table.
323 It will be passed the row index as a partial OBJECT IDENTIFIER in
324 dotted notation, e.g. "1.3" or "10.0.1.34", and the values of the
325 requested table columns in that row.
326 The number of rows in the table is returned on success. The undefined
328 value is returned when a failure has occurred.
329 snmpmaptable4() - walk OBJECT IDENTIFIER tree(s) on the remote agent
331 $result = snmpmaptable4(
332 [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
333 \&function,
334 $maxrepetitions,
335 [\%param_hash],
336 @oids
337 );
338 This function performs a sequence of SNMP get-next-request or get-bulk-
340 request (if the SNMP version is 2 or higher) queries to gather data
341 from the remote agent on the host specified. The initial message is
342 built using the list of OBJECT IDENTIFIERs passed as an array. Each
343 OBJECT IDENTIFIER is placed into a single SNMP GetNextRequest-PDU in
344 the same order that it held in the original list. Queries continue
345 until all the returned OBJECT IDENTIFIERs are no longer a child of the
346 base OBJECT IDENTIFIERs. The OBJECT IDENTIFIERs must correspond to
347 column entries for a conceptual row in a table. They may however be
348 columns in different tables as long as each table is indexed the same
349 way.
350 • The \&function argument will be called once per row of the table.
352 It will be passed the row index as a partial OBJECT IDENTIFIER in
353 dotted notation, e.g. "1.3" or "10.0.1.34", and the values of the
354 requested table columns in that row.
355 • The $maxrepetitions argument specifies the number of rows to be
357 returned by a single get-bulk-request. If it is null or undefined,
358 the default value of 12 is used.
359 The number of rows in the table is returned on success. The undefined
361 value is returned when a failure has occurred.
362 snmpwalkhash() - send a SNMP get-next-request to the remote agent
364 @result = snmpwalkhash(
365 [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
366 \&function(),
367 [\%param_hash],
368 @oids,
369 [\%hash]
370 );
371 This function performs a sequence of SNMP get-next-request or get-bulk-
373 request (if the SNMP version is 2 or higher) queries to gather data
374 from the remote agent on the host specified. The message is built
375 using the list of OBJECT IDENTIFIERs passed as an array. Each OBJECT
376 IDENTIFIER is placed into a single SNMP GetNextRequest-PDU in the same
377 order that it held in the original list. Queries continue until all
378 the returned OBJECT IDENTIFIERs are outside of the tree specified by
379 the initial OBJECT IDENTIFIERs.
380 The \&function is called once for every returned value. It is passed a
382 reference to a hash, the hostname, the textual OBJECT IDENTIFIER, the
383 dotted-numberic OBJECT IDENTIFIER, the instance, the value and the
384 requested textual OBJECT IDENTIFIER. That function can customize the
385 result so the values can be extracted later by hosts, by oid_names, by
386 oid_numbers, by instances... like these:
387 $hash{$host}{$name}{$inst} = $value;
389 $hash{$host}{$oid}{$inst} = $value;
390 $hash{$name}{$inst} = $value;
391 $hash{$oid}{$inst} = $value;
392 $hash{$oid . '.' . $ints} = $value;
393 $hash{$inst} = $value;
394 ...
395 If the last argument to snmpwalkhash is a reference to a hash, that
397 hash reference is passed to the passed-in function instead of a local
398 hash reference. That way the function can look up other objects
399 unrelated to the current invocation of snmpwalkhash.
400 The snmpwalkhash routine returns the hash.
402 snmpmapOID() - add textual OBJECT INDENTIFIER mapping
404 snmpmapOID(
405 $text1, $oid1,
406 [ $text2, $oid2 ...]
407 );
408 This routine adds entries to the table that maps textual representation
410 of OBJECT IDENTIFIERs to their dotted notation. For example,
411 snmpmapOID('ciscoCPU', '1.3.6.1.4.1.9.9.109.1.1.1.1.5.1');
413 allows the string 'ciscoCPU' to be used as an OBJECT IDENTIFIER in any
415 SNMP query routine.
416 This routine doesn't return anything.
418 snmpLoad_OID_Cache() - Read a file of cached OID mappings
420 $result = snmpLoad_OID_Cache(
421 $file
422 );
423 This routine opens the file named by the $file argument and reads it.
425 The file should contain text, OBJECT IDENTIFIER pairs, one pair per
426 line. It adds the pairs as entries to the table that maps textual
427 representation of OBJECT IDENTIFIERs to their dotted notation. Blank
428 lines and anything after a '#' or between '--' is ignored.
429 This routine returns 0 on success and -1 if the $file could not be
431 opened.
432 snmpMIB_to_OID() - Read a MIB file for textual OID mappings
434 $result = snmpMIB_to_OID(
435 $file
436 );
437 This routine opens the file named by the $file argument and reads it.
439 The file should be an SNMP Management Information Base (MIB) file that
440 describes OBJECT IDENTIFIERs supported by an SNMP agent. per line. It
441 adds the textual representation of the OBJECT IDENTIFIERs to the text-
442 to-OID mapping table.
443 This routine returns the number of entries added to the table or -1 if
445 the $file could not be opened.
446 snmpQueue_MIB_File() - queue a MIB file for reading "on demand"
448 snmpQueue_MIB_File(
449 $file1,
450 [$file2, ...]
451 );
452 This routine queues the list of SNMP MIB files for later processing.
454 Whenever a text-to-OBJECT IDENTIFIER lookup fails, the list of queued
455 MIB files is consulted. If it isn't empty, the first MIB file in the
456 list is removed and passed to snmpMIB_to_OID(). The lookup is
457 attempted again, and if that still fails the next MIB file in the list
458 is removed and passed to snmpMIB_to_OID(). This process continues until
459 the lookup succeeds or the list is exhausted.
460 This routine doesn't return anything.
462
464 The Net_SNMP_util module uses the Exporter module to export useful
465 constants and subroutines. These exportable symbols are defined below
466 and follow the rules and conventions of the Exporter module (see
467 Exporter).
468 Exportable
470 &snmpget, &snmpgetnext, &snmpgetbulk, &snmpwalk, &snmpset,
471 &snmptrap, &snmpmaptable, &snmpmaptable4, &snmpwalkhash,
472 &snmpmapOID, &snmpMIB_to_OID, &snmpLoad_OID_Cache,
473 &snmpQueue_MIB_File, ErrorMessage
474
476 1. SNMPv1 get-request for sysUpTime
477 This example gets the sysUpTime from a remote host.
478 #! /usr/local/bin/perl
480 use strict;
481 use Net_SNMP_util;
482 my ($host, $ret)
483 $host = shift || 'localhost';
484 $ret = snmpget($host, 'sysUpTime');
485 print("sysUpTime for $host is $ret\n");
487 exit 0;
489 2. SNMPv3 set-request of sysContact
491 This example sets the sysContact information on the remote host to
492 "Help Desk x911". The parameters passed to the snmpset function are
493 for the demonstration of syntax only. These parameters will need to be
494 set according to the SNMPv3 parameters of the remote host used by the
495 script.
496 #! /usr/local/bin/perl
498 use strict;
499 use Net_SNMP_util;
500 my($host, %v3hash, $ret);
501 $host = shift || 'localhost';
502 $v3hash{'-version'} = 'snmpv3';
503 $v3hash{'-username'} = 'myv3Username';
504 $v3hash{'-authkey'} = '0x05c7fbde31916f64da4d5b77156bdfa7';
505 $v3hash{'-authprotocol'} = 'md5';
506 $v3hash{'-privkey'} = '0x93725fd3a02a48ce02df4e065a1c1746';
507 $ret = snmpset($host, \%v3hash, 'sysContact', 'string', 'Help Desk x911');
509 print "sysContact on $host is now $ret\n";
511 exit 0;
512 3. SNMPv2c walk for ifTable
514 This example gets the contents of the ifTable by sending get-bulk-
515 requests until the responses are no longer part of the ifTable. The
516 ifTable can also be retrieved using "snmpmaptable".
517 #! /usr/local/bin/perl
519 use strict;
520 use Net_SNMP_util;
521 my($host, @ret, $oid, $val);
522 $host = shift || 'localhost';
523 @ret = snmpwalk($host . ':::::2', 'ifTable');
525 foreach $val (@ret) {
526 ($oid, $val) = split(':', $val, 2);
527 print "$oid => $val\n";
528 }
529 exit 0;
530 4. SNMPv2c maptable collecting ifDescr, ifInOctets, and ifOutOctets.
532 This example collects a table containing the columns ifDescr,
533 ifInOctets, and ifOutOctets. A printing function is called once per
534 row.
535 #! /usr/local/bin/perl
537 use strict;
538 use Net_SNMP_util;
539 sub printfun($$$$) {
541 my($inst, $desc, $in, $out) = @_;
542 printf "%3d %-52.52s %10d %10d\n", $inst, $desc, $in, $out;
543 }
544 my($host, @ret);
546 $host = shift || 'localhost';
547 printf "%-3s %-52s %10s %10s\n", "Int", "Description", "In", "Out";
549 @ret = snmpmaptable($host . ':::::2', \&printfun,
550 'ifDescr', 'ifInOctets', 'ifOutOctets');
551 exit 0;
553
555 • The Net_SNMP_util module uses syntax that is not supported in
556 versions of Perl earlier than v5.6.0.
557 • The Net_SNMP_util module uses the Net::SNMP module, and as such may
559 depend on other modules. Please see the documentation on Net::SNMP
560 for more information.
561
563 Mike Mitchell <Mike.Mitchell@sas.com>
564
566 The original concept for this module was based on SNMP_Session.pm
567 written by Simon Leinen <simon@switch.ch>
568
570 Copyright (c) 2007 Mike Mitchell. All rights reserved. This program
571 is free software; you may redistribute it and/or modify it under the
572 same terms as Perl itself.
573perl v5.38.0 2023-07-21 Net_SNMP_util(3)