1Net::SNMP(3) User Contributed Perl Documentation Net::SNMP(3)
2
6 Net::SNMP - Object oriented interface to SNMP
7
9 The Net::SNMP module implements an object oriented interface to the
10 Simple Network Management Protocol. Perl applications can use the
11 module to retrieve or update information on a remote host using the
12 SNMP protocol. The module supports SNMP version-1, SNMP version-2c
13 (Community-Based SNMPv2), and SNMP version-3. The Net::SNMP module
14 assumes that the user has a basic understanding of the Simple Network
15 Management Protocol and related network management concepts.
16
18 The Net::SNMP module abstracts the intricate details of the Simple
19 Network Management Protocol by providing a high level programming
20 interface to the protocol. Each Net::SNMP object provides a one-to-one
21 mapping between a Perl object and a remote SNMP agent or manager. Once
22 an object is created, it can be used to perform the basic protocol
23 exchange actions defined by SNMP.
24 A Net::SNMP object can be created such that it has either "blocking" or
26 "non-blocking" properties. By default, the methods used to send SNMP
27 messages do not return until the protocol exchange has completed
28 successfully or a timeout period has expired. This behavior gives the
29 object a "blocking" property because the flow of the code is stopped
30 until the method returns.
31 The optional named argument -nonblocking can be passed to the object
33 constructor with a true value to give the object "non-blocking"
34 behavior. A method invoked by a non-blocking object queues the SNMP
35 message and returns immediately, allowing the flow of the code to
36 continue. The queued SNMP messages are not sent until an event loop is
37 entered by calling the "snmp_dispatcher()" method. When the SNMP
38 messages are sent, any response to the messages invokes the subroutine
39 defined by the user when the message was originally queued. The event
40 loop exits when all messages have been removed from the queue by either
41 receiving a response, or by exceeding the number of retries at the
42 Transport Layer.
43 Blocking Objects
45 The default behavior of the methods associated with a Net::SNMP object
46 is to block the code flow until the method completes. For methods that
47 initiate a SNMP protocol exchange requiring a response, a hash
48 reference containing the results of the query is returned. The
49 undefined value is returned by all methods when a failure has occurred.
50 The "error()" method can be used to determine the cause of the failure.
51 The hash reference returned by a SNMP protocol exchange points to a
53 hash constructed from the VarBindList contained in the SNMP response
54 message. The hash is created using the ObjectName and the ObjectSyntax
55 pairs in the VarBindList. The keys of the hash consist of the OBJECT
56 IDENTIFIERs in dotted notation corresponding to each ObjectName in the
57 VarBindList. The value of each hash entry is set equal to the value of
58 the corresponding ObjectSyntax. This hash reference can also be
59 retrieved using the "var_bind_list()" method.
60 Non-blocking Objects
62 When a Net::SNMP object is created having non-blocking behavior, the
63 invocation of a method associated with the object returns immediately,
64 allowing the flow of the code to continue. When a method is invoked
65 that would initiate a SNMP protocol exchange requiring a response,
66 either a true value (i.e. 0x1) is returned immediately or the undefined
67 value is returned if there was a failure. The "error()" method can be
68 used to determine the cause of the failure.
69 The contents of the VarBindList contained in the SNMP response message
71 can be retrieved by calling the "var_bind_list()" method using the
72 object reference passed as the first argument to the callback. The
73 value returned by the "var_bind_list()" method is a hash reference
74 created using the ObjectName and the ObjectSyntax pairs in the
75 VarBindList. The keys of the hash consist of the OBJECT IDENTIFIERs in
76 dotted notation corresponding to each ObjectName in the VarBindList.
77 The value of each hash entry is set equal to the value of the
78 corresponding ObjectSyntax. The undefined value is returned if there
79 has been a failure and the "error()" method may be used to determine
80 the reason.
81
83 When named arguments are expected by the methods, two different styles
84 are supported. All examples in this documentation use the dashed-
85 option style:
86 $object->method(-argument => $value);
88 However, the IO:: style is also allowed:
90 $object->method(Argument => $value);
92 Non-blocking Objects Arguments
94 When a Net::SNMP object has been created with a "non-blocking"
95 property, most methods that generate a SNMP message take additional
96 arguments to support this property.
97 Callback
99 Most methods associated with a non-blocking object have an
100 optional named argument called -callback. The -callback
101 argument expects a reference to a subroutine or to an array
102 whose first element must be a reference to a subroutine. The
103 subroutine defined by the -callback option is executed when a
104 response to a SNMP message is received, an error condition has
105 occurred, or the number of retries for the message has been
106 exceeded.
107 When the -callback argument only contains a subroutine
109 reference, the subroutine is evaluated passing a reference to
110 the original Net::SNMP object as the only parameter. If the
111 -callback argument was defined as an array reference, all
112 elements in the array are passed to subroutine after the
113 reference to the Net::SNMP object. The first element, which is
114 required to be a reference to a subroutine, is removed before
115 the remaining arguments are passed to that subroutine.
116 Once one method is invoked with the -callback argument, this
118 argument stays with the object and is used by any further calls
119 to methods using the -callback option if the argument is
120 absent. The undefined value may be passed to the -callback
121 argument to delete the callback.
122 NOTE: The subroutine being passed with the -callback named
124 argument should not cause blocking itself. This will cause all
125 the actions in the event loop to be stopped, defeating the non-
126 blocking property of the Net::SNMP module.
127 Delay
129 An optional argument -delay can also be passed to non-blocking
130 objects. The -delay argument instructs the object to wait the
131 number of seconds passed to the argument before executing the
132 SNMP protocol exchange. The delay period starts when the event
133 loop is entered. The -delay parameter is applied to all
134 methods associated with the object once it is specified. The
135 delay value must be set back to 0 seconds to disable the delay
136 parameter.
137 SNMPv3 Arguments
139 A SNMP context is a collection of management information accessible
140 by a SNMP entity. An item of management information may exist in
141 more than one context and a SNMP entity potentially has access to
142 many contexts. The combination of a contextEngineID and a
143 contextName unambiguously identifies a context within an
144 administrative domain. In a SNMPv3 message, the contextEngineID
145 and contextName are included as part of the scopedPDU. All methods
146 that generate a SNMP message optionally take a -contextengineid and
147 -contextname argument to configure these fields.
148 Context Engine ID
150 The -contextengineid argument expects a hexadecimal string
151 representing the desired contextEngineID. The string must be
152 10 to 64 characters (5 to 32 octets) long and can be prefixed
153 with an optional "0x". Once the -contextengineid is specified
154 it stays with the object until it is changed again or reset to
155 default by passing in the undefined value. By default, the
156 contextEngineID is set to match the authoritativeEngineID of
157 the authoritative SNMP engine.
158 Context Name
160 The contextName is passed as a string which must be 0 to 32
161 octets in length using the -contextname argument. The
162 contextName stays with the object until it is changed. The
163 contextName defaults to an empty string which represents the
164 "default" context.
165 session() - create a new Net::SNMP object
167 ($session, $error) = Net::SNMP->session(
168 [-hostname => $hostname,]
169 [-port => $port,]
170 [-localaddr => $localaddr,]
171 [-localport => $localport,]
172 [-nonblocking => $boolean,]
173 [-version => $version,]
174 [-domain => $domain,]
175 [-timeout => $seconds,]
176 [-retries => $count,]
177 [-maxmsgsize => $octets,]
178 [-translate => $translate,]
179 [-debug => $bitmask,]
180 [-community => $community,] # v1/v2c
181 [-username => $username,] # v3
182 [-authkey => $authkey,] # v3
183 [-authpassword => $authpasswd,] # v3
184 [-authprotocol => $authproto,] # v3
185 [-privkey => $privkey,] # v3
186 [-privpassword => $privpasswd,] # v3
187 [-privprotocol => $privproto,] # v3
188 );
189 This is the constructor for Net::SNMP objects. In scalar context, a
191 reference to a new Net::SNMP object is returned if the creation of the
192 object is successful. In list context, a reference to a new Net::SNMP
193 object and an empty error message string is returned. If a failure
194 occurs, the object reference is returned as the undefined value. The
195 error string may be used to determine the cause of the error.
196 Most of the named arguments passed to the constructor define basic
198 attributes for the object and are not modifiable after the object has
199 been created. The -timeout, -retries, -maxmsgsize, -translate, and
200 -debug arguments are modifiable using an accessor method. See their
201 corresponding method definitions for a complete description of their
202 usage, default values, and valid ranges.
203 Transport Domain Arguments
205 The Net::SNMP module uses UDP/IPv4 as the default Transport Domain
206 to exchange SNMP messages between the local and remote devices.
207 The module also supports UDP/IPv6, TCP/IPv4, and TCP/IPv6 as
208 alternative Transport Domains. The -domain argument can be used to
209 change the Transport Domain by setting the value to one of the
210 following strings: 'udp6', 'udp/ipv6'; 'tcp', 'tcp4', 'tcp/ipv4';
211 'tcp6', or 'tcp/ipv6'. The -domain argument also accepts the
212 strings 'udp', 'udp4', or 'udp/ipv4' which correspond to the
213 default Transport Domain of UDP/IPv4.
214 The transport address of the destination SNMP device can be
216 specified using the -hostname argument. This argument is optional
217 and defaults to "localhost". The destination port number can be
218 specified as part of the transport address or by using the -port
219 argument. Either a numeric port number or a textual service name
220 can be specified. A numeric port number in parentheses can
221 optionally follow the service name. This port number will be used
222 if the service name cannot be resolved. If the destination port
223 number is not specified, the well-known SNMP port number 161 is
224 used.
225 By default the source transport address and port number are
227 assigned dynamically by the local device on which the Net::SNMP
228 module is being used. This dynamic assignment can be overridden by
229 using the -localaddr and -localport arguments. These arguments
230 accept the same values as the -hostname and -port arguments
231 respectively. The resolved address must correspond to a valid
232 address of an interface on the local device.
233 When using an IPv4 Transport Domain, the transport address can be
235 specified as either an IP network hostname or an IPv4 address in
236 standard dotted notation. The port information can be optionally
237 appended to the hostname or address delimited by a colon. The
238 accepted IPv4 transport address formats are "address",
239 "address:port", "hostname", and "hostname:port".
240 When using an IPv6 Transport Domain, the transport address can be
242 specified as an IP hostname (which will be looked up as a DNS quad-
243 A record) or an IPv6 address in presentation format. The port
244 information can optionally be included following a colon after the
245 hostname or address. When including this information after an IPv6
246 address, the address must be enclosed in square brackets. The
247 scope zone index (described in RFC 4007) can be specified after the
248 address as a decimal value delimited by a percent sign. The
249 accepted transport address formats for IPv6 are "address",
250 "address%zone", "[address]:port", "[address%zone]:port",
251 "hostname", and "hostname:port".
252 Security Model Arguments
254 The -version argument controls which other arguments are expected
255 or required by the "session()" constructor. The Net::SNMP module
256 supports SNMPv1, SNMPv2c, and SNMPv3. The module defaults to
257 SNMPv1 if no -version argument is specified. The -version argument
258 expects either a digit (i.e. '1', '2', or '3') or a string
259 specifying the version (i.e. 'snmpv1', 'snmpv2c', or 'snmpv3') to
260 define the SNMP version.
261 The Security Model used by the Net::SNMP object is based on the
263 SNMP version associated with the object. If the SNMP version is
264 SNMPv1 or SNMPv2c a Community-based Security Model will be used,
265 while the User-based Security Model (USM) will be used if the
266 version is SNMPv3.
267 Community-based Security Model Argument
269 If the Security Model is Community-based, the only argument
270 available is the -community argument. This argument expects a
271 string that is to be used as the SNMP community name. By
272 default the community name is set to 'public' if the argument
273 is not present.
274 User-based Security Model Arguments
276 The User-based Security Model (USM) used by SNMPv3 requires
277 that a securityName be specified using the -username argument.
278 The creation of a Net::SNMP object with the version set to
279 SNMPv3 will fail if the -username argument is not present. The
280 -username argument expects a string 1 to 32 octets in length.
281 Different levels of security are allowed by the User-based
283 Security Model which address authentication and privacy
284 concerns. A SNMPv3 Net::SNMP object will derive the security
285 level (securityLevel) based on which of the following arguments
286 are specified.
287 By default a securityLevel of 'noAuthNoPriv' is assumed. If
289 the -authkey or -authpassword arguments are specified, the
290 securityLevel becomes 'authNoPriv'. The -authpassword argument
291 expects a string which is at least 1 octet in length.
292 Optionally, the -authkey argument can be used so that a plain
293 text password does not have to be specified in a script. The
294 -authkey argument expects a hexadecimal string produced by
295 localizing the password with the authoritativeEngineID for the
296 specific destination device. The "snmpkey" utility included
297 with the distribution can be used to create the hexadecimal
298 string (see snmpkey).
299 Two different hash algorithms are defined by SNMPv3 which can
301 be used by the Security Model for authentication. These
302 algorithms are HMAC-MD5-96 "MD5" (RFC 1321) and HMAC-SHA-96
303 "SHA-1" (NIST FIPS PUB 180-1). The default algorithm used by
304 the module is HMAC-MD5-96. This behavior can be changed by
305 using the -authprotocol argument. This argument expects either
306 the string 'md5' or 'sha' to be passed to modify the hash
307 algorithm.
308 By specifying the arguments -privkey or -privpassword the
310 securityLevel associated with the object becomes 'authPriv'.
311 According to SNMPv3, privacy requires the use of
312 authentication. Therefore, if either of these two arguments
313 are present and the -authkey or -authpassword arguments are
314 missing, the creation of the object fails. The -privkey and
315 -privpassword arguments expect the same input as the -authkey
316 and -authpassword arguments respectively.
317 The User-based Security Model described in RFC 3414 defines a
319 single encryption protocol to be used for privacy. This
320 protocol, CBC-DES "DES" (NIST FIPS PUB 46-1), is used by
321 default or if the string 'des' is passed to the -privprotocol
322 argument. The module also supports RFC 3826 which describes
323 the use of CFB128-AES-128 "AES" (NIST FIPS PUB 197) in the USM.
324 The AES encryption protocol can be selected by passing 'aes' or
325 'aes128' to the -privprotocol argument. By working with the
326 Extended Security Options Consortium
327 <http://www.snmp.com/protocol/eso.shtml>, the module also
328 supports CBC-3DES-EDE "Triple-DES" (NIST FIPS 46-3) in the
329 User-based Security Model. This is defined in the draft
330 <http://www.snmp.com/eso/draft-reeder-snmpv3-usm-3desede-00.txt>.
331 The Triple-DES encryption protocol can be selected using the
332 -privprotocol argument with the string '3des' or '3desede'.
333 close() - clear the Transport Domain associated with the object
335 $session->close();
336 This method clears the Transport Domain and any errors associated with
338 the object. Once closed, the Net::SNMP object can no longer be used to
339 send or receive SNMP messages.
340 snmp_dispatcher() - enter the non-blocking object event loop
342 $session->snmp_dispatcher();
343 This method enters the event loop associated with non-blocking
345 Net::SNMP objects. The method exits when all queued SNMP messages have
346 received a response or have timed out at the Transport Layer. This
347 method is also exported as the stand alone function "snmp_dispatcher()"
348 by default (see "EXPORTS").
349 get_request() - send a SNMP get-request to the remote agent
351 $result = $session->get_request(
352 [-callback => sub {},] # non-blocking
353 [-delay => $seconds,] # non-blocking
354 [-contextengineid => $engine_id,] # v3
355 [-contextname => $name,] # v3
356 -varbindlist => \@oids,
357 );
358 This method performs a SNMP get-request query to gather data from the
360 remote agent on the host associated with the Net::SNMP object. The
361 message is built using the list of OBJECT IDENTIFIERs in dotted
362 notation passed to the method as an array reference using the
363 -varbindlist argument. Each OBJECT IDENTIFIER is placed into a single
364 SNMP GetRequest-PDU in the same order that it held in the original
365 list.
366 A reference to a hash is returned in blocking mode which contains the
368 contents of the VarBindList. In non-blocking mode, a true value is
369 returned when no error has occurred. In either mode, the undefined
370 value is returned when an error has occurred. The "error()" method may
371 be used to determine the cause of the failure.
372 get_next_request() - send a SNMP get-next-request to the remote agent
374 $result = $session->get_next_request(
375 [-callback => sub {},] # non-blocking
376 [-delay => $seconds,] # non-blocking
377 [-contextengineid => $engine_id,] # v3
378 [-contextname => $name,] # v3
379 -varbindlist => \@oids,
380 );
381 This method performs a SNMP get-next-request query to gather data from
383 the remote agent on the host associated with the Net::SNMP object. The
384 message is built using the list of OBJECT IDENTIFIERs in dotted
385 notation passed to the method as an array reference using the
386 -varbindlist argument. Each OBJECT IDENTIFER is placed into a single
387 SNMP GetNextRequest-PDU in the same order that it held in the original
388 list.
389 A reference to a hash is returned in blocking mode which contains the
391 contents of the VarBindList. In non-blocking mode, a true value is
392 returned when no error has occurred. In either mode, the undefined
393 value is returned when an error has occurred. The "error()" method may
394 be used to determine the cause of the failure.
395 set_request() - send a SNMP set-request to the remote agent
397 $result = $session->set_request(
398 [-callback => sub {},] # non-blocking
399 [-delay => $seconds,] # non-blocking
400 [-contextengineid => $engine_id,] # v3
401 [-contextname => $name,] # v3
402 -varbindlist => \@oid_value,
403 );
404 This method is used to modify data on the remote agent that is
406 associated with the Net::SNMP object using a SNMP set-request. The
407 message is built using a list of values consisting of groups of an
408 OBJECT IDENTIFIER, an object type, and the actual value to be set.
409 This list is passed to the method as an array reference using the
410 -varbindlist argument. The OBJECT IDENTIFIERs in each trio are to be
411 in dotted notation. The object type is an octet corresponding to the
412 ASN.1 type of value that is to be set. Each of the supported ASN.1
413 types have been defined and are exported by the package by default (see
414 "EXPORTS").
415 A reference to a hash is returned in blocking mode which contains the
417 contents of the VarBindList. In non-blocking mode, a true value is
418 returned when no error has occurred. In either mode, the undefined
419 value is returned when an error has occurred. The "error()" method may
420 be used to determine the cause of the failure.
421 trap() - send a SNMP trap to the remote manager
423 $result = $session->trap(
424 [-delay => $seconds,] # non-blocking
425 [-enterprise => $oid,]
426 [-agentaddr => $ipaddress,]
427 [-generictrap => $generic,]
428 [-specifictrap => $specific,]
429 [-timestamp => $timeticks,]
430 -varbindlist => \@oid_value,
431 );
432 This method sends a SNMP trap to the remote manager associated with the
434 Net::SNMP object. All arguments are optional and will be given the
435 following defaults in the absence of a corresponding named argument:
436 • The default value for the trap -enterprise is "1.3.6.1.4.1", which
438 corresponds to "iso.org.dod.internet.private.enterprises". The
439 enterprise value is expected to be an OBJECT IDENTIFER in dotted
440 notation.
441 • When the Transport Domain is UDP/IPv4 or TCP/IPv4, the default
443 value for the trap -agentaddr is the IP address associated with the
444 interface on which the trap will be transmitted. For other
445 Transport Domains the -agentaddr is defaulted to "0.0.0.0". When
446 specified, the agent-addr is expected to be an IpAddress in dotted
447 notation.
448 • The default value for the -generictrap type is 6 which corresponds
450 to "enterpriseSpecific". The generic-trap types are defined and
451 can be exported upon request (see "EXPORTS").
452 • The default value for the -specifictrap type is 0. No pre-defined
454 values are available for specific-trap types.
455 • The default value for the trap -timestamp is the "uptime" of the
457 script. The "uptime" of the script is the number of hundredths of
458 seconds that have elapsed since the script began running. The
459 time-stamp is expected to be a TimeTicks number in hundredths of
460 seconds.
461 • The default value for the trap -varbindlist is an empty array
463 reference. The variable-bindings are expected to be in an array
464 format consisting of groups of an OBJECT IDENTIFIER, an object
465 type, and the actual value of the object. This is identical to the
466 list expected by the "set_request()" method. The OBJECT
467 IDENTIFIERs in each trio are to be in dotted notation. The object
468 type is an octet corresponding to the ASN.1 type for the value.
469 Each of the supported types have been defined and are exported by
470 default (see "EXPORTS").
471 A true value is returned when the method is successful. The undefined
473 value is returned when a failure has occurred. The "error()" method
474 can be used to determine the cause of the failure. Since there are no
475 acknowledgements for Trap-PDUs, there is no way to determine if the
476 remote host actually received the trap.
477 NOTE: When the object is in non-blocking mode, the trap is not sent
479 until the event loop is entered and no callback is ever executed.
480 NOTE: This method can only be used when the version of the object is
482 set to SNMPv1.
483 get_bulk_request() - send a SNMP get-bulk-request to the remote agent
485 $result = $session->get_bulk_request(
486 [-callback => sub {},] # non-blocking
487 [-delay => $seconds,] # non-blocking
488 [-contextengineid => $engine_id,] # v3
489 [-contextname => $name,] # v3
490 [-nonrepeaters => $non_reps,]
491 [-maxrepetitions => $max_reps,]
492 -varbindlist => \@oids,
493 );
494 This method performs a SNMP get-bulk-request query to gather data from
496 the remote agent on the host associated with the Net::SNMP object. All
497 arguments are optional except -varbindlist and will be given the
498 following defaults in the absence of a corresponding named argument:
499 • The default value for the get-bulk-request -nonrepeaters is 0. The
501 non-repeaters value specifies the number of variables in the
502 variable-bindings list for which a single successor is to be
503 returned.
504 • The default value for the get-bulk-request -maxrepetitions is 0.
506 The max-repetitions value specifies the number of successors to be
507 returned for the remaining variables in the variable-bindings list.
508 • The -varbindlist argument expects an array reference consisting of
510 a list of OBJECT IDENTIFIERs in dotted notation. Each OBJECT
511 IDENTIFER is placed into a single SNMP GetBulkRequest-PDU in the
512 same order that it held in the original list.
513 A reference to a hash is returned in blocking mode which contains the
515 contents of the VarBindList. In non-blocking mode, a true value is
516 returned when no error has occurred. In either mode, the undefined
517 value is returned when an error has occurred. The "error()" method may
518 be used to determine the cause of the failure.
519 NOTE: This method can only be used when the version of the object is
521 set to SNMPv2c or SNMPv3.
522 inform_request() - send a SNMP inform-request to the remote manager
524 $result = $session->inform_request(
525 [-callback => sub {},] # non-blocking
526 [-delay => $seconds,] # non-blocking
527 [-contextengineid => $engine_id,] # v3
528 [-contextname => $name,] # v3
529 -varbindlist => \@oid_value,
530 );
531 This method is used to provide management information to the remote
533 manager associated with the Net::SNMP object using an inform-request.
534 The message is built using a list of values consisting of groups of an
535 OBJECT IDENTIFIER, an object type, and the actual value to be
536 identified. This list is passed to the method as an array reference
537 using the -varbindlist argument. The OBJECT IDENTIFIERs in each trio
538 are to be in dotted notation. The object type is an octet
539 corresponding to the ASN.1 type of value that is to be identified.
540 Each of the supported ASN.1 types have been defined and are exported by
541 the package by default (see "EXPORTS").
542 The first two variable-bindings fields in the inform-request are
544 specified by SNMPv2 and should be:
545 • sysUpTime.0 - ('1.3.6.1.2.1.1.3.0', TIMETICKS, $timeticks)
547 • snmpTrapOID.0 - ('1.3.6.1.6.3.1.1.4.1.0', OBJECT_IDENTIFIER, $oid)
549 A reference to a hash is returned in blocking mode which contains the
551 contents of the VarBindList. In non-blocking mode, a true value is
552 returned when no error has occurred. In either mode, the undefined
553 value is returned when an error has occurred. The "error()" method may
554 be used to determine the cause of the failure.
555 NOTE: This method can only be used when the version of the object is
557 set to SNMPv2c or SNMPv3.
558 snmpv2_trap() - send a SNMP snmpV2-trap to the remote manager
560 $result = $session->snmpv2_trap(
561 [-delay => $seconds,] # non-blocking
562 -varbindlist => \@oid_value,
563 );
564 This method sends a snmpV2-trap to the remote manager associated with
566 the Net::SNMP object. The message is built using a list of values
567 consisting of groups of an OBJECT IDENTIFIER, an object type, and the
568 actual value to be identified. This list is passed to the method as an
569 array reference using the -varbindlist argument. The OBJECT
570 IDENTIFIERs in each trio are to be in dotted notation. The object type
571 is an octet corresponding to the ASN.1 type of value that is to be
572 identified. Each of the supported ASN.1 types have been defined and
573 are exported by the package by default (see "EXPORTS").
574 The first two variable-bindings fields in the snmpV2-trap are specified
576 by SNMPv2 and should be:
577 • sysUpTime.0 - ('1.3.6.1.2.1.1.3.0', TIMETICKS, $timeticks)
579 • snmpTrapOID.0 - ('1.3.6.1.6.3.1.1.4.1.0', OBJECT_IDENTIFIER, $oid)
581 A true value is returned when the method is successful. The undefined
583 value is returned when a failure has occurred. The "error()" method
584 can be used to determine the cause of the failure. Since there are no
585 acknowledgements for SNMPv2-Trap-PDUs, there is no way to determine if
586 the remote host actually received the snmpV2-trap.
587 NOTE: When the object is in non-blocking mode, the snmpV2-trap is not
589 sent until the event loop is entered and no callback is ever executed.
590 NOTE: This method can only be used when the version of the object is
592 set to SNMPv2c. SNMPv2-Trap-PDUs are supported by SNMPv3, but require
593 the sender of the message to be an authoritative SNMP engine which is
594 not currently supported by the Net::SNMP module.
595 get_table() - retrieve a table from the remote agent
597 $result = $session->get_table(
598 [-callback => sub {},] # non-blocking
599 [-delay => $seconds,] # non-blocking
600 [-contextengineid => $engine_id,] # v3
601 [-contextname => $name,] # v3
602 -baseoid => $oid,
603 [-maxrepetitions => $max_reps,] # v2c/v3
604 );
605 This method performs repeated SNMP get-next-request or get-bulk-request
607 (when using SNMPv2c or SNMPv3) queries to gather data from the remote
608 agent on the host associated with the Net::SNMP object. The first
609 message sent is built using the OBJECT IDENTIFIER in dotted notation
610 passed to the method by the -baseoid argument. Repeated SNMP requests
611 are issued until the OBJECT IDENTIFIER in the response is no longer a
612 child of the base OBJECT IDENTIFIER.
613 The -maxrepetitions argument can be used to specify the max-repetitions
615 value that is passed to the get-bulk-requests when using SNMPv2c or
616 SNMPv3. If this argument is not present, a value is calculated based
617 on the maximum message size for the Net::SNMP object. If the value is
618 set to 1 or less, get-next-requests will be used for the queries
619 instead of get-bulk-requests.
620 A reference to a hash is returned in blocking mode which contains the
622 contents of the VarBindList. In non-blocking mode, a true value is
623 returned when no error has occurred. In either mode, the undefined
624 value is returned when an error has occurred. The "error()" method may
625 be used to determine the cause of the failure.
626 WARNING: Results from this method can become very large if the base
628 OBJECT IDENTIFIER is close to the root of the SNMP MIB tree.
629 get_entries() - retrieve table entries from the remote agent
631 $result = $session->get_entries(
632 [-callback => sub {},] # non-blocking
633 [-delay => $seconds,] # non-blocking
634 [-contextengineid => $engine_id,] # v3
635 [-contextname => $name,] # v3
636 -columns => \@columns,
637 [-startindex => $start,]
638 [-endindex => $end,]
639 [-maxrepetitions => $max_reps,] # v2c/v3
640 );
641 This method performs repeated SNMP get-next-request or get-bulk-request
643 (when using SNMPv2c or SNMPv3) queries to gather data from the remote
644 agent on the host associated with the Net::SNMP object. Each message
645 specifically requests data for each OBJECT IDENTIFIER specified in the
646 -columns array. The OBJECT IDENTIFIERs must correspond to column
647 entries for a conceptual row in a table. They may however be columns
648 in different tables as long as each table is indexed the same way. The
649 optional -startindex and -endindex arguments may be specified to limit
650 the query to specific rows in the table(s).
651 The -startindex can be specified as a single decimal value or in dotted
653 notation if the index associated with the entry so requires. If the
654 -startindex is specified, it will be include as part of the query
655 results. If no -startindex is specified, the first request message
656 will be sent without an index. To insure that the -startindex is
657 included, the last sub-identifier in the index is decremented by one.
658 If the last sub-identifier has a value of zero, the sub-identifier is
659 removed from the index.
660 The optional -endindex argument can be specified as a single decimal
662 value or in dotted notation. If the -endindex is specified, it will be
663 included as part of the query results. If no -endindex is specified,
664 repeated SNMP requests are issued until the response no longer returns
665 entries matching any of the columns specified in the -columns array.
666 The -maxrepetitions argument can be used to specify the max-repetitions
668 value that is passed to the get-bulk-requests when using SNMPv2c or
669 SNMPv3. If this argument is not present, a value is calculated based
670 on the maximum message size of the object and the number of columns
671 specified in the -columns array. If the value is set to 1 or less,
672 get-next-requests will be used for the queries instead of get-bulk-
673 requests.
674 A reference to a hash is returned in blocking mode which contains the
676 contents of the VarBindList. In non-blocking mode, a true value is
677 returned when no error has occurred. In either mode, the undefined
678 value is returned when an error has occurred. The "error()" method may
679 be used to determine the cause of the failure.
680 version() - get the SNMP version from the object
682 $rfc_version = $session->version();
683 This method returns the current value for the SNMP version associated
685 with the object. The returned value is the corresponding version
686 number defined by the RFCs for the protocol version field (i.e. SNMPv1
687 == 0, SNMPv2c == 1, and SNMPv3 == 3). The RFC versions are defined as
688 constant by the module and can be exported by request (see "EXPORTS").
689 error() - get the current error message from the object
691 $error_message = $session->error();
692 This method returns a text string explaining the reason for the last
694 error. An empty string is returned if no error has occurred.
695 hostname() - get the hostname associated with the object
697 $hostname = $session->hostname();
698 This method returns the parsed hostname string that is associated with
700 the object. Any port information and formatting that can be included
701 with the corresponding "session()" constructor argument will be
702 stripped and not included as part of the returned string.
703 error_status() - get the current SNMP error-status from the object
705 $error_status = $session->error_status();
706 This method returns the numeric value of the error-status contained in
708 the last SNMP message received by the object.
709 error_index() - get the current SNMP error-index from the object
711 $error_index = $session->error_index();
712 This method returns the numeric value of the error-index contained in
714 the last SNMP message received by the object.
715 var_bind_list() - get the hash reference for the VarBindList values
717 $values = $session->var_bind_list();
718 This method returns a hash reference created using the ObjectName and
720 the ObjectSyntax pairs in the VarBindList of the last SNMP message
721 received by the object. The keys of the hash consist of the OBJECT
722 IDENTIFIERs in dotted notation corresponding to each ObjectName in the
723 VarBindList. If any of the OBJECT IDENTIFIERs passed to the request
724 method began with a leading dot, all of the OBJECT IDENTIFIER hash keys
725 will be prefixed with a leading dot. If duplicate OBJECT IDENTIFIERs
726 are present in the VarBindList they will be padded with spaces to make
727 them an unique hash key. The value of each hash entry is set equal to
728 the value of the corresponding ObjectSyntax. The undefined value is
729 returned if there has been a failure.
730 var_bind_names() - get the array of the ObjectNames in the VarBindList
732 @names = $session->var_bind_names();
733 This method returns an array containing the OBJECT IDENTIFIERs
735 corresponding to the ObjectNames in the VarBindList in the order that
736 they were received in the last SNMP message. The entries in the array
737 will map directly to the keys in the hash reference returned by the
738 methods that perform SNMP message exchanges and by the
739 "var_bind_list()" and "var_bind_types()" methods. The array returned
740 for the convenience methods "get_table()" and "get_entries()" will be
741 in lexicographical order. An empty array is returned if there has been
742 a failure.
743 var_bind_types() - get the hash reference for the VarBindList ASN.1 types
745 $types = $session->var_bind_types();
746 This method returns a hash reference created using the ObjectName and
748 the ASN.1 type of the ObjectSyntax in the VarBindList of the last SNMP
749 message received by the object. The keys of the hash consist of the
750 OBJECT IDENTIFIERs in dotted notation corresponding to each ObjectName
751 in the VarBindList. The value of each hash entry is set equal to the
752 ASN.1 type of the corresponding ObjectSyntax. Constants for the
753 supported ASN.1 types have been defined and are exported by the package
754 by default (see "EXPORTS"). The undefined value is returned if there
755 has been a failure.
756 timeout() - set or get the current timeout period for the object
758 $seconds = $session->timeout([$seconds]);
759 This method returns the current value for the Transport Layer timeout
761 for the Net::SNMP object. This value is the number of seconds that the
762 object will wait for a response from the agent on the remote host. The
763 default timeout is 5.0 seconds.
764 If a parameter is specified, the timeout for the object is set to the
766 provided value if it falls within the range 1.0 to 60.0 seconds. The
767 undefined value is returned upon an error and the "error()" method may
768 be used to determine the cause.
769 retries() - set or get the current retry count for the object
771 $count = $session->retries([$count]);
772 This method returns the current value for the number of times to retry
774 sending a SNMP message to the remote host. The default number of
775 retries is 1.
776 If a parameter is specified, the number of retries for the object is
778 set to the provided value if it falls within the range 0 to 20. The
779 undefined value is returned upon an error and the "error()" method may
780 be used to determine the cause.
781 max_msg_size() - set or get the current maxMsgSize for the object
783 $octets = $session->max_msg_size([$octets]);
784 This method returns the current value for the maximum message size
786 (maxMsgSize) for the Net::SNMP object. This value is the largest
787 message size in octets that can be prepared or processed by the object.
788 The default maxMsgSize is 1472 octets for UDP/IPv4, 1452 octets for
789 UDP/IPv6, 1460 octets for TCP/IPv4, and 1440 octets for TCP/IPv6.
790 If a parameter is specified, the maxMsgSize is set to the provided
792 value if it falls within the range 484 to 65535 octets. The undefined
793 value is returned upon an error and the "error()" method may be used to
794 determine the cause.
795 NOTE: When using SNMPv3, the maxMsgSize is actually contained in the
797 SNMP message (as msgMaxSize). If the value received from a remote
798 device is less than the current maxMsgSize, the size is automatically
799 adjusted to be the lower value.
800 translate() - enable or disable the translation mode for the object
802 $mask = $session->translate([
803 $mode |
804 [ # Perl anonymous ARRAY reference
805 ['-all' => $mode0,]
806 ['-octetstring' => $mode1,]
807 ['-null' => $mode2,]
808 ['-timeticks' => $mode3,]
809 ['-opaque' => $mode4,]
810 ['-nosuchobject' => $mode5,]
811 ['-nosuchinstance' => $mode6,]
812 ['-endofmibview' => $mode7,]
813 ['-unsigned' => $mode8]
814 ]
815 ]);
816 When the object decodes the GetResponse-PDU that is returned in
818 response to a SNMP message, certain values are translated into a more
819 "human readable" form. By default the following translations occur:
820 • OCTET STRINGs and Opaques containing any octet which is not part of
822 the character set defined as a DisplayString in RFC 2679 are
823 converted into a hexadecimal representation prefixed with "0x".
824 The control codes NUL(0x00), BEL(0x07), BS(0x08), HT(0x09),
825 LF(0x0A), VT(0x0b), FF(0x0C), and CR(0x0D) are part of the
826 character set and will not trigger translation. The sequence 'CR
827 x' for any x other than LF or NUL is illegal and will trigger
828 translation.
829 • TimeTicks integer values are converted to a time format.
831 • NULL values return the string "NULL" instead of an empty string.
833 • noSuchObject exception values return the string "noSuchObject"
835 instead of an empty string.
836 • noSuchInstance exception values return the string "noSuchInstance"
838 instead of an empty string.
839 • endOfMibView exception values return the string "endOfMibView"
841 instead of an empty string.
842 • Counter64, Counter, Gauge, and TimeTick values that have been
844 incorrectly encoded as signed negative values are returned as
845 unsigned values.
846 The "translate()" method can be invoked with two different types of
848 arguments.
849 If the argument passed is any Perl variable type except an array
851 reference, the translation mode for all ASN.1 types is set to either
852 enabled or disabled, depending on the value of the passed parameter.
853 Any value that Perl would treat as a true value will set the mode to be
854 enabled for all types, while a false value will disable translation for
855 all types.
856 A reference to an array can be passed to the "translate()" method in
858 order to define the translation mode on a per ASN.1 type basis. The
859 array is expected to contain a list of named argument pairs for each
860 ASN.1 type that is to be modified. The arguments in the list are
861 applied in the order that they are passed in via the array. Arguments
862 at the end of the list supercede those passed earlier in the list. The
863 argument "-all" can be used to specify that the mode is to apply to all
864 ASN.1 types. Only the arguments for the ASN.1 types that are to be
865 modified need to be included in the list.
866 The "translate()" method returns a bit mask indicating which ASN.1
868 types are to be translated. Definitions of the bit to ASN.1 type
869 mappings can be exported using the :translate tag (see "EXPORTS"). The
870 undefined value is returned upon an error and the "error()" method may
871 be used to determine the cause.
872 debug() - set or get the debug mode for the module
874 $mask = $session->debug([$mask]);
875 This method is used to enable or disable debugging for the Net::SNMP
877 module. Debugging can be enabled on a per component level as defined
878 by a bit mask passed to the "debug()" method. The bit mask is broken
879 up as follows:
880 • 0x02 - Message or PDU encoding and decoding
882 • 0x04 - Transport Layer
884 • 0x08 - Dispatcher
886 • 0x10 - Message Processing
888 • 0x20 - Security
890 Symbols representing these bit mask values are defined by the module
892 and can be exported using the :debug tag (see "EXPORTS"). If a non-
893 numeric value is passed to the "debug()" method, it is evaluated in
894 boolean context. Debugging for all of the components is then enabled
895 or disabled based on the resulting truth value.
896 The current debugging mask is returned by the method. Debugging can
898 also be enabled using the stand alone function "snmp_debug()". This
899 function can be exported by request (see "EXPORTS").
900
902 oid_base_match() - determine if an OID has a specified OID base
903 $value = oid_base_match($base_oid, $oid);
904 This function takes two OBJECT IDENTIFIERs in dotted notation and
906 returns a true value (i.e. 0x1) if the second OBJECT IDENTIFIER is
907 equal to or is a child of the first OBJECT IDENTIFIER in the SNMP
908 Management Information Base (MIB). This function can be used in
909 conjunction with the "get-next-request()" or "get-bulk-request()"
910 methods to determine when a OBJECT IDENTIFIER in the GetResponse-PDU is
911 no longer in the desired MIB tree branch.
912 oid_lex_cmp() - compare two OBJECT IDENTIFIERs lexicographically
914 $cmp = oid_lex_cmp($oid1, $oid2);
915 This function takes two OBJECT IDENTIFIERs in dotted notation and
917 returns one of the values 1, 0, -1 if $oid1 is respectively
918 lexicographically greater, equal, or less than $oid2.
919 oid_lex_sort() - sort a list of OBJECT IDENTIFIERs lexicographically
921 @sorted_oids = oid_lex_sort(@oids);
922 This function takes a list of OBJECT IDENTIFIERs in dotted notation and
924 returns the listed sorted in lexicographical order.
925 snmp_type_ntop() - convert an ASN.1 type to presentation format
927 $text = snmp_type_ntop($type);
928 This function takes an ASN.1 type octet and returns a text string
930 suitable for presentation. Some ASN.1 type definitions map to the same
931 octet value when encoded. This method cannot distinguish between these
932 multiple mappings and the most basic type name will be returned.
933 ticks_to_time() - convert TimeTicks to formatted time
935 $time = ticks_to_time($timeticks);
936 This function takes an ASN.1 TimeTicks value and returns a string
938 representing the time defined by the value. The TimeTicks value is
939 expected to be a non-negative integer value representing the time in
940 hundredths of a second since some epoch. The returned string will
941 display the time in days, hours, and seconds format according to the
942 value of the TimeTicks argument.
943
945 The Net::SNMP module uses the Exporter module to export useful
946 constants and subroutines. These exportable symbols are defined below
947 and follow the rules and conventions of the Exporter module (see
948 Exporter).
949 Default
951 &snmp_dispatcher, INTEGER, INTEGER32, OCTET_STRING,
952 OBJECT_IDENTIFIER, IPADDRESS, COUNTER, COUNTER32, GAUGE, GAUGE32,
953 UNSIGNED32, TIMETICKS, OPAQUE, COUNTER64, NOSUCHOBJECT,
954 NOSUCHINSTANCE, ENDOFMIBVIEW
955 Exportable
957 &snmp_debug, &snmp_dispatcher, &snmp_type_ntop, &oid_base_match,
958 &oid_lex_cmp, &oid_lex_sort,&ticks_to_time, INTEGER, INTEGER32,
959 OCTET_STRING, NULL, OBJECT_IDENTIFIER, SEQUENCE, IPADDRESS,
960 COUNTER, COUNTER32, GAUGE, GAUGE32, UNSIGNED32, TIMETICKS, OPAQUE,
961 COUNTER64, NOSUCHOBJECT, NOSUCHINSTANCE, ENDOFMIBVIEW, GET_REQUEST,
962 GET_NEXT_REQUEST, GET_RESPONSE, SET_REQUEST, TRAP,
963 GET_BULK_REQUEST, INFORM_REQUEST, SNMPV2_TRAP, REPORT, DEBUG_ALL,
964 DEBUG_NONE, DEBUG_MESSAGE, DEBUG_TRANSPORT,
965 DEBUG_DISPATCHER,DEBUG_PROCESSING, DEBUG_SECURITY, COLD_START,
966 WARM_START, LINK_DOWN, LINK_UP, AUTHENTICATION_FAILURE,
967 EGP_NEIGHBOR_LOSS, ENTERPRISE_SPECIFIC, SNMP_VERSION_1,
968 SNMP_VERSION_2C, SNMP_VERSION_3, SNMP_PORT, SNMP_TRAP_PORT,
969 TRANSLATE_NONE,TRANSLATE_OCTET_STRING, TRANSLATE_NULL,
970 TRANSLATE_TIMETICKS, TRANSLATE_OPAQUE,TRANSLATE_NOSUCHOBJECT,
971 TRANSLATE_NOSUCHINSTANCE, TRANSLATE_ENDOFMIBVIEW,
972 TRANSLATE_UNSIGNED, TRANSLATE_ALL
973 Tags
975 :asn1
976 INTEGER, INTEGER32, OCTET_STRING, NULL, OBJECT_IDENTIFIER,
977 SEQUENCE, IPADDRESS, COUNTER, COUNTER32, GAUGE, GAUGE32,
978 UNSIGNED32, TIMETICKS, OPAQUE, COUNTER64, NOSUCHOBJECT,
979 NOSUCHINSTANCE, ENDOFMIBVIEW, GET_REQUEST, GET_NEXT_REQUEST,
980 GET_RESPONSE, SET_REQUEST, TRAP, GET_BULK_REQUEST,
981 INFORM_REQUEST, SNMPV2_TRAP, REPORT
982 :debug
984 &snmp_debug, DEBUG_ALL, DEBUG_NONE, DEBUG_MESSAGE,
985 DEBUG_TRANSPORT, DEBUG_DISPATCHER, DEBUG_PROCESSING,
986 DEBUG_SECURITY
987 :generictrap
989 COLD_START, WARM_START, LINK_DOWN, LINK_UP,
990 AUTHENTICATION_FAILURE, EGP_NEIGHBOR_LOSS, ENTERPRISE_SPECIFIC
991 :snmp
993 &snmp_debug, &snmp_dispatcher, &snmp_type_ntop,
994 &oid_base_match, &oid_lex_cmp, &oid_lex_sort, &ticks_to_time,
995 SNMP_VERSION_1, SNMP_VERSION_2C, SNMP_VERSION_3, SNMP_PORT,
996 SNMP_TRAP_PORT
997 :translate
999 TRANSLATE_NONE, TRANSLATE_OCTET_STRING, TRANSLATE_NULL,
1000 TRANSLATE_TIMETICKS, TRANSLATE_OPAQUE, TRANSLATE_NOSUCHOBJECT,
1001 TRANSLATE_NOSUCHINSTANCE, TRANSLATE_ENDOFMIBVIEW,
1002 TRANSLATE_UNSIGNED, TRANSLATE_ALL
1003 :ALL
1005 All of the above exportable items.
1006
1008 1. Blocking SNMPv1 get-request for sysUpTime
1009 This example gets the sysUpTime from a remote host.
1010 #! /usr/local/bin/perl
1012 use strict;
1014 use warnings;
1015 use Net::SNMP;
1017 my $OID_sysUpTime = '1.3.6.1.2.1.1.3.0';
1019 my ($session, $error) = Net::SNMP->session(
1021 -hostname => shift || 'localhost',
1022 -community => shift || 'public',
1023 );
1024 if (!defined $session) {
1026 printf "ERROR: %s.\n", $error;
1027 exit 1;
1028 }
1029 my $result = $session->get_request(-varbindlist => [ $OID_sysUpTime ],);
1031 if (!defined $result) {
1033 printf "ERROR: %s.\n", $session->error();
1034 $session->close();
1035 exit 1;
1036 }
1037 printf "The sysUpTime for host '%s' is %s.\n",
1039 $session->hostname(), $result->{$OID_sysUpTime};
1040 $session->close();
1042 exit 0;
1044 2. Blocking SNMPv3 set-request of sysContact
1046 This example sets the sysContact information on the remote host to
1047 "Help Desk x911". The named arguments passed to the "session()"
1048 constructor are for the demonstration of syntax only. These parameters
1049 will need to be set according to the SNMPv3 parameters of the remote
1050 host. The "snmpkey" utility included with the distribution can be used
1051 to create the key values.
1052 #! /usr/local/bin/perl
1054 use strict;
1056 use warnings;
1057 use Net::SNMP;
1059 my $OID_sysContact = '1.3.6.1.2.1.1.4.0';
1061 my ($session, $error) = Net::SNMP->session(
1063 -hostname => 'myv3host.example.com',
1064 -version => 'snmpv3',
1065 -username => 'myv3Username',
1066 -authprotocol => 'sha1',
1067 -authkey => '0x6695febc9288e36282235fc7151f128497b38f3f',
1068 -privprotocol => 'des',
1069 -privkey => '0x6695febc9288e36282235fc7151f1284',
1070 );
1071 if (!defined $session) {
1073 printf "ERROR: %s.\n", $error;
1074 exit 1;
1075 }
1076 my $result = $session->set_request(
1078 -varbindlist => [ $OID_sysContact, OCTET_STRING, 'Help Desk x911' ],
1079 );
1080 if (!defined $result) {
1082 printf "ERROR: %s.\n", $session->error();
1083 $session->close();
1084 exit 1;
1085 }
1086 printf "The sysContact for host '%s' was set to '%s'.\n",
1088 $session->hostname(), $result->{$OID_sysContact};
1089 $session->close();
1091 exit 0;
1093 3. Non-blocking SNMPv2c get-bulk-request for ifTable
1095 This example gets the contents of the ifTable by sending get-bulk-
1096 requests until the responses are no longer part of the ifTable. The
1097 ifTable can also be retrieved using the "get_table()" method. The
1098 ifPhysAddress object in the table has a syntax of an OCTET STRING. By
1099 default, translation is enabled and non-printable OCTET STRINGs are
1100 translated into a hexadecimal format. Sometimes the OCTET STRING
1101 contains all printable characters and this produces unexpected output
1102 when it is not translated. The example turns off translation for OCTET
1103 STRINGs and specifically formats the output for the ifPhysAddress
1104 objects.
1105 #! /usr/local/bin/perl
1107 use strict;
1109 use warnings;
1110 use Net::SNMP qw(:snmp);
1112 my $OID_ifTable = '1.3.6.1.2.1.2.2';
1114 my $OID_ifPhysAddress = '1.3.6.1.2.1.2.2.1.6';
1115 my ($session, $error) = Net::SNMP->session(
1117 -hostname => shift || 'localhost',
1118 -community => shift || 'public',
1119 -nonblocking => 1,
1120 -translate => [-octetstring => 0],
1121 -version => 'snmpv2c',
1122 );
1123 if (!defined $session) {
1125 printf "ERROR: %s.\n", $error;
1126 exit 1;
1127 }
1128 my %table; # Hash to store the results
1130 my $result = $session->get_bulk_request(
1132 -varbindlist => [ $OID_ifTable ],
1133 -callback => [ \&table_callback, \%table ],
1134 -maxrepetitions => 10,
1135 );
1136 if (!defined $result) {
1138 printf "ERROR: %s\n", $session->error();
1139 $session->close();
1140 exit 1;
1141 }
1142 # Now initiate the SNMP message exchange.
1144 snmp_dispatcher();
1146 $session->close();
1148 # Print the results, specifically formatting ifPhysAddress.
1150 for my $oid (oid_lex_sort(keys %table)) {
1152 if (!oid_base_match($OID_ifPhysAddress, $oid)) {
1153 printf "%s = %s\n", $oid, $table{$oid};
1154 } else {
1155 printf "%s = %s\n", $oid, unpack 'H*', $table{$oid};
1156 }
1157 }
1158 exit 0;
1160 sub table_callback
1162 {
1163 my ($session, $table) = @_;
1164 my $list = $session->var_bind_list();
1166 if (!defined $list) {
1168 printf "ERROR: %s\n", $session->error();
1169 return;
1170 }
1171 # Loop through each of the OIDs in the response and assign
1173 # the key/value pairs to the reference that was passed with
1174 # the callback. Make sure that we are still in the table
1175 # before assigning the key/values.
1176 my @names = $session->var_bind_names();
1178 my $next = undef;
1179 while (@names) {
1181 $next = shift @names;
1182 if (!oid_base_match($OID_ifTable, $next)) {
1183 return; # Table is done.
1184 }
1185 $table->{$next} = $list->{$next};
1186 }
1187 # Table is not done, send another request, starting at the last
1189 # OBJECT IDENTIFIER in the response. No need to include the
1190 # calback argument, the same callback that was specified for the
1191 # original request will be used.
1192 my $result = $session->get_bulk_request(
1194 -varbindlist => [ $next ],
1195 -maxrepetitions => 10,
1196 );
1197 if (!defined $result) {
1199 printf "ERROR: %s.\n", $session->error();
1200 }
1201 return;
1203 }
1204 4. Non-blocking SNMPv1 get-request and set-request on multiple hosts
1206 This example first polls several hosts for their sysUpTime. If the
1207 poll of the host is successful, the sysContact and sysLocation
1208 information is set on the host. The sysContact information is
1209 hardcoded to "Help Desk x911" while the sysLocation information is
1210 passed as an argument to the callback.
1211 #! /usr/local/bin/perl
1213 use strict;
1215 use warnings;
1216 use Net::SNMP;
1218 my $OID_sysUpTime = '1.3.6.1.2.1.1.3.0';
1220 my $OID_sysContact = '1.3.6.1.2.1.1.4.0';
1221 my $OID_sysLocation = '1.3.6.1.2.1.1.6.0';
1222 # Hash of hosts and location data.
1224 my %host_data = (
1226 '10.1.1.2' => 'Building 1, Second Floor',
1227 '10.2.1.1' => 'Building 2, First Floor',
1228 'localhost' => 'Right here!',
1229 );
1230 # Create a session for each host and queue a get-request for sysUpTime.
1232 for my $host (keys %host_data) {
1234 my ($session, $error) = Net::SNMP->session(
1236 -hostname => $host,
1237 -community => 'private',
1238 -nonblocking => 1,
1239 );
1240 if (!defined $session) {
1242 printf "ERROR: Failed to create session for host '%s': %s.\n",
1243 $host, $error;
1244 next;
1245 }
1246 my $result = $session->get_request(
1248 -varbindlist => [ $OID_sysUpTime ],
1249 -callback => [ \&get_callback, $host_data{$host} ],
1250 );
1251 if (!defined $result) {
1253 printf "ERROR: Failed to queue get request for host '%s': %s.\n",
1254 $session->hostname(), $session->error();
1255 }
1256 }
1258 # Now initiate the SNMP message exchange.
1260 snmp_dispatcher();
1262 exit 0;
1264 sub get_callback
1266 {
1267 my ($session, $location) = @_;
1268 my $result = $session->var_bind_list();
1270 if (!defined $result) {
1272 printf "ERROR: Get request failed for host '%s': %s.\n",
1273 $session->hostname(), $session->error();
1274 return;
1275 }
1276 printf "The sysUpTime for host '%s' is %s.\n",
1278 $session->hostname(), $result->{$OID_sysUpTime};
1279 # Now set the sysContact and sysLocation for the host.
1281 $result = $session->set_request(
1283 -varbindlist =>
1284 [
1285 $OID_sysContact, OCTET_STRING, 'Help Desk x911',
1286 $OID_sysLocation, OCTET_STRING, $location,
1287 ],
1288 -callback => \&set_callback,
1289 );
1290 if (!defined $result) {
1292 printf "ERROR: Failed to queue set request for host '%s': %s.\n",
1293 $session->hostname(), $session->error();
1294 }
1295 return;
1297 }
1298 sub set_callback
1300 {
1301 my ($session) = @_;
1302 my $result = $session->var_bind_list();
1304 if (defined $result) {
1306 printf "The sysContact for host '%s' was set to '%s'.\n",
1307 $session->hostname(), $result->{$OID_sysContact};
1308 printf "The sysLocation for host '%s' was set to '%s'.\n",
1309 $session->hostname(), $result->{$OID_sysLocation};
1310 } else {
1311 printf "ERROR: Set request failed for host '%s': %s.\n",
1312 $session->hostname(), $session->error();
1313 }
1314 return;
1316 }
1317
1319 • The Net::SNMP module uses syntax that is not supported in versions
1320 of Perl earlier than v5.6.0.
1321 • The non-core modules Crypt::DES, Digest::MD5, Digest::SHA1, and
1323 Digest::HMAC are required to support SNMPv3.
1324 • In order to support the AES Cipher Algorithm as a SNMPv3 privacy
1326 protocol, the non-core module Crypt::Rijndael is needed.
1327 • To use UDP/IPv6 or TCP/IPv6 as a Transport Domain, the non-core
1329 module Socket6 is needed.
1330
1332 David M. Town <dtown@cpan.org>
1333
1335 The original concept for this module was based on SNMP_Session.pm
1336 written by Simon Leinen <simon@switch.ch>.
1337 The Abstract Syntax Notation One (ASN.1) encode and decode methods were
1339 originally derived by example from the CMU SNMP package whose copyright
1340 follows: Copyright (c) 1988, 1989, 1991, 1992 by Carnegie Mellon
1341 University. All rights reserved.
1342
1344 Copyright (c) 1998-2010 David M. Town. All rights reserved.
1345 This program is free software; you may redistribute it and/or modify it
1347 under the same terms as the Perl 5 programming language system itself.
1348perl v5.32.1 2021-01-27 Net::SNMP(3)