unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

Net::SNMP(3pm)        User Contributed Perl Documentation       Net::SNMP(3pm)



NAME
       Net::SNMP - Object oriented interface to SNMP

SYNOPSIS
       The Net::SNMP module implements an object oriented interface to the
       Simple Network Management Protocol.  Perl applications can use the mod-
       ule to retrieve or update information on a remote host using the SNMP
       protocol.  The module supports SNMP version-1, SNMP version-2c (Commu-
       nity-Based SNMPv2), and SNMP version-3. The Net::SNMP module assumes
       that the user has a basic understanding of the Simple Network Manage-
       ment Protocol and related network management concepts.

DESCRIPTION
       The Net::SNMP module abstracts the intricate details of the Simple Net-
       work Management Protocol by providing a high level programming inter-
       face to the protocol.  Each Net::SNMP object provides a one-to-one map-
       ping between a Perl object and a remote SNMP agent or manager.  Once an
       object is created, it can be used to perform the basic protocol
       exchange actions defined by SNMP.

       A Net::SNMP object can be created such that it has either "blocking" or
       "non-blocking" properties.  By default, the methods used to send SNMP
       messages do not return until the protocol exchange has completed suc-
       cessfully or a timeout period has expired. This behavior gives the
       object a "blocking" property because the flow of the code is stopped
       until the method returns.

       The optional named argument -nonblocking can be passed to the object
       constructor with a true value to give the object "non-blocking" behav-
       ior.  A method invoked by a non-blocking object queues the SNMP message
       and returns immediately, allowing the flow of the code to continue. The
       queued SNMP messages are not sent until an event loop is entered by
       calling the "snmp_dispatcher()" method.  When the SNMP messages are
       sent, any response to the messages invokes the subroutine defined by
       the user when the message was originally queued. The event loop exits
       when all messages have been removed from the queue by either receiving
       a response, or by exceeding the number of retries at the Transport
       Layer.

       Blocking Objects

       The default behavior of the methods associated with a Net::SNMP object
       is to block the code flow until the method completes.  For methods that
       initiate a SNMP protocol exchange requiring a response, a hash refer-
       ence containing the results of the query is returned. The undefined
       value is returned by all methods when a failure has occurred. The
       "error()" method can be used to determine the cause of the failure.

       The hash reference returned by a SNMP protocol exchange points to a
       hash constructed from the VarBindList contained in the SNMP response
       message.  The hash is created using the ObjectName and the ObjectSyntax
       pairs in the VarBindList.  The keys of the hash consist of the OBJECT
       IDENTIFIERs in dotted notation corresponding to each ObjectName in the
       VarBindList.  The value of each hash entry is set equal to the value of
       the corresponding ObjectSyntax.  This hash reference can also be
       retrieved using the "var_bind_list()" method.

       Non-blocking Objects

       When a Net::SNMP object is created having non-blocking behavior, the
       invocation of a method associated with the object returns immediately,
       allowing the flow of the code to continue.  When a method is invoked
       that would initiate a SNMP protocol exchange requiring a response,
       either a true value (i.e. 0x1) is returned immediately or the undefined
       value is returned if there was a failure.  The "error()" method can be
       used to determine the cause of the failure.

       The contents of the VarBindList contained in the SNMP response message
       can be retrieved by calling the "var_bind_list()" method using the
       object reference passed as the first argument to the callback.  The
       value returned by the "var_bind_list()" method is a hash reference cre-
       ated using the ObjectName and the ObjectSyntax pairs in the
       VarBindList.  The keys of the hash consist of the OBJECT IDENTIFIERs in
       dotted notation corresponding to each ObjectName in the VarBindList.
       The value of each hash entry is set equal to the value of the corre-
       sponding ObjectSyntax. The undefined value is returned if there has
       been a failure and the "error()" method may be used to determine the
       reason.

