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 object
72 reference passed as the first argument to the callback. The value
73 returned by the var_bind_list() method is a hash reference created
74 using the ObjectName and the ObjectSyntax pairs in the VarBindList.
75 The keys of the hash consist of the OBJECT IDENTIFIERs in dotted
76 notation corresponding to each ObjectName in the VarBindList. The
77 value of each hash entry is set equal to the value of the corresponding
78 ObjectSyntax. The undefined value is returned if there has been a
79 failure and the error() method may be used to determine the reason.
80
82 When named arguments are expected by the methods, two different styles
83 are supported. All examples in this documentation use the dashed-
84 option style:
85 $object->method(-argument => $value);
87 However, the IO:: style is also allowed:
89 $object->method(Argument => $value);
91 Non-blocking Objects Arguments
93 When a Net::SNMP object has been created with a "non-blocking"
94 property, most methods that generate a SNMP message take additional
95 arguments to support this property.
96 Callback
98 Most methods associated with a non-blocking object have an
99 optional named argument called -callback. The -callback
100 argument expects a reference to a subroutine or to an array
101 whose first element must be a reference to a subroutine. The
102 subroutine defined by the -callback option is executed when a
103 response to a SNMP message is received, an error condition has
104 occurred, or the number of retries for the message has been
105 exceeded.
106 When the -callback argument only contains a subroutine
108 reference, the subroutine is evaluated passing a reference to
109 the original Net::SNMP object as the only parameter. If the
110 -callback argument was defined as an array reference, all
111 elements in the array are passed to subroutine after the
112 reference to the Net::SNMP object. The first element, which is
113 required to be a reference to a subroutine, is removed before
114 the remaining arguments are passed to that subroutine.
115 Once one method is invoked with the -callback argument, this
117 argument stays with the object and is used by any further calls
118 to methods using the -callback option if the argument is
119 absent. The undefined value may be passed to the -callback
120 argument to delete the callback.
121 NOTE: The subroutine being passed with the -callback named
123 argument should not cause blocking itself. This will cause all
124 the actions in the event loop to be stopped, defeating the non-
125 blocking property of the Net::SNMP module.
126 Delay
128 An optional argument -delay can also be passed to non-blocking
129 objects. The -delay argument instructs the object to wait the
130 number of seconds passed to the argument before executing the
131 SNMP protocol exchange. The delay period starts when the event
132 loop is entered. The -delay parameter is applied to all
133 methods associated with the object once it is specified. The
134 delay value must be set back to 0 seconds to disable the delay
135 parameter.
136 SNMPv3 Arguments
138 A SNMP context is a collection of management information accessible
139 by a SNMP entity. An item of management information may exist in
140 more than one context and a SNMP entity potentially has access to
141 many contexts. The combination of a contextEngineID and a
142 contextName unambiguously identifies a context within an
143 administrative domain. In a SNMPv3 message, the contextEngineID
144 and contextName are included as part of the scopedPDU. All methods
145 that generate a SNMP message optionally take a -contextengineid and
146 -contextname argument to configure these fields.
147 Context Engine ID
149 The -contextengineid argument expects a hexadecimal string
150 representing the desired contextEngineID. The string must be
151 10 to 64 characters (5 to 32 octets) long and can be prefixed
152 with an optional "0x". Once the -contextengineid is specified
153 it stays with the object until it is changed again or reset to
154 default by passing in the undefined value. By default, the
155 contextEngineID is set to match the authoritativeEngineID of
156 the authoritative SNMP engine.
157 Context Name
159 The contextName is passed as a string which must be 0 to 32
160 octets in length using the -contextname argument. The
161 contextName stays with the object until it is changed. The
162 contextName defaults to an empty string which represents the
163 "default" context.
164 session() - create a new Net::SNMP object
166 ($session, $error) = Net::SNMP->session(
167 [-hostname => $hostname,]
168 [-port => $port,]
169 [-localaddr => $localaddr,]
170 [-localport => $localport,]
171 [-nonblocking => $boolean,]
172 [-version => $version,]
173 [-domain => $domain,]
174 [-timeout => $seconds,]
175 [-retries => $count,]
176 [-maxmsgsize => $octets,]
177 [-translate => $translate,]
178 [-debug => $bitmask,]
179 [-community => $community,] # v1/v2c
180 [-username => $username,] # v3
181 [-authkey => $authkey,] # v3
182 [-authpassword => $authpasswd,] # v3
183 [-authprotocol => $authproto,] # v3
184 [-privkey => $privkey,] # v3
185 [-privpassword => $privpasswd,] # v3
186 [-privprotocol => $privproto,] # v3
187 );
188 This is the constructor for Net::SNMP objects. In scalar context, a
190 reference to a new Net::SNMP object is returned if the creation of the
191 object is successful. In list context, a reference to a new Net::SNMP
192 object and an empty error message string is returned. If a failure
193 occurs, the object reference is returned as the undefined value. The
194 error string may be used to determine the cause of the error.
195 Most of the named arguments passed to the constructor define basic
197 attributes for the object and are not modifiable after the object has
198 been created. The -timeout, -retries, -maxmsgsize, -translate, and
199 -debug arguments are modifiable using an accessor method. See their
200 corresponding method definitions for a complete description of their
201 usage, default values, and valid ranges.
202 Transport Domain Arguments
204 The Net::SNMP module uses UDP/IPv4 as the default Transport Domain
205 to exchange SNMP messages between the local and remote devices.
206 The module also supports UDP/IPv6, TCP/IPv4, and TCP/IPv6 as
207 alternative Transport Domains. The -domain argument can be used to
208 change the Transport Domain by setting the value to one of the
209 following strings: 'udp6', 'udp/ipv6'; 'tcp', 'tcp4', 'tcp/ipv4';
210 'tcp6', or 'tcp/ipv6'. The -domain argument also accepts the
211 strings 'udp', 'udp4', or 'udp/ipv4' which correspond to the
212 default Transport Domain of UDP/IPv4.
213 The transport address of the destination SNMP device can be
215 specified using the -hostname argument. This argument is optional
216 and defaults to "localhost". The destination port number can be
217 specified as part of the transport address or by using the -port
218 argument. Either a numeric port number or a textual service name
219 can be specified. A numeric port number in parentheses can
220 optionally follow the service name. This port number will be used
221 if the service name cannot be resolved. If the destination port
222 number is not specified, the well-known SNMP port number 161 is
223 used.
224 By default the source transport address and port number are
226 assigned dynamically by the local device on which the Net::SNMP
227 module is being used. This dynamic assignment can be overridden by
228 using the -localaddr and -localport arguments. These arguments
229 accept the same values as the -hostname and -port arguments
230 respectively. The resolved address must correspond to a valid
231 address of an interface on the local device.
232 When using an IPv4 Transport Domain, the transport address can be
234 specified as either an IP network hostname or an IPv4 address in
235 standard dotted notation. The port information can be optionally
236 appended to the hostname or address delimited by a colon. The
237 accepted IPv4 transport address formats are "address",
238 "address:port", "hostname", and "hostname:port".
239 When using an IPv6 Transport Domain, the transport address can be
241 specified as an IP hostname (which will be looked up as a DNS quad-
242 A record) or an IPv6 address in presentation format. The port
243 information can optionally be included following a colon after the
244 hostname or address. When including this information after an IPv6
245 address, the address must be enclosed in square brackets. The
246 scope zone index (described in RFC 4007) can be specified after the
247 address as a decimal value delimited by a percent sign. The
248 accepted transport address formats for IPv6 are "address",
249 "address%zone", "[address]:port", "[address%zone]:port",
250 "hostname", and "hostname:port".
251 Security Model Arguments
253 The -version argument controls which other arguments are expected
254 or required by the session() constructor. The Net::SNMP module
255 supports SNMPv1, SNMPv2c, and SNMPv3. The module defaults to
256 SNMPv1 if no -version argument is specified. The -version argument
257 expects either a digit (i.e. '1', '2', or '3') or a string
258 specifying the version (i.e. 'snmpv1', 'snmpv2c', or 'snmpv3') to
259 define the SNMP version.
260 The Security Model used by the Net::SNMP object is based on the
262 SNMP version associated with the object. If the SNMP version is
263 SNMPv1 or SNMPv2c a Community-based Security Model will be used,
264 while the User-based Security Model (USM) will be used if the
265 version is SNMPv3.
266 Community-based Security Model Argument
268 If the Security Model is Community-based, the only argument
269 available is the -community argument. This argument expects a
270 string that is to be used as the SNMP community name. By
271 default the community name is set to 'public' if the argument
272 is not present.
273 User-based Security Model Arguments
275 The User-based Security Model (USM) used by SNMPv3 requires
276 that a securityName be specified using the -username argument.
277 The creation of a Net::SNMP object with the version set to
278 SNMPv3 will fail if the -username argument is not present. The
279 -username argument expects a string 1 to 32 octets in length.
280 Different levels of security are allowed by the User-based
282 Security Model which address authentication and privacy
283 concerns. A SNMPv3 Net::SNMP object will derive the security
284 level (securityLevel) based on which of the following arguments
285 are specified.
286 By default a securityLevel of 'noAuthNoPriv' is assumed. If
288 the -authkey or -authpassword arguments are specified, the
289 securityLevel becomes 'authNoPriv'. The -authpassword argument
290 expects a string which is at least 1 octet in length.
291 Optionally, the -authkey argument can be used so that a plain
292 text password does not have to be specified in a script. The
293 -authkey argument expects a hexadecimal string produced by
294 localizing the password with the authoritativeEngineID for the
295 specific destination device. The "snmpkey" utility included
296 with the distribution can be used to create the hexadecimal
297 string (see snmpkey).
298 Two different hash algorithms are defined by SNMPv3 which can
300 be used by the Security Model for authentication. These
301 algorithms are HMAC-MD5-96 "MD5" (RFC 1321) and HMAC-SHA-96
302 "SHA-1" (NIST FIPS PUB 180-1). The default algorithm used by
303 the module is HMAC-MD5-96. This behavior can be changed by
304 using the -authprotocol argument. This argument expects either
305 the string 'md5' or 'sha' to be passed to modify the hash
306 algorithm.
307 By specifying the arguments -privkey or -privpassword the
309 securityLevel associated with the object becomes 'authPriv'.
310 According to SNMPv3, privacy requires the use of
311 authentication. Therefore, if either of these two arguments
312 are present and the -authkey or -authpassword arguments are
313 missing, the creation of the object fails. The -privkey and
314 -privpassword arguments expect the same input as the -authkey
315 and -authpassword arguments respectively.
316 The User-based Security Model described in RFC 3414 defines a
318 single encryption protocol to be used for privacy. This
319 protocol, CBC-DES "DES" (NIST FIPS PUB 46-1), is used by
320 default or if the string 'des' is passed to the -privprotocol
321 argument. The module also supports RFC 3826 which describes
322 the use of CFB128-AES-128 "AES" (NIST FIPS PUB 197) in the USM.
323 The AES encryption protocol can be selected by passing 'aes' or
324 'aes128' to the -privprotocol argument. By working with the
325 Extended Security Options Consortium
326 <http://www.snmp.com/protocol/eso.shtml>, the module also
327 supports CBC-3DES-EDE "Triple-DES" (NIST FIPS 46-3) in the
328 User-based Security Model. This is defined in the draft
329 <http://www.snmp.com/eso/draft-reeder-snmpv3-usm-3desede-00.txt>.
330 The Triple-DES encryption protocol can be selected using the
331 -privprotocol argument with the string '3des' or '3desede'.
332 close() - clear the Transport Domain associated with the object
334 $session->close();
335 This method clears the Transport Domain and any errors associated with
337 the object. Once closed, the Net::SNMP object can no longer be used to
338 send or receive SNMP messages.
339 snmp_dispatcher() - enter the non-blocking object event loop
341 $session->snmp_dispatcher();
342 This method enters the event loop associated with non-blocking
344 Net::SNMP objects. The method exits when all queued SNMP messages have
345 received a response or have timed out at the Transport Layer. This
346 method is also exported as the stand alone function snmp_dispatcher()
347 by default (see "EXPORTS").
348 get_request() - send a SNMP get-request to the remote agent
350 $result = $session->get_request(
351 [-callback => sub {},] # non-blocking
352 [-delay => $seconds,] # non-blocking
353 [-contextengineid => $engine_id,] # v3
354 [-contextname => $name,] # v3
355 -varbindlist => \@oids,
356 );
357 This method performs a SNMP get-request query to gather data from the
359 remote agent on the host associated with the Net::SNMP object. The
360 message is built using the list of OBJECT IDENTIFIERs in dotted
361 notation passed to the method as an array reference using the
362 -varbindlist argument. Each OBJECT IDENTIFIER is placed into a single
363 SNMP GetRequest-PDU in the same order that it held in the original
364 list.
365 A reference to a hash is returned in blocking mode which contains the
367 contents of the VarBindList. In non-blocking mode, a true value is
368 returned when no error has occurred. In either mode, the undefined
369 value is returned when an error has occurred. The error() method may
370 be used to determine the cause of the failure.
371 get_next_request() - send a SNMP get-next-request to the remote agent
373 $result = $session->get_next_request(
374 [-callback => sub {},] # non-blocking
375 [-delay => $seconds,] # non-blocking
376 [-contextengineid => $engine_id,] # v3
377 [-contextname => $name,] # v3
378 -varbindlist => \@oids,
379 );
380 This method performs a SNMP get-next-request query to gather data from
382 the remote agent on the host associated with the Net::SNMP object. The
383 message is built using the list of OBJECT IDENTIFIERs in dotted
384 notation passed to the method as an array reference using the
385 -varbindlist argument. Each OBJECT IDENTIFER is placed into a single
386 SNMP GetNextRequest-PDU in the same order that it held in the original
387 list.
388 A reference to a hash is returned in blocking mode which contains the
390 contents of the VarBindList. In non-blocking mode, a true value is
391 returned when no error has occurred. In either mode, the undefined
392 value is returned when an error has occurred. The error() method may
393 be used to determine the cause of the failure.
394 set_request() - send a SNMP set-request to the remote agent
396 $result = $session->set_request(
397 [-callback => sub {},] # non-blocking
398 [-delay => $seconds,] # non-blocking
399 [-contextengineid => $engine_id,] # v3
400 [-contextname => $name,] # v3
401 -varbindlist => \@oid_value,
402 );
403 This method is used to modify data on the remote agent that is
405 associated with the Net::SNMP object using a SNMP set-request. The
406 message is built using a list of values consisting of groups of an
407 OBJECT IDENTIFIER, an object type, and the actual value to be set.
408 This list is passed to the method as an array reference using the
409 -varbindlist argument. The OBJECT IDENTIFIERs in each trio are to be
410 in dotted notation. The object type is an octet corresponding to the
411 ASN.1 type of value that is to be set. Each of the supported ASN.1
412 types have been defined and are exported by the package by default (see
413 "EXPORTS").
414 A reference to a hash is returned in blocking mode which contains the
416 contents of the VarBindList. In non-blocking mode, a true value is
417 returned when no error has occurred. In either mode, the undefined
418 value is returned when an error has occurred. The error() method may
419 be used to determine the cause of the failure.
420 trap() - send a SNMP trap to the remote manager
422 $result = $session->trap(
423 [-delay => $seconds,] # non-blocking
424 [-enterprise => $oid,]
425 [-agentaddr => $ipaddress,]
426 [-generictrap => $generic,]
427 [-specifictrap => $specific,]
428 [-timestamp => $timeticks,]
429 -varbindlist => \@oid_value,
430 );
431 This method sends a SNMP trap to the remote manager associated with the
433 Net::SNMP object. All arguments are optional and will be given the
434 following defaults in the absence of a corresponding named argument:
435 • The default value for the trap -enterprise is "1.3.6.1.4.1", which
437 corresponds to "iso.org.dod.internet.private.enterprises". The
438 enterprise value is expected to be an OBJECT IDENTIFER in dotted
439 notation.
440 • When the Transport Domain is UDP/IPv4 or TCP/IPv4, the default
442 value for the trap -agentaddr is the IP address associated with the
443 interface on which the trap will be transmitted. For other
444 Transport Domains the -agentaddr is defaulted to "0.0.0.0". When
445 specified, the agent-addr is expected to be an IpAddress in dotted
446 notation.
447 • The default value for the -generictrap type is 6 which corresponds
449 to "enterpriseSpecific". The generic-trap types are defined and
450 can be exported upon request (see "EXPORTS").
451 • The default value for the -specifictrap type is 0. No pre-defined
453 values are available for specific-trap types.
454 • The default value for the trap -timestamp is the "uptime" of the
456 script. The "uptime" of the script is the number of hundredths of
457 seconds that have elapsed since the script began running. The
458 time-stamp is expected to be a TimeTicks number in hundredths of
459 seconds.
460 • The default value for the trap -varbindlist is an empty array
462 reference. The variable-bindings are expected to be in an array
463 format consisting of groups of an OBJECT IDENTIFIER, an object
464 type, and the actual value of the object. This is identical to the
465 list expected by the set_request() method. The OBJECT IDENTIFIERs
466 in each trio are to be in dotted notation. The object type is an
467 octet corresponding to the ASN.1 type for the value. Each of the
468 supported types have been defined and are exported by default (see
469 "EXPORTS").
470 A true value is returned when the method is successful. The undefined
472 value is returned when a failure has occurred. The error() method can
473 be used to determine the cause of the failure. Since there are no
474 acknowledgements for Trap-PDUs, there is no way to determine if the
475 remote host actually received the trap.
476 NOTE: When the object is in non-blocking mode, the trap is not sent
478 until the event loop is entered and no callback is ever executed.
479 NOTE: This method can only be used when the version of the object is
481 set to SNMPv1.
482 get_bulk_request() - send a SNMP get-bulk-request to the remote agent
484 $result = $session->get_bulk_request(
485 [-callback => sub {},] # non-blocking
486 [-delay => $seconds,] # non-blocking
487 [-contextengineid => $engine_id,] # v3
488 [-contextname => $name,] # v3
489 [-nonrepeaters => $non_reps,]
490 [-maxrepetitions => $max_reps,]
491 -varbindlist => \@oids,
492 );
493 This method performs a SNMP get-bulk-request query to gather data from
495 the remote agent on the host associated with the Net::SNMP object. All
496 arguments are optional except -varbindlist and will be given the
497 following defaults in the absence of a corresponding named argument:
498 • The default value for the get-bulk-request -nonrepeaters is 0. The
500 non-repeaters value specifies the number of variables in the
501 variable-bindings list for which a single successor is to be
502 returned.
503 • The default value for the get-bulk-request -maxrepetitions is 0.
505 The max-repetitions value specifies the number of successors to be
506 returned for the remaining variables in the variable-bindings list.
507 • The -varbindlist argument expects an array reference consisting of
509 a list of OBJECT IDENTIFIERs in dotted notation. Each OBJECT
510 IDENTIFER is placed into a single SNMP GetBulkRequest-PDU in the
511 same order that it held in the original list.
512 A reference to a hash is returned in blocking mode which contains the
514 contents of the VarBindList. In non-blocking mode, a true value is
515 returned when no error has occurred. In either mode, the undefined
516 value is returned when an error has occurred. The error() method may
517 be used to determine the cause of the failure.
518 NOTE: This method can only be used when the version of the object is
520 set to SNMPv2c or SNMPv3.
521 inform_request() - send a SNMP inform-request to the remote manager
523 $result = $session->inform_request(
524 [-callback => sub {},] # non-blocking
525 [-delay => $seconds,] # non-blocking
526 [-contextengineid => $engine_id,] # v3
527 [-contextname => $name,] # v3
528 -varbindlist => \@oid_value,
529 );
530 This method is used to provide management information to the remote
532 manager associated with the Net::SNMP object using an inform-request.
533 The message is built using a list of values consisting of groups of an
534 OBJECT IDENTIFIER, an object type, and the actual value to be
535 identified. This list is passed to the method as an array reference
536 using the -varbindlist argument. The OBJECT IDENTIFIERs in each trio
537 are to be in dotted notation. The object type is an octet
538 corresponding to the ASN.1 type of value that is to be identified.
539 Each of the supported ASN.1 types have been defined and are exported by
540 the package by default (see "EXPORTS").
541 The first two variable-bindings fields in the inform-request are
543 specified by SNMPv2 and should be:
544 • sysUpTime.0 - ('1.3.6.1.2.1.1.3.0', TIMETICKS, $timeticks)
546 • snmpTrapOID.0 - ('1.3.6.1.6.3.1.1.4.1.0', OBJECT_IDENTIFIER, $oid)
548 A reference to a hash is returned in blocking mode which contains the
550 contents of the VarBindList. In non-blocking mode, a true value is
551 returned when no error has occurred. In either mode, the undefined
552 value is returned when an error has occurred. The error() method may
553 be used to determine the cause of the failure.
554 NOTE: This method can only be used when the version of the object is
556 set to SNMPv2c or SNMPv3.
557 snmpv2_trap() - send a SNMP snmpV2-trap to the remote manager
559 $result = $session->snmpv2_trap(
560 [-delay => $seconds,] # non-blocking
561 -varbindlist => \@oid_value,
562 );
563 This method sends a snmpV2-trap to the remote manager associated with
565 the Net::SNMP object. The message is built using a list of values
566 consisting of groups of an OBJECT IDENTIFIER, an object type, and the
567 actual value to be identified. This list is passed to the method as an
568 array reference using the -varbindlist argument. The OBJECT
569 IDENTIFIERs in each trio are to be in dotted notation. The object type
570 is an octet corresponding to the ASN.1 type of value that is to be
571 identified. Each of the supported ASN.1 types have been defined and
572 are exported by the package by default (see "EXPORTS").
573 The first two variable-bindings fields in the snmpV2-trap are specified
575 by SNMPv2 and should be:
576 • sysUpTime.0 - ('1.3.6.1.2.1.1.3.0', TIMETICKS, $timeticks)
578 • snmpTrapOID.0 - ('1.3.6.1.6.3.1.1.4.1.0', OBJECT_IDENTIFIER, $oid)
580 A true value is returned when the method is successful. The undefined
582 value is returned when a failure has occurred. The error() method can
583 be used to determine the cause of the failure. Since there are no
584 acknowledgements for SNMPv2-Trap-PDUs, there is no way to determine if
585 the remote host actually received the snmpV2-trap.
586 NOTE: When the object is in non-blocking mode, the snmpV2-trap is not
588 sent until the event loop is entered and no callback is ever executed.
589 NOTE: This method can only be used when the version of the object is
591 set to SNMPv2c. SNMPv2-Trap-PDUs are supported by SNMPv3, but require
592 the sender of the message to be an authoritative SNMP engine which is
593 not currently supported by the Net::SNMP module.
594 get_table() - retrieve a table from the remote agent
596 $result = $session->get_table(
597 [-callback => sub {},] # non-blocking
598 [-delay => $seconds,] # non-blocking
599 [-contextengineid => $engine_id,] # v3
600 [-contextname => $name,] # v3
601 -baseoid => $oid,
602 [-maxrepetitions => $max_reps,] # v2c/v3
603 );
604 This method performs repeated SNMP get-next-request or get-bulk-request
606 (when using SNMPv2c or SNMPv3) queries to gather data from the remote
607 agent on the host associated with the Net::SNMP object. The first
608 message sent is built using the OBJECT IDENTIFIER in dotted notation
609 passed to the method by the -baseoid argument. Repeated SNMP requests
610 are issued until the OBJECT IDENTIFIER in the response is no longer a
611 child of the base OBJECT IDENTIFIER.
612 The -maxrepetitions argument can be used to specify the max-repetitions
614 value that is passed to the get-bulk-requests when using SNMPv2c or
615 SNMPv3. If this argument is not present, a value is calculated based
616 on the maximum message size for the Net::SNMP object. If the value is
617 set to 1 or less, get-next-requests will be used for the queries
618 instead of get-bulk-requests.
619 A reference to a hash is returned in blocking mode which contains the
621 contents of the VarBindList. In non-blocking mode, a true value is
622 returned when no error has occurred. In either mode, the undefined
623 value is returned when an error has occurred. The error() method may
624 be used to determine the cause of the failure.
625 WARNING: Results from this method can become very large if the base
627 OBJECT IDENTIFIER is close to the root of the SNMP MIB tree.
628 get_entries() - retrieve table entries from the remote agent
630 $result = $session->get_entries(
631 [-callback => sub {},] # non-blocking
632 [-delay => $seconds,] # non-blocking
633 [-contextengineid => $engine_id,] # v3
634 [-contextname => $name,] # v3
635 -columns => \@columns,
636 [-startindex => $start,]
637 [-endindex => $end,]
638 [-maxrepetitions => $max_reps,] # v2c/v3
639 );
640 This method performs repeated SNMP get-next-request or get-bulk-request
642 (when using SNMPv2c or SNMPv3) queries to gather data from the remote
643 agent on the host associated with the Net::SNMP object. Each message
644 specifically requests data for each OBJECT IDENTIFIER specified in the
645 -columns array. The OBJECT IDENTIFIERs must correspond to column
646 entries for a conceptual row in a table. They may however be columns
647 in different tables as long as each table is indexed the same way. The
648 optional -startindex and -endindex arguments may be specified to limit
649 the query to specific rows in the table(s).
650 The -startindex can be specified as a single decimal value or in dotted
652 notation if the index associated with the entry so requires. If the
653 -startindex is specified, it will be include as part of the query
654 results. If no -startindex is specified, the first request message
655 will be sent without an index. To insure that the -startindex is
656 included, the last sub-identifier in the index is decremented by one.
657 If the last sub-identifier has a value of zero, the sub-identifier is
658 removed from the index.
659 The optional -endindex argument can be specified as a single decimal
661 value or in dotted notation. If the -endindex is specified, it will be
662 included as part of the query results. If no -endindex is specified,
663 repeated SNMP requests are issued until the response no longer returns
664 entries matching any of the columns specified in the -columns array.
665 The -maxrepetitions argument can be used to specify the max-repetitions
667 value that is passed to the get-bulk-requests when using SNMPv2c or
668 SNMPv3. If this argument is not present, a value is calculated based
669 on the maximum message size of the object and the number of columns
670 specified in the -columns array. If the value is set to 1 or less,
671 get-next-requests will be used for the queries instead of get-bulk-
672 requests.
673 A reference to a hash is returned in blocking mode which contains the
675 contents of the VarBindList. In non-blocking mode, a true value is
676 returned when no error has occurred. In either mode, the undefined
677 value is returned when an error has occurred. The error() method may
678 be used to determine the cause of the failure.
679 version() - get the SNMP version from the object
681 $rfc_version = $session->version();
682 This method returns the current value for the SNMP version associated
684 with the object. The returned value is the corresponding version
685 number defined by the RFCs for the protocol version field (i.e. SNMPv1
686 == 0, SNMPv2c == 1, and SNMPv3 == 3). The RFC versions are defined as
687 constant by the module and can be exported by request (see "EXPORTS").
688 error() - get the current error message from the object
690 $error_message = $session->error();
691 This method returns a text string explaining the reason for the last
693 error. An empty string is returned if no error has occurred.
694 hostname() - get the hostname associated with the object
696 $hostname = $session->hostname();
697 This method returns the parsed hostname string that is associated with
699 the object. Any port information and formatting that can be included
700 with the corresponding session() constructor argument will be stripped
701 and not included as part of the returned string.
702 error_status() - get the current SNMP error-status from the object
704 $error_status = $session->error_status();
705 This method returns the numeric value of the error-status contained in
707 the last SNMP message received by the object.
708 error_index() - get the current SNMP error-index from the object
710 $error_index = $session->error_index();
711 This method returns the numeric value of the error-index contained in
713 the last SNMP message received by the object.
714 var_bind_list() - get the hash reference for the VarBindList values
716 $values = $session->var_bind_list();
717 This method returns a hash reference created using the ObjectName and
719 the ObjectSyntax pairs in the VarBindList of the last SNMP message
720 received by the object. The keys of the hash consist of the OBJECT
721 IDENTIFIERs in dotted notation corresponding to each ObjectName in the
722 VarBindList. If any of the OBJECT IDENTIFIERs passed to the request
723 method began with a leading dot, all of the OBJECT IDENTIFIER hash keys
724 will be prefixed with a leading dot. If duplicate OBJECT IDENTIFIERs
725 are present in the VarBindList they will be padded with spaces to make
726 them an unique hash key. The value of each hash entry is set equal to
727 the value of the corresponding ObjectSyntax. The undefined value is
728 returned if there has been a failure.
729 var_bind_names() - get the array of the ObjectNames in the VarBindList
731 @names = $session->var_bind_names();
732 This method returns an array containing the OBJECT IDENTIFIERs
734 corresponding to the ObjectNames in the VarBindList in the order that
735 they were received in the last SNMP message. The entries in the array
736 will map directly to the keys in the hash reference returned by the
737 methods that perform SNMP message exchanges and by the var_bind_list()
738 and var_bind_types() methods. The array returned for the convenience
739 methods get_table() and get_entries() will be in lexicographical order.
740 An empty array is returned if there has been a failure.
741 var_bind_types() - get the hash reference for the VarBindList ASN.1 types
743 $types = $session->var_bind_types();
744 This method returns a hash reference created using the ObjectName and
746 the ASN.1 type of the ObjectSyntax in the VarBindList of the last SNMP
747 message received by the object. The keys of the hash consist of the
748 OBJECT IDENTIFIERs in dotted notation corresponding to each ObjectName
749 in the VarBindList. The value of each hash entry is set equal to the
750 ASN.1 type of the corresponding ObjectSyntax. Constants for the
751 supported ASN.1 types have been defined and are exported by the package
752 by default (see "EXPORTS"). The undefined value is returned if there
753 has been a failure.
754 timeout() - set or get the current timeout period for the object
756 $seconds = $session->timeout([$seconds]);
757 This method returns the current value for the Transport Layer timeout
759 for the Net::SNMP object. This value is the number of seconds that the
760 object will wait for a response from the agent on the remote host. The
761 default timeout is 5.0 seconds.
762 If a parameter is specified, the timeout for the object is set to the
764 provided value if it falls within the range 1.0 to 60.0 seconds. The
765 undefined value is returned upon an error and the error() method may be
766 used to determine the cause.
767 retries() - set or get the current retry count for the object
769 $count = $session->retries([$count]);
770 This method returns the current value for the number of times to retry
772 sending a SNMP message to the remote host. The default number of
773 retries is 1.
774 If a parameter is specified, the number of retries for the object is
776 set to the provided value if it falls within the range 0 to 20. The
777 undefined value is returned upon an error and the error() method may be
778 used to determine the cause.
779 max_msg_size() - set or get the current maxMsgSize for the object
781 $octets = $session->max_msg_size([$octets]);
782 This method returns the current value for the maximum message size
784 (maxMsgSize) for the Net::SNMP object. This value is the largest
785 message size in octets that can be prepared or processed by the object.
786 The default maxMsgSize is 1472 octets for UDP/IPv4, 1452 octets for
787 UDP/IPv6, 1460 octets for TCP/IPv4, and 1440 octets for TCP/IPv6.
788 If a parameter is specified, the maxMsgSize is set to the provided
790 value if it falls within the range 484 to 65535 octets. The undefined
791 value is returned upon an error and the error() method may be used to
792 determine the cause.
793 NOTE: When using SNMPv3, the maxMsgSize is actually contained in the
795 SNMP message (as msgMaxSize). If the value received from a remote
796 device is less than the current maxMsgSize, the size is automatically
797 adjusted to be the lower value.
798 translate() - enable or disable the translation mode for the object
800 $mask = $session->translate([
801 $mode |
802 [ # Perl anonymous ARRAY reference
803 ['-all' => $mode0,]
804 ['-octetstring' => $mode1,]
805 ['-null' => $mode2,]
806 ['-timeticks' => $mode3,]
807 ['-opaque' => $mode4,]
808 ['-nosuchobject' => $mode5,]
809 ['-nosuchinstance' => $mode6,]
810 ['-endofmibview' => $mode7,]
811 ['-unsigned' => $mode8]
812 ]
813 ]);
814 When the object decodes the GetResponse-PDU that is returned in
816 response to a SNMP message, certain values are translated into a more
817 "human readable" form. By default the following translations occur:
818 • OCTET STRINGs and Opaques containing any octet which is not part of
820 the character set defined as a DisplayString in RFC 2679 are
821 converted into a hexadecimal representation prefixed with "0x".
822 The control codes NUL(0x00), BEL(0x07), BS(0x08), HT(0x09),
823 LF(0x0A), VT(0x0b), FF(0x0C), and CR(0x0D) are part of the
824 character set and will not trigger translation. The sequence 'CR
825 x' for any x other than LF or NUL is illegal and will trigger
826 translation.
827 • TimeTicks integer values are converted to a time format.
829 • NULL values return the string "NULL" instead of an empty string.
831 • noSuchObject exception values return the string "noSuchObject"
833 instead of an empty string.
834 • noSuchInstance exception values return the string "noSuchInstance"
836 instead of an empty string.
837 • endOfMibView exception values return the string "endOfMibView"
839 instead of an empty string.
840 • Counter64, Counter, Gauge, and TimeTick values that have been
842 incorrectly encoded as signed negative values are returned as
843 unsigned values.
844 The translate() method can be invoked with two different types of
846 arguments.
847 If the argument passed is any Perl variable type except an array
849 reference, the translation mode for all ASN.1 types is set to either
850 enabled or disabled, depending on the value of the passed parameter.
851 Any value that Perl would treat as a true value will set the mode to be
852 enabled for all types, while a false value will disable translation for
853 all types.
854 A reference to an array can be passed to the translate() method in
856 order to define the translation mode on a per ASN.1 type basis. The
857 array is expected to contain a list of named argument pairs for each
858 ASN.1 type that is to be modified. The arguments in the list are
859 applied in the order that they are passed in via the array. Arguments
860 at the end of the list supercede those passed earlier in the list. The
861 argument "-all" can be used to specify that the mode is to apply to all
862 ASN.1 types. Only the arguments for the ASN.1 types that are to be
863 modified need to be included in the list.
864 The translate() method returns a bit mask indicating which ASN.1 types
866 are to be translated. Definitions of the bit to ASN.1 type mappings
867 can be exported using the :translate tag (see "EXPORTS"). The
868 undefined value is returned upon an error and the error() method may be
869 used to determine the cause.
870 debug() - set or get the debug mode for the module
872 $mask = $session->debug([$mask]);
873 This method is used to enable or disable debugging for the Net::SNMP
875 module. Debugging can be enabled on a per component level as defined
876 by a bit mask passed to the debug() method. The bit mask is broken up
877 as follows:
878 • 0x02 - Message or PDU encoding and decoding
880 • 0x04 - Transport Layer
882 • 0x08 - Dispatcher
884 • 0x10 - Message Processing
886 • 0x20 - Security
888 Symbols representing these bit mask values are defined by the module
890 and can be exported using the :debug tag (see "EXPORTS"). If a non-
891 numeric value is passed to the debug() method, it is evaluated in
892 boolean context. Debugging for all of the components is then enabled
893 or disabled based on the resulting truth value.
894 The current debugging mask is returned by the method. Debugging can
896 also be enabled using the stand alone function snmp_debug(). This
897 function can be exported by request (see "EXPORTS").
898
900 oid_base_match() - determine if an OID has a specified OID base
901 $value = oid_base_match($base_oid, $oid);
902 This function takes two OBJECT IDENTIFIERs in dotted notation and
904 returns a true value (i.e. 0x1) if the second OBJECT IDENTIFIER is
905 equal to or is a child of the first OBJECT IDENTIFIER in the SNMP
906 Management Information Base (MIB). This function can be used in
907 conjunction with the "get-next-request()" or "get-bulk-request()"
908 methods to determine when a OBJECT IDENTIFIER in the GetResponse-PDU is
909 no longer in the desired MIB tree branch.
910 oid_lex_cmp() - compare two OBJECT IDENTIFIERs lexicographically
912 $cmp = oid_lex_cmp($oid1, $oid2);
913 This function takes two OBJECT IDENTIFIERs in dotted notation and
915 returns one of the values 1, 0, -1 if $oid1 is respectively
916 lexicographically greater, equal, or less than $oid2.
917 oid_lex_sort() - sort a list of OBJECT IDENTIFIERs lexicographically
919 @sorted_oids = oid_lex_sort(@oids);
920 This function takes a list of OBJECT IDENTIFIERs in dotted notation and
922 returns the listed sorted in lexicographical order.
923 snmp_type_ntop() - convert an ASN.1 type to presentation format
925 $text = snmp_type_ntop($type);
926 This function takes an ASN.1 type octet and returns a text string
928 suitable for presentation. Some ASN.1 type definitions map to the same
929 octet value when encoded. This method cannot distinguish between these
930 multiple mappings and the most basic type name will be returned.
931 ticks_to_time() - convert TimeTicks to formatted time
933 $time = ticks_to_time($timeticks);
934 This function takes an ASN.1 TimeTicks value and returns a string
936 representing the time defined by the value. The TimeTicks value is
937 expected to be a non-negative integer value representing the time in
938 hundredths of a second since some epoch. The returned string will
939 display the time in days, hours, and seconds format according to the
940 value of the TimeTicks argument.
941
943 The Net::SNMP module uses the Exporter module to export useful
944 constants and subroutines. These exportable symbols are defined below
945 and follow the rules and conventions of the Exporter module (see
946 Exporter).
947 Default
949 &snmp_dispatcher, INTEGER, INTEGER32, OCTET_STRING,
950 OBJECT_IDENTIFIER, IPADDRESS, COUNTER, COUNTER32, GAUGE, GAUGE32,
951 UNSIGNED32, TIMETICKS, OPAQUE, COUNTER64, NOSUCHOBJECT,
952 NOSUCHINSTANCE, ENDOFMIBVIEW
953 Exportable
955 &snmp_debug, &snmp_dispatcher, &snmp_type_ntop, &oid_base_match,
956 &oid_lex_cmp, &oid_lex_sort,&ticks_to_time, INTEGER, INTEGER32,
957 OCTET_STRING, NULL, OBJECT_IDENTIFIER, SEQUENCE, IPADDRESS,
958 COUNTER, COUNTER32, GAUGE, GAUGE32, UNSIGNED32, TIMETICKS, OPAQUE,
959 COUNTER64, NOSUCHOBJECT, NOSUCHINSTANCE, ENDOFMIBVIEW, GET_REQUEST,
960 GET_NEXT_REQUEST, GET_RESPONSE, SET_REQUEST, TRAP,
961 GET_BULK_REQUEST, INFORM_REQUEST, SNMPV2_TRAP, REPORT, DEBUG_ALL,
962 DEBUG_NONE, DEBUG_MESSAGE, DEBUG_TRANSPORT,
963 DEBUG_DISPATCHER,DEBUG_PROCESSING, DEBUG_SECURITY, COLD_START,
964 WARM_START, LINK_DOWN, LINK_UP, AUTHENTICATION_FAILURE,
965 EGP_NEIGHBOR_LOSS, ENTERPRISE_SPECIFIC, SNMP_VERSION_1,
966 SNMP_VERSION_2C, SNMP_VERSION_3, SNMP_PORT, SNMP_TRAP_PORT,
967 TRANSLATE_NONE,TRANSLATE_OCTET_STRING, TRANSLATE_NULL,
968 TRANSLATE_TIMETICKS, TRANSLATE_OPAQUE,TRANSLATE_NOSUCHOBJECT,
969 TRANSLATE_NOSUCHINSTANCE, TRANSLATE_ENDOFMIBVIEW,
970 TRANSLATE_UNSIGNED, TRANSLATE_ALL
971 Tags
973 :asn1
974 INTEGER, INTEGER32, OCTET_STRING, NULL, OBJECT_IDENTIFIER,
975 SEQUENCE, IPADDRESS, COUNTER, COUNTER32, GAUGE, GAUGE32,
976 UNSIGNED32, TIMETICKS, OPAQUE, COUNTER64, NOSUCHOBJECT,
977 NOSUCHINSTANCE, ENDOFMIBVIEW, GET_REQUEST, GET_NEXT_REQUEST,
978 GET_RESPONSE, SET_REQUEST, TRAP, GET_BULK_REQUEST,
979 INFORM_REQUEST, SNMPV2_TRAP, REPORT
980 :debug
982 &snmp_debug, DEBUG_ALL, DEBUG_NONE, DEBUG_MESSAGE,
983 DEBUG_TRANSPORT, DEBUG_DISPATCHER, DEBUG_PROCESSING,
984 DEBUG_SECURITY
985 :generictrap
987 COLD_START, WARM_START, LINK_DOWN, LINK_UP,
988 AUTHENTICATION_FAILURE, EGP_NEIGHBOR_LOSS, ENTERPRISE_SPECIFIC
989 :snmp
991 &snmp_debug, &snmp_dispatcher, &snmp_type_ntop,
992 &oid_base_match, &oid_lex_cmp, &oid_lex_sort, &ticks_to_time,
993 SNMP_VERSION_1, SNMP_VERSION_2C, SNMP_VERSION_3, SNMP_PORT,
994 SNMP_TRAP_PORT
995 :translate
997 TRANSLATE_NONE, TRANSLATE_OCTET_STRING, TRANSLATE_NULL,
998 TRANSLATE_TIMETICKS, TRANSLATE_OPAQUE, TRANSLATE_NOSUCHOBJECT,
999 TRANSLATE_NOSUCHINSTANCE, TRANSLATE_ENDOFMIBVIEW,
1000 TRANSLATE_UNSIGNED, TRANSLATE_ALL
1001 :ALL
1003 All of the above exportable items.
1004
1006 1. Blocking SNMPv1 get-request for sysUpTime
1007 This example gets the sysUpTime from a remote host.
1008 #! /usr/local/bin/perl
1010 use strict;
1012 use warnings;
1013 use Net::SNMP;
1015 my $OID_sysUpTime = '1.3.6.1.2.1.1.3.0';
1017 my ($session, $error) = Net::SNMP->session(
1019 -hostname => shift || 'localhost',
1020 -community => shift || 'public',
1021 );
1022 if (!defined $session) {
1024 printf "ERROR: %s.\n", $error;
1025 exit 1;
1026 }
1027 my $result = $session->get_request(-varbindlist => [ $OID_sysUpTime ],);
1029 if (!defined $result) {
1031 printf "ERROR: %s.\n", $session->error();
1032 $session->close();
1033 exit 1;
1034 }
1035 printf "The sysUpTime for host '%s' is %s.\n",
1037 $session->hostname(), $result->{$OID_sysUpTime};
1038 $session->close();
1040 exit 0;
1042 2. Blocking SNMPv3 set-request of sysContact
1044 This example sets the sysContact information on the remote host to
1045 "Help Desk x911". The named arguments passed to the session()
1046 constructor are for the demonstration of syntax only. These parameters
1047 will need to be set according to the SNMPv3 parameters of the remote
1048 host. The "snmpkey" utility included with the distribution can be used
1049 to create the key values.
1050 #! /usr/local/bin/perl
1052 use strict;
1054 use warnings;
1055 use Net::SNMP;
1057 my $OID_sysContact = '1.3.6.1.2.1.1.4.0';
1059 my ($session, $error) = Net::SNMP->session(
1061 -hostname => 'myv3host.example.com',
1062 -version => 'snmpv3',
1063 -username => 'myv3Username',
1064 -authprotocol => 'sha1',
1065 -authkey => '0x6695febc9288e36282235fc7151f128497b38f3f',
1066 -privprotocol => 'des',
1067 -privkey => '0x6695febc9288e36282235fc7151f1284',
1068 );
1069 if (!defined $session) {
1071 printf "ERROR: %s.\n", $error;
1072 exit 1;
1073 }
1074 my $result = $session->set_request(
1076 -varbindlist => [ $OID_sysContact, OCTET_STRING, 'Help Desk x911' ],
1077 );
1078 if (!defined $result) {
1080 printf "ERROR: %s.\n", $session->error();
1081 $session->close();
1082 exit 1;
1083 }
1084 printf "The sysContact for host '%s' was set to '%s'.\n",
1086 $session->hostname(), $result->{$OID_sysContact};
1087 $session->close();
1089 exit 0;
1091 3. Non-blocking SNMPv2c get-bulk-request for ifTable
1093 This example gets the contents of the ifTable by sending get-bulk-
1094 requests until the responses are no longer part of the ifTable. The
1095 ifTable can also be retrieved using the get_table() method. The
1096 ifPhysAddress object in the table has a syntax of an OCTET STRING. By
1097 default, translation is enabled and non-printable OCTET STRINGs are
1098 translated into a hexadecimal format. Sometimes the OCTET STRING
1099 contains all printable characters and this produces unexpected output
1100 when it is not translated. The example turns off translation for OCTET
1101 STRINGs and specifically formats the output for the ifPhysAddress
1102 objects.
1103 #! /usr/local/bin/perl
1105 use strict;
1107 use warnings;
1108 use Net::SNMP qw(:snmp);
1110 my $OID_ifTable = '1.3.6.1.2.1.2.2';
1112 my $OID_ifPhysAddress = '1.3.6.1.2.1.2.2.1.6';
1113 my ($session, $error) = Net::SNMP->session(
1115 -hostname => shift || 'localhost',
1116 -community => shift || 'public',
1117 -nonblocking => 1,
1118 -translate => [-octetstring => 0],
1119 -version => 'snmpv2c',
1120 );
1121 if (!defined $session) {
1123 printf "ERROR: %s.\n", $error;
1124 exit 1;
1125 }
1126 my %table; # Hash to store the results
1128 my $result = $session->get_bulk_request(
1130 -varbindlist => [ $OID_ifTable ],
1131 -callback => [ \&table_callback, \%table ],
1132 -maxrepetitions => 10,
1133 );
1134 if (!defined $result) {
1136 printf "ERROR: %s\n", $session->error();
1137 $session->close();
1138 exit 1;
1139 }
1140 # Now initiate the SNMP message exchange.
1142 snmp_dispatcher();
1144 $session->close();
1146 # Print the results, specifically formatting ifPhysAddress.
1148 for my $oid (oid_lex_sort(keys %table)) {
1150 if (!oid_base_match($OID_ifPhysAddress, $oid)) {
1151 printf "%s = %s\n", $oid, $table{$oid};
1152 } else {
1153 printf "%s = %s\n", $oid, unpack 'H*', $table{$oid};
1154 }
1155 }
1156 exit 0;
1158 sub table_callback
1160 {
1161 my ($session, $table) = @_;
1162 my $list = $session->var_bind_list();
1164 if (!defined $list) {
1166 printf "ERROR: %s\n", $session->error();
1167 return;
1168 }
1169 # Loop through each of the OIDs in the response and assign
1171 # the key/value pairs to the reference that was passed with
1172 # the callback. Make sure that we are still in the table
1173 # before assigning the key/values.
1174 my @names = $session->var_bind_names();
1176 my $next = undef;
1177 while (@names) {
1179 $next = shift @names;
1180 if (!oid_base_match($OID_ifTable, $next)) {
1181 return; # Table is done.
1182 }
1183 $table->{$next} = $list->{$next};
1184 }
1185 # Table is not done, send another request, starting at the last
1187 # OBJECT IDENTIFIER in the response. No need to include the
1188 # calback argument, the same callback that was specified for the
1189 # original request will be used.
1190 my $result = $session->get_bulk_request(
1192 -varbindlist => [ $next ],
1193 -maxrepetitions => 10,
1194 );
1195 if (!defined $result) {
1197 printf "ERROR: %s.\n", $session->error();
1198 }
1199 return;
1201 }
1202 4. Non-blocking SNMPv1 get-request and set-request on multiple hosts
1204 This example first polls several hosts for their sysUpTime. If the
1205 poll of the host is successful, the sysContact and sysLocation
1206 information is set on the host. The sysContact information is
1207 hardcoded to "Help Desk x911" while the sysLocation information is
1208 passed as an argument to the callback.
1209 #! /usr/local/bin/perl
1211 use strict;
1213 use warnings;
1214 use Net::SNMP;
1216 my $OID_sysUpTime = '1.3.6.1.2.1.1.3.0';
1218 my $OID_sysContact = '1.3.6.1.2.1.1.4.0';
1219 my $OID_sysLocation = '1.3.6.1.2.1.1.6.0';
1220 # Hash of hosts and location data.
1222 my %host_data = (
1224 '10.1.1.2' => 'Building 1, Second Floor',
1225 '10.2.1.1' => 'Building 2, First Floor',
1226 'localhost' => 'Right here!',
1227 );
1228 # Create a session for each host and queue a get-request for sysUpTime.
1230 for my $host (keys %host_data) {
1232 my ($session, $error) = Net::SNMP->session(
1234 -hostname => $host,
1235 -community => 'private',
1236 -nonblocking => 1,
1237 );
1238 if (!defined $session) {
1240 printf "ERROR: Failed to create session for host '%s': %s.\n",
1241 $host, $error;
1242 next;
1243 }
1244 my $result = $session->get_request(
1246 -varbindlist => [ $OID_sysUpTime ],
1247 -callback => [ \&get_callback, $host_data{$host} ],
1248 );
1249 if (!defined $result) {
1251 printf "ERROR: Failed to queue get request for host '%s': %s.\n",
1252 $session->hostname(), $session->error();
1253 }
1254 }
1256 # Now initiate the SNMP message exchange.
1258 snmp_dispatcher();
1260 exit 0;
1262 sub get_callback
1264 {
1265 my ($session, $location) = @_;
1266 my $result = $session->var_bind_list();
1268 if (!defined $result) {
1270 printf "ERROR: Get request failed for host '%s': %s.\n",
1271 $session->hostname(), $session->error();
1272 return;
1273 }
1274 printf "The sysUpTime for host '%s' is %s.\n",
1276 $session->hostname(), $result->{$OID_sysUpTime};
1277 # Now set the sysContact and sysLocation for the host.
1279 $result = $session->set_request(
1281 -varbindlist =>
1282 [
1283 $OID_sysContact, OCTET_STRING, 'Help Desk x911',
1284 $OID_sysLocation, OCTET_STRING, $location,
1285 ],
1286 -callback => \&set_callback,
1287 );
1288 if (!defined $result) {
1290 printf "ERROR: Failed to queue set request for host '%s': %s.\n",
1291 $session->hostname(), $session->error();
1292 }
1293 return;
1295 }
1296 sub set_callback
1298 {
1299 my ($session) = @_;
1300 my $result = $session->var_bind_list();
1302 if (defined $result) {
1304 printf "The sysContact for host '%s' was set to '%s'.\n",
1305 $session->hostname(), $result->{$OID_sysContact};
1306 printf "The sysLocation for host '%s' was set to '%s'.\n",
1307 $session->hostname(), $result->{$OID_sysLocation};
1308 } else {
1309 printf "ERROR: Set request failed for host '%s': %s.\n",
1310 $session->hostname(), $session->error();
1311 }
1312 return;
1314 }
1315
1317 • The Net::SNMP module uses syntax that is not supported in versions
1318 of Perl earlier than v5.6.0.
1319 • The non-core modules Crypt::DES, Digest::MD5, Digest::SHA1, and
1321 Digest::HMAC are required to support SNMPv3.
1322 • In order to support the AES Cipher Algorithm as a SNMPv3 privacy
1324 protocol, the non-core module Crypt::Rijndael is needed.
1325 • To use UDP/IPv6 or TCP/IPv6 as a Transport Domain, the non-core
1327 module Socket6 is needed.
1328
1330 David M. Town <dtown@cpan.org>
1331
1333 The original concept for this module was based on SNMP_Session.pm
1334 written by Simon Leinen <simon@switch.ch>.
1335 The Abstract Syntax Notation One (ASN.1) encode and decode methods were
1337 originally derived by example from the CMU SNMP package whose copyright
1338 follows: Copyright (c) 1988, 1989, 1991, 1992 by Carnegie Mellon
1339 University. All rights reserved.
1340
1342 Copyright (c) 1998-2010 David M. Town. All rights reserved.
1343 This program is free software; you may redistribute it and/or modify it
1345 under the same terms as the Perl 5 programming language system itself.
1346perl v5.36.0 2023-01-20 Net::SNMP(3)