METHODS
       When named arguments are expected by the methods, two different styles
       are supported.  All examples in this documentation use the dashed-
       option style:

              $object->method(-argument => $value);

       However, the IO:: style is also allowed:

              $object->method(Argument => $value);

       Non-blocking Objects Arguments
           When a Net::SNMP object has been created with a "non-blocking"
           property, most methods that generate a SNMP message take additional
           arguments to support this property.

           Callback
               Most methods associated with a non-blocking object have an
               optional named argument called -callback.  The -callback argu-
               ment expects a reference to a subroutine or to an array whose
               first element must be a reference to a subroutine.  The subrou-
               tine defined by the -callback option is executed when a
               response to a SNMP message is received, an error condition has
               occurred, or the number of retries for the message has been
               exceeded.

               When the -callback argument only contains a subroutine refer-
               ence, the subroutine is evaluated passing a reference to the
               original Net::SNMP object as the only parameter.  If the -call-
               back argument was defined as an array reference, all elements
               in the array are passed to subroutine after the reference to
               the Net::SNMP object.  The first element, which is required to
               be a reference to a subroutine, is removed before the remaining
               arguments are passed to that subroutine.

               Once one method is invoked with the -callback argument, this
               argument stays with the object and is used by any further calls
               to methods using the -callback option if the argument is
               absent.  The undefined value may be passed to the -callback
               argument to delete the callback.

               NOTE: The subroutine being passed with the -callback named
               argument should not cause blocking itself.  This will cause all
               the actions in the event loop to be stopped, defeating the non-
               blocking property of the Net::SNMP module.

           Delay
               An optional argument -delay can also be passed to non-blocking
               objects.  The -delay argument instructs the object to wait the
               number of seconds passed to the argument before executing the
               SNMP protocol exchange.  The delay period starts when the event
               loop is entered.  The -delay parameter is applied to all meth-
               ods associated with the object once it is specified.  The delay
               value must be set back to 0 seconds to disable the delay param-
               eter.

       SNMPv3 Arguments
           A SNMP context is a collection of management information accessible
           by a SNMP entity.  An item of management information may exist in
           more than one context and a SNMP entity potentially has access to
           many contexts.  The combination of a contextEngineID and a con-
           textName unambiguously identifies a context within an administra-
           tive domain.  In a SNMPv3 message, the contextEngineID and con-
           textName are included as part of the scopedPDU.  All methods that
           generate a SNMP message optionally take a -contextengineid and
           -contextname argument to configure these fields.

           Context Engine ID
               The -contextengineid argument expects a hexadecimal string rep-
               resenting the desired contextEngineID.  The string must be 10
               to 64 characters (5 to 32 octets) long and can be prefixed with
               an optional "0x".  Once the -contextengineid is specified it
               stays with the object until it is changed again or reset to
               default by passing in the undefined value.  By default, the
               contextEngineID is set to match the authoritativeEngineID of
               the authoritative SNMP engine.

           Context Name
               The contextName is passed as a string which must be 0 to 32
               octets in length using the -contextname argument.  The con-
               textName stays with the object until it is changed.  The con-
               textName defaults to an empty string which represents the
               "default" context.

       session() - create a new Net::SNMP object

          ($session, $error) = Net::SNMP->session(
                                  [-hostname      => $hostname,]
                                  [-port          => $port,]
                                  [-localaddr     => $localaddr,]
                                  [-localport     => $localport,]
                                  [-nonblocking   => $boolean,]
                                  [-version       => $version,]
                                  [-domain        => $domain,]
                                  [-timeout       => $seconds,]
                                  [-retries       => $count,]
                                  [-maxmsgsize    => $octets,]
                                  [-translate     => $translate,]
                                  [-debug         => $bitmask,]
                                  [-community     => $community,]   # v1/v2c
                                  [-username      => $username,]    # v3
                                  [-authkey       => $authkey,]     # v3
                                  [-authpassword  => $authpasswd,]  # v3
                                  [-authprotocol  => $authproto,]   # v3
                                  [-privkey       => $privkey,]     # v3
                                  [-privpassword  => $privpasswd,]  # v3
                                  [-privprotocol  => $privproto,]   # v3
                               );

       This is the constructor for Net::SNMP objects.  In scalar context, a
       reference to a new Net::SNMP object is returned if the creation of the
       object is successful.  In list context, a reference to a new Net::SNMP
       object and an empty error message string is returned.  If a failure
       occurs, the object reference is returned as the undefined value.  The
       error string may be used to determine the cause of the error.

       Most of the named arguments passed to the constructor define basic
       attributes for the object and are not modifiable after the object has
       been created.  The -timeout, -retries, -maxmsgsize, -translate, and
       -debug arguments are modifiable using an accessor method.  See their
       corresponding method definitions for a complete description of their
       usage, default values, and valid ranges.

       Transport Domain Arguments
           The Net::SNMP module uses UDP/IPv4 as the default Transport Domain
           to exchange SNMP messages between the local and remote devices.
           The module also supports UDP/IPv6, TCP/IPv4, and TCP/IPv6 as alter-
           native Transport Domains.  The -domain argument can be used to
           change the Transport Domain by setting the value to one of the fol-
           lowing strings: 'udp6', 'udp/ipv6'; 'tcp', 'tcp4', 'tcp/ipv4';
           'tcp6', or 'tcp/ipv6'.  The -domain argument also accepts the
           strings 'udp', 'udp4', or 'udp/ipv4' which correspond to the
           default Transport Domain of UDP/IPv4.

           The transport address of the destination SNMP device can be speci-
           fied using the -hostname argument.  This argument is optional and
           defaults to "localhost".  The destination port number can be speci-
           fied as part of the transport address or by using the -port argu-
           ment.  Either a numeric port number or a textual service name can
           be specified.  A numeric port number in parentheses can optionally
           follow the service name.  This port number will be used if the ser-
           vice name cannot be resolved.  If the destination port number is
           not specified, the well-known SNMP port number 161 is used.

           By default the source transport address and port number are
           assigned dynamically by the local device on which the Net::SNMP
           module is being used.  This dynamic assignment can be overridden by
           using the -localaddr and -localport arguments.  These arguments
           accept the same values as the -hostname and -port arguments respec-
           tively.  The resolved address must correspond to a valid address of
           an interface on the local device.

           When using an IPv4 Transport Domain, the transport address can be
           specified as either an IP network hostname or an IPv4 address in
           standard dotted notation.  The port information can be optionally
           appended to the hostname or address delimited by a colon.  The
           accepted IPv4 transport address formats are "address",
           "address:port", "hostname", and "hostname:port".

           When using an IPv6 Transport Domain, the transport address can be
           specified as an IP hostname (which will be looked up as a DNS quad-
           A record) or an IPv6 address in presentation format.  The port
           information can optionally be included following a colon after the
           hostname or address.  When including this information after an IPv6
           address, the address must be enclosed in square brackets.  The
           scope zone index (described in RFC 4007) can be specified after the
           address as a decimal value delimited by a percent sign.  The
           accepted transport address formats for IPv6 are "address",
           "address%zone", "[address]:port", "[address%zone]:port", "host-
           name", and "hostname:port".

       Security Model Arguments
           The -version argument controls which other arguments are expected
           or required by the "session()" constructor.  The Net::SNMP module
           supports SNMPv1, SNMPv2c, and SNMPv3.  The module defaults to
           SNMPv1 if no -version argument is specified.  The -version argument
           expects either a digit (i.e.  '1', '2', or '3') or a string speci-
           fying the version (i.e. 'snmpv1', 'snmpv2c', or 'snmpv3') to define
           the SNMP version.

           The Security Model used by the Net::SNMP object is based on the
           SNMP version associated with the object.  If the SNMP version is
           SNMPv1 or SNMPv2c a Community-based Security Model will be used,
           while the User-based Security Model (USM) will be used if the ver-
           sion is SNMPv3.

           Community-based Security Model Argument
               If the Security Model is Community-based, the only argument
               available is the -community argument.  This argument expects a
               string that is to be used as the SNMP community name.  By
               default the community name is set to 'public' if the argument
               is not present.

           User-based Security Model Arguments
               The User-based Security Model (USM) used by SNMPv3 requires
               that a securityName be specified using the -username argument.
               The creation of a Net::SNMP object with the version set to
               SNMPv3 will fail if the -username argument is not present.  The
               -username argument expects a string 1 to 32 octets in length.

               Different levels of security are allowed by the User-based
               Security Model which address authentication and privacy con-
               cerns.  A SNMPv3 Net::SNMP object will derive the security
               level (securityLevel) based on which of the following arguments
               are specified.

               By default a securityLevel of 'noAuthNoPriv' is assumed.  If
               the -authkey or -authpassword arguments are specified, the
               securityLevel becomes 'authNoPriv'.  The -authpassword argument
               expects a string which is at least 1 octet in length.  Option-
               ally, the -authkey argument can be used so that a plain text
               password does not have to be specified in a script.  The
               -authkey argument expects a hexadecimal string produced by
               localizing the password with the authoritativeEngineID for the
               specific destination device.  The "snmpkey" utility included
               with the distribution can be used to create the hexadecimal
               string (see snmpkey).

               Two different hash algorithms are defined by SNMPv3 which can
               be used by the Security Model for authentication.  These algo-
               rithms are HMAC-MD5-96 "MD5" (RFC 1321) and HMAC-SHA-96 "SHA-1"
               (NIST FIPS PUB 180-1).   The default algorithm used by the mod-
               ule is HMAC-MD5-96.  This behavior can be changed by using the
               -authprotocol argument.  This argument expects either the
               string 'md5' or 'sha' to be passed to modify the hash algo-
               rithm.

               By specifying the arguments -privkey or -privpassword the secu-
               rityLevel associated with the object becomes 'authPriv'.
               According to SNMPv3, privacy requires the use of authentica-
               tion.  Therefore, if either of these two arguments are present
               and the -authkey or -authpassword arguments are missing, the
               creation of the object fails.  The -privkey and -privpassword
               arguments expect the same input as the -authkey and -authpass-
               word arguments respectively.

               The User-based Security Model described in RFC 3414 defines a
               single encryption protocol to be used for privacy.  This proto-
               col, CBC-DES "DES" (NIST FIPS PUB 46-1), is used by default or
               if the string 'des' is passed to the -privprotocol argument.
               The module also supports RFC 3826 which describes the use of
               CFB128-AES-128 "AES" (NIST FIPS PUB 197) in the USM.  The AES
               encryption protocol can be selected by passing 'aes' or
               'aes128' to the -privprotocol argument.  By working with the
               Extended Security Options Consortium
               <http://www.snmp.com/eso/>;, the module also supports
               CBC-3DES-EDE "Triple-DES" (NIST FIPS 46-3) in the User-based
               Security Model.  This is defined in the draft
               <http://www.snmp.com/eso/draft-reeder-snmpv3-usm-3desede-00.txt>;.
               The Triple-DES encryption protocol can be selected using the
               -privprotocol argument with the string '3des' or '3desede'.

       close() - clear the Transport Domain associated with the object

          $session->close;

       This method clears the Transport Domain and any errors associated with
       the object.  Once closed, the Net::SNMP object can no longer be used to
       send or receive SNMP messages.

       snmp_dispatcher() - enter the non-blocking object event loop

          $session->snmp_dispatcher();

       This method enters the event loop associated with non-blocking
       Net::SNMP objects.  The method exits when all queued SNMP messages have
       received a response or have timed out at the Transport Layer. This
       method is also exported as the stand alone function "snmp_dispatcher()"
       by default (see "EXPORTS").

       get_request() - send a SNMP get-request to the remote agent

          $result = $session->get_request(
                                 [-callback        => sub {},]     # non-blocking
                                 [-delay           => $seconds,]   # non-blocking
                                 [-contextengineid => $engine_id,] # v3
                                 [-contextname     => $name,]      # v3
                                 -varbindlist      => \@oids,
                              );

       This method performs a SNMP get-request query to gather data from the
       remote agent on the host associated with the Net::SNMP object.  The
       message is built using the list of OBJECT IDENTIFIERs in dotted nota-
       tion passed to the method as an array reference using the -varbindlist
       argument.  Each OBJECT IDENTIFER is placed into a single SNMP GetRe-
       quest-PDU in the same order that it held in the original list.

       A reference to a hash is returned in blocking mode which contains the
       contents of the VarBindList.  In non-blocking mode, a true value is
       returned when no error has occurred.  In either mode, the undefined
       value is returned when an error has occurred.  The "error()" method may
       be used to determine the cause of the failure.

       get_next_request() - send a SNMP get-next-request to the remote agent

          $result = $session->get_next_request(
                                 [-callback        => sub {},]     # non-blocking
                                 [-delay           => $seconds,]   # non-blocking
                                 [-contextengineid => $engine_id,] # v3
                                 [-contextname     => $name,]      # v3
                                 -varbindlist      => \@oids,
                              );

       This method performs a SNMP get-next-request query to gather data from
       the remote agent on the host associated with the Net::SNMP object.  The
       message is built using the list of OBJECT IDENTIFIERs in dotted nota-
       tion passed to the method as an array reference using the -varbindlist
       argument.  Each OBJECT IDENTIFER is placed into a single SNMP GetNex-
       tRequest-PDU in the same order that it held in the original list.

       A reference to a hash is returned in blocking mode which contains the
       contents of the VarBindList.  In non-blocking mode, a true value is
       returned when no error has occurred.  In either mode, the undefined
       value is returned when an error has occurred.  The "error()" method may
       be used to determine the cause of the failure.

       set_request() - send a SNMP set-request to the remote agent

          $result = $session->set_request(
                                 [-callback        => sub {},]     # non-blocking
                                 [-delay           => $seconds,]   # non-blocking
                                 [-contextengineid => $engine_id,] # v3
                                 [-contextname     => $name,]      # v3
                                 -varbindlist      => \@oid_value,
                              );

       This method is used to modify data on the remote agent that is associ-
       ated with the Net::SNMP object using a SNMP set-request.  The message
       is built using a list of values consisting of groups of an OBJECT IDEN-
       TIFIER, an object type, and the actual value to be set.  This list is
       passed to the method as an array reference using the -varbindlist argu-
       ment.  The OBJECT IDENTIFIERs in each trio are to be in dotted nota-
       tion.  The object type is an octet corresponding to the ASN.1 type of
       value that is to be set.  Each of the supported ASN.1 types have been
       defined and are exported by the package by default (see "EXPORTS").

       A reference to a hash is returned in blocking mode which contains the
       contents of the VarBindList.  In non-blocking mode, a true value is
       returned when no error has occurred.  In either mode, the undefined
       value is returned when an error has occurred.  The "error()" method may
       be used to determine the cause of the failure.

       trap() - send a SNMP trap to the remote manager

          $result = $session->trap(
                                 [-delay           => $seconds,]   # non-blocking
                                 [-enterprise      => $oid,]
                                 [-agentaddr       => $ipaddress,]
                                 [-generictrap     => $generic,]
                                 [-specifictrap    => $specific,]
                                 [-timestamp       => $timeticks,]
                                 -varbindlist      => \@oid_value,
                              );

       This method sends a SNMP trap to the remote manager associated with the
       Net::SNMP object.  All arguments are optional and will be given the
       following defaults in the absence of a corresponding named argument:

       o   The default value for the trap -enterprise is "1.3.6.1.4.1", which
           corresponds to "iso.org.dod.internet.private.enterprises".  The
           enterprise value is expected to be an OBJECT IDENTIFER in dotted
           notation.

       o   When the Transport Domain is UDP/IPv4 or TCP/IPv4, the default
           value for the trap -agentaddr is the IP address associated with the
           interface on which the trap will be transmitted.  For other Trans-
           port Domains the -agentaddr is defaulted to "0.0.0.0".  When speci-
           fied, the agent-addr is expected to be an IpAddress in dotted nota-
           tion.

       o   The default value for the -generictrap type is 6 which corresponds
           to "enterpriseSpecific".  The generic-trap types are defined and
           can be exported upon request (see "EXPORTS").

       o   The default value for the -specifictrap type is 0.  No pre-defined
           values are available for specific-trap types.

       o   The default value for the trap -timestamp is the "uptime" of the
           script.  The "uptime" of the script is the number of hundredths of
           seconds that have elapsed since the script began running.  The
           time-stamp is expected to be a TimeTicks number in hundredths of
           seconds.

       o   The default value for the trap -varbindlist is an empty array ref-
           erence.  The variable-bindings are expected to be in an array for-
           mat consisting of groups of an OBJECT IDENTIFIER, an object type,
           and the actual value of the object.  This is identical to the list
           expected by the "set_request()" method.  The OBJECT IDENTIFIERs in
           each trio are to be in dotted notation.  The object type is an
           octet corresponding to the ASN.1 type for the value. Each of the
           supported types have been defined and are exported by default (see
           "EXPORTS").

       A true value is returned when the method is successful. The undefined
       value is returned when a failure has occurred.  The "error()" method
       can be used to determine the cause of the failure. Since there are no
       acknowledgements for Trap-PDUs, there is no way to determine if the
       remote host actually received the trap.

       NOTE: When the object is in non-blocking mode, the trap is not sent
       until the event loop is entered and no callback is ever executed.

       NOTE: This method can only be used when the version of the object is
       set to SNMPv1.

       get_bulk_request() - send a SNMP get-bulk-request to the remote agent

          $result = $session->get_bulk_request(
                                 [-callback        => sub {},]     # non-blocking
                                 [-delay           => $seconds,]   # non-blocking
                                 [-contextengineid => $engine_id,] # v3
                                 [-contextname     => $name,]      # v3
                                 [-nonrepeaters    => $non_reps,]
                                 [-maxrepetitions  => $max_reps,]
                                 -varbindlist      => \@oids,
                              );

       This method performs a SNMP get-bulk-request query to gather data from
       the remote agent on the host associated with the Net::SNMP object.  All
       arguments are optional except -varbindlist and will be given the fol-
       lowing defaults in the absence of a corresponding named argument:

       o   The default value for the get-bulk-request -nonrepeaters is 0.  The
           non-repeaters value specifies the number of variables in the vari-
           able-bindings list for which a single successor is to be returned.

       o   The default value for the get-bulk-request -maxrepetitions is 0.
           The max-repetitions value specifies the number of successors to be
           returned for the remaining variables in the variable-bindings list.

       o   The -varbindlist argument expects an array reference consisting of
           a list of OBJECT IDENTIFIERs in dotted notation.  Each OBJECT IDEN-
           TIFER is placed into a single SNMP GetBulkRequest-PDU in the same
           order that it held in the original list.

       A reference to a hash is returned in blocking mode which contains the
       contents of the VarBindList.  In non-blocking mode, a true value is
       returned when no error has occurred.  In either mode, the undefined
       value is returned when an error has occurred.  The "error()" method may
       be used to determine the cause of the failure.

       NOTE: This method can only be used when the version of the object is
       set to SNMPv2c or SNMPv3.

       inform_request() - send a SNMP inform-request to the remote manager

          $result = $session->inform_request(
                                 [-callback        => sub {},]     # non-blocking
                                 [-delay           => $seconds,]   # non-blocking
                                 [-contextengineid => $engine_id,] # v3
                                 [-contextname     => $name,]      # v3
                                 -varbindlist      => \@oid_value,
                              );

       This method is used to provide management information to the remote
       manager associated with the Net::SNMP object using an inform-request.
       The message is built using a list of values consisting of groups of an
       OBJECT IDENTIFIER, an object type, and the actual value to be identi-
       fied.  This list is passed to the method as an array reference using
       the -varbindlist argument.  The OBJECT IDENTIFIERs in each trio are to
       be in dotted notation.  The object type is an octet corresponding to
       the ASN.1 type of value that is to be identified.  Each of the sup-
       ported ASN.1 types have been defined and are exported by the package by
       default (see "EXPORTS").

       The first two variable-bindings fields in the inform-request are speci-
       fied by SNMPv2 and should be:

       o   sysUpTime.0 - ('1.3.6.1.2.1.1.3.0', TIMETICKS, $timeticks)

       o   snmpTrapOID.0 - ('1.3.6.1.6.3.1.1.4.1.0', OBJECT_IDENTIFIER, $oid)

       A reference to a hash is returned in blocking mode which contains the
       contents of the VarBindList.  In non-blocking mode, a true value is
       returned when no error has occurred.  In either mode, the undefined
       value is returned when an error has occurred.  The "error()" method may
       be used to determine the cause of the failure.

       NOTE: This method can only be used when the version of the object is
       set to SNMPv2c or SNMPv3.

       snmpv2_trap() - send a SNMP snmpV2-trap to the remote manager

          $result = $session->snmpv2_trap(
                                 [-delay           => $seconds,]   # non-blocking
                                 -varbindlist      => \@oid_value,
                              );

       This method sends a snmpV2-trap to the remote manager associated with
       the Net::SNMP object.  The message is built using a list of values con-
       sisting of groups of an OBJECT IDENTIFIER, an object type, and the
       actual value to be identified.  This list is passed to the method as an
       array reference using the -varbindlist argument.  The OBJECT IDENTI-
       FIERs in each trio are to be in dotted notation.  The object type is an
       octet corresponding to the ASN.1 type of value that is to be identi-
       fied.  Each of the supported ASN.1 types have been defined and are
       exported by the package by default (see "EXPORTS").

       The first two variable-bindings fields in the snmpV2-trap are specified
       by SNMPv2 and should be:

       o   sysUpTime.0 - ('1.3.6.1.2.1.1.3.0', TIMETICKS, $timeticks)

       o   snmpTrapOID.0 - ('1.3.6.1.6.3.1.1.4.1.0', OBJECT_IDENTIFIER, $oid)

       A true value is returned when the method is successful. The undefined
       value is returned when a failure has occurred.  The "error()" method
       can be used to determine the cause of the failure. Since there are no
       acknowledgements for SNMPv2-Trap-PDUs, there is no way to determine if
       the remote host actually received the snmpV2-trap.

       NOTE: When the object is in non-blocking mode, the snmpV2-trap is not
       sent until the event loop is entered and no callback is ever executed.

       NOTE: This method can only be used when the version of the object is
       set to SNMPv2c.  SNMPv2-Trap-PDUs are supported by SNMPv3, but require
       the sender of the message to be an authoritative SNMP engine which is
       not currently supported by the Net::SNMP module.

       get_table() - retrieve a table from the remote agent

          $result = $session->get_table(
                                 [-callback        => sub {},]     # non-blocking
                                 [-delay           => $seconds,]   # non-blocking
                                 [-contextengineid => $engine_id,] # v3
                                 [-contextname     => $name,]      # v3
                                 -baseoid          => $oid,
                                 [-maxrepetitions  => $max_reps,]  # v2c/v3
                              );

       This method performs repeated SNMP get-next-request or get-bulk-request
       (when using SNMPv2c or SNMPv3) queries to gather data from the remote
       agent on the host associated with the Net::SNMP object.  The first mes-
       sage sent is built using the OBJECT IDENTIFIER in dotted notation
       passed to the method by the -baseoid argument.   Repeated SNMP requests
       are issued until the OBJECT IDENTIFIER in the response is no longer a
       child of the base OBJECT IDENTIFIER.

       The -maxrepetitions argument can be used to specify the max-repetitions
       value that is passed to the get-bulk-requests when using SNMPv2c or
       SNMPv3.  If this argument is not present, a value is calculated based
       on the maximum message size for the Net::SNMP object.  If the value is
       set to 1 or less, get-next-requests will be used for the queries
       instead of get-bulk-requests.

       A reference to a hash is returned in blocking mode which contains the
       contents of the VarBindList.  In non-blocking mode, a true value is
       returned when no error has occurred.  In either mode, the undefined
       value is returned when an error has occurred.  The "error()" method may
       be used to determine the cause of the failure.

       WARNING: Results from this method can become very large if the base
       OBJECT IDENTIFIER is close to the root of the SNMP MIB tree.

       get_entries() - retrieve table entries from the remote agent

          $result = $session->get_entries(
                                 [-callback        => sub {},]     # non-blocking
                                 [-delay           => $seconds,]   # non-blocking
                                 [-contextengineid => $engine_id,] # v3
                                 [-contextname     => $name,]      # v3
                                 -columns          => \@columns,
                                 [-startindex      => $start,]
                                 [-endindex        => $end,]
                                 [-maxrepetitions  => $max_reps,]  # v2c/v3
                              );

       This method performs repeated SNMP get-next-request or get-bulk-request
       (when using SNMPv2c or SNMPv3) queries to gather data from the remote
       agent on the host associated with the Net::SNMP object.  Each message
       specifically requests data for each OBJECT IDENTIFIER specified in the
       -columns array.  The OBJECT IDENTIFIERs must correspond to column
       entries for a conceptual row in a table.  They may however be columns
       in different tables as long as each table is indexed the same way.  The
       optional -startindex and -endindex arguments may be specified to limit
       the query to specific rows in the table(s).

       The -startindex can be specified as a single decimal value or in dotted
       notation if the index associated with the entry so requires.  If the
       -startindex is specified, it will be include as part of the query
       results.  If no -startindex is specified, the first request message
       will be sent without an index.  To insure that the -startindex is
       included, the last subidentifier in the index is decremented by one.
       If the last subidentifier has a value of zero, the subidentifier is
       removed from the index.

       The optional -endindex argument can be specified as a single decimal
       value or in dotted notation.  If the -endindex is specified, it will be
       included as part of the query results.  If no -endindex is specified,
       repeated SNMP requests are issued until the response no longer returns
       entries matching any of the columns specified in the -columns array.

       The -maxrepetitions argument can be used to specify the max-repetitions
       value that is passed to the get-bulk-requests when using SNMPv2c or
       SNMPv3.  If this argument is not present, a value is calculated based
       on the maximum message size of the object and the number of columns
       specified in the -columns array.  If the value is set to 1 or less,
       get-next-requests will be used for the queries instead of
       get-bulk-requests.

       A reference to a hash is returned in blocking mode which contains the
       contents of the VarBindList.  In non-blocking mode, a true value is
       returned when no error has occurred.  In either mode, the undefined
       value is returned when an error has occurred.  The "error()" method may
       be used to determine the cause of the failure.

       version() - get the SNMP version from the object

          $rfc_version = $session->version;

       This method returns the current value for the SNMP version associated
       with the object.  The returned value is the corresponding version num-
       ber defined by the RFCs for the protocol version field (i.e. SNMPv1 ==
       0, SNMPv2c == 1, and SNMPv3 == 3).  The RFC versions are defined as
       constant by the module and can be exported by request (see "EXPORTS").

       error() - get the current error message from the object

          $error_message = $session->error;

       This method returns a text string explaining the reason for the last
       error.  An empty string is returned if no error has occurred.

       hostname() - get the hostname associated with the object

          $hostname = $session->hostname;

       This method returns the hostname string that is associated with the
       object as it was passed to the "session()" constructor.

       error_status() - get the current SNMP error-status from the object

          $error_status = $session->error_status;

       This method returns the numeric value of the error-status contained in
       the last SNMP message received by the object.

       error_index() - get the current SNMP error-index from the object

          $error_index = $session->error_index;

       This method returns the numeric value of the error-index contained in
       the last SNMP message received by the object.

       var_bind_list() - get the hash reference for the VarBindList values

          $values = $session->var_bind_list;

       This method returns a hash reference created using the ObjectName and
       the ObjectSyntax pairs in the VarBindList of the last SNMP message
       received by the object.  The keys of the hash consist of the OBJECT
       IDENTIFIERs in dotted notation corresponding to each ObjectName in the
       VarBindList.  If any of the OBJECT IDENTIFIERs passed to the request
       method began with a leading dot, all of the OBJECT IDENTIFIER hash keys
       will be prefixed with a leading dot.  If duplicate OBJECT IDENTIFIERs
       are present in the VarBindList they will be padded with spaces to make
       them an uniq hash key.  The value of each hash entry is set equal to
       the value of the corresponding ObjectSyntax.  The undefined value is
       returned if there has been a failure.

       var_bind_names() - get the array of the ObjectNames in the VarBindList

          @names = $session->var_bind_names;

       This method returns an array containing the OBJECT IDENTIFIERs corre-
       sponding to the ObjectNames in the VarBindList in the order that they
       were received in the last SNMP message.  The entries in the array will
       map directly to the keys in the hash reference returned by the methods
       that perform SNMP message exchanges and by the "var_bind_list()" and
       "var_bind_types()" methods.  The array returned for the convenience
       methods "get_table()" and "get_entries()" will be in lexicographical
       order.  An empty array is returned if there has been a failure.

       var_bind_types() - get the hash reference for the VarBindList ASN.1
       types

          $types = $session->var_bind_types;

       This method returns a hash reference created using the ObjectName and
       the ASN.1 type of the ObjectSyntax in the VarBindList of the last SNMP
       message received by the object.  The keys of the hash consist of the
       OBJECT IDENTIFIERs in dotted notation corresponding to each ObjectName
       in the VarBindList.  The value of each hash entry is set equal to the
       ASN.1 type of the corresponding ObjectSyntax.  Constants for the sup-
       ported ASN.1 types have been defined and are exported by the package by
       default (see "EXPORTS").  The undefined value is returned if there has
       been a failure.

       timeout() - set or get the current timeout period for the object

          $seconds = $session->timeout([$seconds]);

       This method returns the current value for the Transport Layer timeout
       for the Net::SNMP object.  This value is the number of seconds that the
       object will wait for a response from the agent on the remote host.  The
       default timeout is 5.0 seconds.

       If a parameter is specified, the timeout for the object is set to the
       provided value if it falls within the range 1.0 to 60.0 seconds.  The
       undefined value is returned upon an error and the "error()" method may
       be used to determine the cause.

       retries() - set or get the current retry count for the object

          $count = $session->retries([$count]);

       This method returns the current value for the number of times to retry
       sending a SNMP message to the remote host.  The default number of
       retries is 1.

       If a parameter is specified, the number of retries for the object is
       set to the provided value if it falls within the range 0 to 20. The
       undefined value is returned upon an error and the "error()" method may
       be used to determine the cause.

       max_msg_size() - set or get the current maxMsgSize for the object

          $octets = $session->max_msg_size([$octets]);

       This method returns the current value for the maximum message size
       (maxMsgSize) for the Net::SNMP object.  This value is the largest mes-
       sage size in octets that can be prepared or processed by the object.
       The default maxMsgSize is 1472 octets for UDP/IPv4, 1452 octets for
       UDP/IPv6, 1460 octets for TCP/IPv4, and 1440 octets for TCP/IPv6.

       If a parameter is specified, the maxMsgSize is set to the provided
       value if it falls within the range 484 to 65535 octets.  The undefined
       value is returned upon an error and the "error()" method may be used to
       determine the cause.

       NOTE: When using SNMPv3, the maxMsgSize is actually contained in the
       SNMP message (as msgMaxSize).  If the value received from a remote
       device is less than the current maxMsgSize, the size is automatically
       adjusted to be the lower value.

       translate() - enable or disable the translation mode for the object

          $mask = $session->translate([
                               $mode |
                               [ # Perl anonymous ARRAY reference
                                  ['-all'            => $mode0,]
                                  ['-octetstring     => $mode1,]
                                  ['-null'           => $mode2,]
                                  ['-timeticks'      => $mode3,]
                                  ['-opaque'         => $mode4,]
                                  ['-nosuchobject'   => $mode5,]
                                  ['-nosuchinstance' => $mode6,]
                                  ['-endofmibview'   => $mode7,]
                                  ['-unsigned'       => $mode8]
                               ]
                            ]);

       When the object decodes the GetResponse-PDU that is returned in
       response to a SNMP message, certain values are translated into a more
       "human readable" form.  By default the following translations occur:

       o   OCTET STRINGs and Opaques containing non-printable ASCII characters
           are converted into a hexadecimal representation prefixed with "0x".
           NOTE: The following ASCII control characters are considered to be
           printable by the module:  NUL(0x00), HT(0x09), LF(0x0A), FF(0x0C),
           and CR(0x0D).

       o   TimeTicks integer values are converted to a time format.

       o   NULL values return the string "NULL" instead of an empty string.

       o   noSuchObject exception values return the string "noSuchObject"
           instead of an empty string.  If translation is not enabled, the
           SNMP error-status field is set to 128 which is equal to the
           exported definition NOSUCHOBJECT (see "EXPORTS").

       o   noSuchInstance exception values return the string "noSuchInstance"
           instead of an empty string.  If translation is not enabled, the
           SNMP error-status field is set to 129 which is equal to the
           exported definition NOSUCHINSTANCE (see "EXPORTS").

       o   endOfMibView exception values return the string "endOfMibView"
           instead of an empty string.  If translation is not enabled, the
           SNMP error-status field is set to 130 which is equal to the
           exported definition ENDOFMIBVIEW (see "EXPORTS").

       o   Counter64, Counter, Gauge, and TimeTick values that have been
           incorrectly encoded as signed negative values are returned as
           unsigned values.

       The "translate()" method can be invoked with two different types of
       arguments.

       If the argument passed is any Perl variable type except an array refer-
       ence, the translation mode for all ASN.1 types is set to either enabled
       or disabled, depending on the value of the passed parameter.  Any value
       that Perl would treat as a true value will set the mode to be enabled
       for all types, while a false value will disable translation for all
       types.

       A reference to an array can be passed to the "translate()" method in
       order to define the translation mode on a per ASN.1 type basis.  The
       array is expected to contain a list of named argument pairs for each
       ASN.1 type that is to be modified.  The arguments in the list are
       applied in the order that they are passed in via the array.  Arguments
       at the end of the list supercede those passed earlier in the list.  The
       argument "-all" can be used to specify that the mode is to apply to all
       ASN.1 types.  Only the arguments for the ASN.1 types that are to be
       modified need to be included in the list.

       The "translate()" method returns a bit mask indicating which ASN.1
       types are to be translated.  Definitions of the bit to ASN.1 type map-
       pings can be exported using the :translate tag (see "EXPORTS").  The
       undefined value is returned upon an error and the "error()" method may
       be used to determine the cause.

       debug() - set or get the debug mode for the module

          $mask = $session->debug([$mask]);

       This method is used to enable or disable debugging for the Net::SNMP
       module.  Debugging can be enabled on a per component level as defined
       by a bit mask passed to the "debug()" method.  The bit mask is broken
       up as follows:

       o   0x02 - Message or PDU encoding and decoding

       o   0x04 - Transport Layer

       o   0x08 - Dispatcher

       o   0x10 - Message Processing

       o   0x20 - Security

       Symbols representing these bit mask values are defined by the module
       and can be exported using the :debug tag (see "EXPORTS").  If a non-
       numeric value is passed to the "debug()" method, it is evaluated in
       boolean context.  Debugging for all of the components is then enabled
       or disabled based on the resulting truth value.

       The current debugging mask is returned by the method.  Debugging can
       also be enabled using the stand alone function "snmp_debug()". This
       function can be exported by request (see "EXPORTS").

FUNCTIONS
       oid_base_match() - determine if an OID has a specified OID base

          $value = oid_base_match($base_oid, $oid);

       This function takes two OBJECT IDENTIFIERs in dotted notation and
       returns a true value (i.e. 0x1) if the second OBJECT IDENTIFIER is
       equal to or is a child of the first OBJECT IDENTIFIER in the SNMP Man-
       agement Information Base (MIB).  This function can be used in conjunc-
       tion with the "get-next-request()" or "get-bulk-request()" methods to
       determine when a OBJECT IDENTIFIER in the GetResponse-PDU is no longer
       in the desired MIB tree branch.

       oid_lex_sort() - sort a list of OBJECT IDENTIFIERs lexicographically

          @sorted_oids = oid_lex_sort(@oids);

       This function takes a list of OBJECT IDENTIFIERs in dotted notation and
       returns the listed sorted in lexicographical order.

       snmp_type_ntop() - convert an ASN.1 type to presentation format

          $text = snmp_type_ntop($type);

       This function takes an ASN.1 type octet and returns a text string suit-
       able for presentation.  Some ASN.1 type definitions map to the same
       octet value when encoded.  This method cannot distinquish between these
       multiple mappings and the most basic type name will be returned.

       ticks_to_time() - convert TimeTicks to formatted time

          $time = ticks_to_time($timeticks);

       This function takes an ASN.1 TimeTicks value and returns a string rep-
       resenting the time defined by the value.  The TimeTicks value is
       expected to be a non-negative integer value representing the time in
       hundredths of a second since some epoch.  The returned string will dis-
       play the time in days, hours, and seconds format according to the value
       of the TimeTicks argument.

EXPORTS
       The Net::SNMP module uses the Exporter module to export useful con-
       stants and subroutines.  These exportable symbols are defined below and
       follow the rules and conventions of the Exporter module (see Exporter).

       Default
           &snmp_dispatcher, INTEGER, INTEGER32, OCTET_STRING, OBJECT_IDENTI-
           FIER, IPADDRESS, COUNTER, COUNTER32, GAUGE, GAUGE32, UNSIGNED32,
           TIMETICKS, OPAQUE, COUNTER64, NOSUCHOBJECT, NOSUCHINSTANCE, END-
           OFMIBVIEW

       Exportable
           &snmp_debug, &snmp_dispatcher, &snmp_type_ntop, &oid_base_match,
           &oid_lex_sort, &ticks_to_time, INTEGER, INTEGER32, OCTET_STRING,
           NULL, OBJECT_IDENTIFIER, SEQUENCE, IPADDRESS, COUNTER, COUNTER32,
           GAUGE, GAUGE32, UNSIGNED32, TIMETICKS, OPAQUE, COUNTER64, NOSUCHOB-
           JECT, NOSUCHINSTANCE, ENDOFMIBVIEW, GET_REQUEST, GET_NEXT_REQUEST,
           GET_RESPONSE, SET_REQUEST, TRAP, GET_BULK_REQUEST, INFORM_REQUEST,
           SNMPV2_TRAP, REPORT, DEBUG_ALL, DEBUG_NONE, DEBUG_MESSAGE,
           DEBUG_TRANSPORT, DEBUG_DISPATCHER,DEBUG_PROCESSING, DEBUG_SECURITY,
           COLD_START, WARM_START, LINK_DOWN, LINK_UP,AUTHENTICATION_FAILURE,
           EGP_NEIGHBOR_LOSS, ENTERPRISE_SPECIFIC, SNMP_VERSION_1,SNMP_VER-
           SION_2C, SNMP_VERSION_3, SNMP_PORT, SNMP_TRAP_PORT, TRANS-
           LATE_NONE,TRANSLATE_OCTET_STRING, TRANSLATE_NULL, TRANSLATE_TIMET-
           ICKS, TRANSLATE_OPAQUE,TRANSLATE_NOSUCHOBJECT, TRANSLATE_NOSUCHIN-
           STANCE, TRANSLATE_ENDOFMIBVIEW, TRANSLATE_UNSIGNED, TRANSLATE_ALL

       Tags
           :asn1
               INTEGER, INTEGER32, OCTET_STRING, NULL, OBJECT_IDENTIFIER,
               SEQUENCE, IPADDRESS, COUNTER, COUNTER32, GAUGE, GAUGE32,
               UNSIGNED32, TIMETICKS, OPAQUE, COUNTER64, NOSUCHOBJECT,
               NOSUCHINSTANCE, ENDOFMIBVIEW, GET_REQUEST, GET_NEXT_REQUEST,
               GET_RESPONSE, SET_REQUEST, TRAP, GET_BULK_REQUEST,
               INFORM_REQUEST, SNMPV2_TRAP, REPORT

           :debug
               &snmp_debug, DEBUG_ALL, DEBUG_NONE, DEBUG_MESSAGE, DEBUG_TRANS-
               PORT, DEBUG_DISPATCHER, DEBUG_PROCESSING, DEBUG_SECURITY

           :generictrap
               COLD_START, WARM_START, LINK_DOWN, LINK_UP, AUTHENTICA-
               TION_FAILURE, EGP_NEIGHBOR_LOSS, ENTERPRISE_SPECIFIC

           :snmp
               &snmp_debug, &snmp_dispatcher, &snmp_type_ntop,
               &oid_base_match, &oid_lex_sort, &ticks_to_time, SNMP_VERSION_1,
               SNMP_VERSION_2C, SNMP_VERSION_3, SNMP_PORT, SNMP_TRAP_PORT

           :translate
               TRANSLATE_NONE, TRANSLATE_OCTET_STRING, TRANSLATE_NULL, TRANS-
               LATE_TIMETICKS, TRANSLATE_OPAQUE, TRANSLATE_NOSUCHOBJECT,
               TRANSLATE_NOSUCHINSTANCE, TRANSLATE_ENDOFMIBVIEW, TRANS-
               LATE_UNSIGNED, TRANSLATE_ALL

           :ALL
               All of the above exportable items.

EXAMPLES
       1. Blocking SNMPv1 get-request for sysUpTime

       This example gets the sysUpTime from a remote host.

          #! /usr/local/bin/perl

          use strict;

          use Net::SNMP;

          my ($session, $error) = Net::SNMP->session(
             -hostname  => shift || 'localhost',
             -community => shift || 'public',
             -port      => shift || 161
          );

          if (!defined($session)) {
             printf("ERROR: %s.\n", $error);
             exit 1;
          }

          my $sysUpTime = '1.3.6.1.2.1.1.3.0';

          my $result = $session->get_request(
             -varbindlist => [$sysUpTime]
          );

          if (!defined($result)) {
             printf("ERROR: %s.\n", $session->error);
             $session->close;
             exit 1;
          }

          printf("sysUpTime for host '%s' is %s\n",
             $session->hostname, $result->{$sysUpTime}
          );

          $session->close;

          exit 0;

       2. Blocking SNMPv3 set-request of sysContact

       This example sets the sysContact information on the remote host to
       "Help Desk x911".  The named arguments passed to the "session()" con-
       structor are for the demonstration of syntax only.  These parameters
       will need to be set according to the SNMPv3 parameters of the remote
       host used by the script.

          #! /usr/local/bin/perl

          use strict;

          use Net::SNMP;

          my ($session, $error) = Net::SNMP->session(
             -hostname     => 'myv3host.company.com',
             -version      => 'snmpv3',
             -username     => 'myv3Username',
             -authkey      => '0x05c7fbde31916f64da4d5b77156bdfa7',
             -authprotocol => 'md5',
             -privkey      => '0x93725fd3a02a48ce02df4e065a1c1746'
          );

          if (!defined($session)) {
             printf("ERROR: %s.\n", $error);
             exit 1;
          }

          my $sysContact = '1.3.6.1.2.1.1.4.0';

          my $result = $session->set_request(
             -varbindlist => [$sysContact, OCTET_STRING, 'Help Desk x911']
          );

          if (!defined($result)) {
             printf("ERROR: %s.\n", $session->error);
             $session->close;
             exit 1;
          }

          printf("sysContact for host '%s' set to '%s'\n",
             $session->hostname, $result->{$sysContact}
          );

          $session->close;

          exit 0;

       3. Non-blocking SNMPv2c get-bulk-request for ifTable

       This example gets the contents of the ifTable by sending get-bulk-
       requests until the responses are no longer part of the ifTable.  The
       ifTable can also be retrieved using the "get_table()" method.

          #! /usr/local/bin/perl

          use strict;

          use Net::SNMP qw(:snmp);

          my ($session, $error) = Net::SNMP->session(
             -version     => 'snmpv2c',
             -nonblocking => 1,
             -hostname    => shift || 'localhost',
             -community   => shift || 'public',
             -port        => shift || 161
          );

          if (!defined($session)) {
             printf("ERROR: %s.\n", $error);
             exit 1;
          }

          my $ifTable = '1.3.6.1.2.1.2.2';

          my $result = $session->get_bulk_request(
             -callback       => [\&table_cb, {}],
             -maxrepetitions => 10,
             -varbindlist    => [$ifTable]
          );

          if (!defined($result)) {
             printf("ERROR: %s.\n", $session->error);
             $session->close;
             exit 1;
          }

          snmp_dispatcher();

          $session->close;

          exit 0;

          sub table_cb
          {
             my ($session, $table) = @_;

             if (!defined($session->var_bind_list)) {

                printf("ERROR: %s\n", $session->error);

             } else {

                # Loop through each of the OIDs in the response and assign
                # the key/value pairs to the anonymous hash that is passed
                # to the callback.  Make sure that we are still in the table
                # before assigning the key/values.

                my $next;

                foreach my $oid (oid_lex_sort(keys(%{$session->var_bind_list}))) {
                   if (!oid_base_match($ifTable, $oid)) {
                      $next = undef;
                      last;
                   }
                   $next = $oid;
                   $table->{$oid} = $session->var_bind_list->{$oid};
                }

                # If $next is defined we need to send another request
                # to get more of the table.

                if (defined($next)) {

                   $result = $session->get_bulk_request(
                      -callback       => [\&table_cb, $table],
                      -maxrepetitions => 10,
                      -varbindlist    => [$next]
                   );

                   if (!defined($result)) {
                      printf("ERROR: %s\n", $session->error);
                   }

                } else {

                   # We are no longer in the table, so print the results.

                   foreach my $oid (oid_lex_sort(keys(%{$table}))) {
                      printf("%s => %s\n", $oid, $table->{$oid});
                   }

                }
             }
          }

       4. Non-blocking SNMPv1 get-request for sysUpTime on multiple hosts

       This example polls several hosts for their sysUpTime using non-blocking
       objects and reports a warning if this value is less than the value from
       the last poll.

          #! /usr/local/bin/perl

          use strict;

          use Net::SNMP qw(snmp_dispatcher ticks_to_time);

          # List of hosts to poll

          my @HOSTS = qw(1.1.1.1 1.1.1.2 localhost);

          # Poll interval (in seconds).  This value should be greater
          # than the number of retries plus one, times the timeout value.

          my $INTERVAL  = 60;

          # Maximum number of polls, including the initial poll.

          my $MAX_POLLS = 10;

          my $sysUpTime = '1.3.6.1.2.1.1.3.0';

          # Create a session for each host and queue the first get-request.

          foreach my $host (@HOSTS) {

             my ($session, $error) = Net::SNMP->session(
                -hostname    => $host,
                -nonblocking => 0x1,   # Create non-blocking objects
                -translate   => [
                   -timeticks => 0x0   # Turn off so sysUpTime is numeric
                ]
             );
             if (!defined($session)) {
                printf("ERROR: %s.\n", $error);
                exit 1;
             }

             # Queue the get-request, passing references to variables that
             # will be used to store the last sysUpTime and the number of
             # polls that this session has performed.

             my ($last_uptime, $num_polls) = (0, 0);

             $session->get_request(
                 -varbindlist => [$sysUpTime],
                 -callback    => [
                    \&validate_sysUpTime_cb, \$last_uptime, \$num_polls
                 ]
             );

          }

          # Define a reference point for all of the polls
          my $EPOC = time();

          # Enter the event loop
          snmp_dispatcher();

          exit 0;

          sub validate_sysUpTime_cb
          {
             my ($session, $last_uptime, $num_polls) = @_;

             if (!defined($session->var_bind_list)) {

                printf("%-15s  ERROR: %s\n", $session->hostname, $session->error);

             } else {

                # Validate the sysUpTime

                my $uptime = $session->var_bind_list->{$sysUpTime};

                if ($uptime < ${$last_uptime}) {
                   printf("%-15s  WARNING: %s is less than %s\n",
                      $session->hostname,
                      ticks_to_time($uptime),
                      ticks_to_time(${$last_uptime})
                   );
                } else {
                   printf("%-15s  Ok (%s)\n",
                      $session->hostname, ticks_to_time($uptime)
                   );
                }

                # Store the new sysUpTime
                ${$last_uptime} = $uptime;

             }

             # Queue the next message if we have not reached $MAX_POLLS.
             # Since we do not provide a -callback argument, the same
             # callback and it's original arguments will be used.

             if (++${$num_polls} < $MAX_POLLS) {
                my $delay = (($INTERVAL * ${$num_polls}) + $EPOC) - time();
                $session->get_request(
                   -delay       => ($delay >= 0) ? $delay : 0,
                   -varbindlist => [$sysUpTime]
                );
             }

             $session->error_status;
          }

REQUIREMENTS
       o   The Net::SNMP module uses syntax that is not supported in versions
           of Perl earlier than v5.6.0.

       o   The non-core modules Crypt::DES, Digest::MD5, Digest::SHA1, and
           Digest::HMAC are required to support SNMPv3.

       o   In order to support the AES Cipher Algorithm as a SNMPv3 privacy
           protocol, the non-core module Crypt::Rijndael is needed.

       o   To use UDP/IPv6 or TCP/IPv6 as a Transport Domain, the non-core
           module Socket6 is needed.

AUTHOR
       David M. Town <dtownATcpan.org>

ACKNOWLEDGMENTS
       The original concept for this module was based on SNMP_Session.pm writ-
       ten by Simon Leinen <simonATswitch.ch>.

       The Abstract Syntax Notation One (ASN.1) encode and decode methods were
       originally derived by example from the CMU SNMP package whose copyright
       follows: Copyright (c) 1988, 1989, 1991, 1992 by Carnegie Mellon Uni-
       versity.  All rights reserved.

COPYRIGHT
       Copyright (c) 1998-2005 David M. Town.  All rights reserved.  This pro-
       gram is free software; you may redistribute it and/or modify it under
       the same terms as Perl itself.



perl v5.8.7                       2005-10-20                    Net::SNMP(3pm)