Net::SNMP(3pm)

📦
version 6.0.1 · 13 versions
, in opensuse-leap 16.0

okay so bestie, welcome to the manual page for Net::SNMP(3pm) — it's giving object-oriented SNMP realness and honestly it ate. 💅

✨ 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 module to retrieve or update information on a remote host using the SNMP protocol. The module supports SNMP version-1, SNMP version-2c (Community-Based SNMPv2), and SNMP version-3. The Net::SNMP module assumes that the user has a basic understanding of the Simple Network Management Protocol and related network management concepts. 🦋

💖 DESCRIPTION 💖

The Net::SNMP module abstracts the intricate details of the Simple Network Management Protocol by providing a high level programming interface to the protocol. Each Net::SNMP object provides a one-to-one mapping 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 successfully 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" behavior. 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 reference 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 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. 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 argument expects a reference to a subroutine or to an array whose first element must be a reference to a subroutine.
  • The subroutine 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 reference, the subroutine is evaluated passing a reference to the original Net::SNMP object as the only parameter. If the -callback 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 methods associated with the object once it is specified.
  • The delay value must be set back to 0 seconds to disable the delay parameter.

🔐 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 contextName unambiguously identifies a context within an administrative domain. In a SNMPv3 message, the contextEngineID and contextName 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 representing 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 contextName stays with the object until it is changed.
  • The contextName 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

okay so by default Net::SNMP is a UDP/IPv4 girlie 💅 — that's the Transport Domain it uses to swap SNMP messages between your local device and the remote one. But she's flexible! She also supports UDP/IPv6, TCP/IPv4, and TCP/IPv6 as alternative Transport Domains. Just pass the -domain argument one of these strings to switch it up:

  • 'udp6', 'udp/ipv6'
  • 'tcp', 'tcp4', 'tcp/ipv4'
  • 'tcp6', 'tcp/ipv6'

And yes, -domain also accepts 'udp', 'udp4', or 'udp/ipv4' — those are literally just the default UDP/IPv4 vibe, in case you like being explicit about it 🎀

You point at the destination SNMP device with the -hostname argument. It's optional, and if you ghost it, it defaults to "localhost" (yes, she'll just talk to herself, no biggie). The destination port number can either ride along inside the transport address or come in via -port. Either a numeric port number or a textual service name works — and you can optionally stick a numeric port number in parentheses after the service name, which gets used as a fallback if the service name can't be resolved. If you don't specify a destination port at all, the well-known SNMP port number 161 is what she uses. Periodt. 🫶

So by default, your source transport address and port number get assigned dynamically by the local device running Net::SNMP. If you wanna override that whole situation, hit up -localaddr and -localport — they take the same values as -hostname and -port respectively. Heads up though: the resolved address has to correspond to a valid address of an interface on the local device. No making up addresses, bestie, that's not the vibe. ✨

When you're on an IPv4 Transport Domain, the transport address can be either an IP network hostname or an IPv4 address in standard dotted notation. Port info can optionally be appended to the hostname or address, delimited by a colon. The accepted IPv4 transport address formats are:

  • "address"
  • "address:port"
  • "hostname"
  • "hostname:port"

When you're on an IPv6 Transport Domain, the transport address can be an IP hostname (which gets looked up as a DNS quad-A record 🌈) or an IPv6 address in presentation format. Port info can optionally be included following a colon after the hostname or address — but when you're tacking it onto an IPv6 address, the address must be enclosed in square brackets. Also! 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"
  • "hostname"
  • "hostname:port"

🔐 Security Model Arguments

The -version argument is the main character here — it controls which other arguments the session() constructor expects or requires. Net::SNMP supports SNMPv1, SNMPv2c, and SNMPv3, and she defaults to SNMPv1 if you don't pass -version at all. The argument expects either a digit — '1', '2', or '3' — or a string naming the version: 'snmpv1', 'snmpv2c', or 'snmpv3'. Easy ✨

The Security Model your Net::SNMP object uses is based on the SNMP version associated with that object. SNMPv1 or SNMPv2c? You get a Community-based Security Model. SNMPv3? You get the User-based Security Model (USM). That's just how she rolls 💅

🎀 Community-based Security Model Argument

If the Security Model is Community-based, your one and only argument is -community. It expects a string that gets used as the SNMP community name. If you don't pass it, the community name defaults to 'public' — yes, the classic 🙈

👑 User-based Security Model Arguments

The User-based Security Model (USM) used by SNMPv3 requires a securityName, and you supply that with the -username argument. Fr fr: creating a Net::SNMP object with the version set to SNMPv3 will fail if -username isn't there. The -username argument expects a string 1 to 32 octets in length. Respect the range 💀

Different levels of security are allowed by USM, covering authentication and privacy concerns. A SNMPv3 Net::SNMP object derives the securityLevel based on which of the following arguments you actually specify:

  • By default, a securityLevel of 'noAuthNoPriv' is assumed.
  • If you pass the -authkey or -authpassword arguments, the securityLevel becomes 'authNoPriv'.
  • The -authpassword argument expects a string that's at least 1 octet in length.
  • Optionally, -authkey can be used so you don't have to hardcode a plain text password in your script (security queen behavior 🔥). 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 that hexadecimal string (see snmpkey).

Two different hash algorithms are defined by SNMPv3 for the Security Model to use for authentication:

  • HMAC-MD5-96 "MD5" (RFC 1321)
  • HMAC-SHA-96 "SHA-1" (NIST FIPS PUB 180-1)

The default algorithm the module uses is HMAC-MD5-96. Wanna change it? Use the -authprotocol argument — it expects either the string 'md5' or 'sha' to modify the hash algorithm. Slay 🌸

Now, by specifying -privkey or -privpassword, the securityLevel associated with the object becomes 'authPriv'. But listen 👀 — according to SNMPv3, privacy requires the use of authentication. So if either of these two arguments are present and the -authkey or -authpassword arguments are missing, the creation of the object fails. No privacy without auth, that's the rule. The -privkey and -privpassword arguments expect the same input as -authkey and -authpassword respectively.

The USM described in RFC 3414 defines a single encryption protocol for privacy: CBC-DES "DES" (NIST FIPS PUB 46-1). That's what's used by default, or if you pass the string 'des' to the -privprotocol argument. But she does more! The module also supports RFC 3826, which describes the use of CFB128-AES-128 "AES" (NIST FIPS PUB 197) in the USM — pick it by passing 'aes' or 'aes128' to -privprotocol. And by working with the Extended Security Options Consortium (http://www.snmp.com/protocol/eso.shtml), the module also supports CBC-3DES-EDE "Triple-DES" (NIST FIPS 46-3) in the User-based Security Model, defined in the draft at http://www.snmp.com/eso/draft-reeder-snmpv3-usm-3desede-00.txt. Select Triple-DES with the -privprotocol argument using the string '3des' or '3desede'. Iconic encryption lineup tbh 🔐✨

🚪 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 it's closed, that Net::SNMP object can no longer be used to send or receive SNMP messages. She's done, she's logging off, do not disturb 💅

🌀 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. It's also exported by default as the stand alone function snmp_dispatcher() (peep the "EXPORTS" section, bestie). Main character energy, truly 🌟

📥 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 gets built using the list of OBJECT IDENTIFIERs in dotted notation that you pass to the method as an array reference via the -varbindlist argument. Each OBJECT IDENTIFIER is placed into a single SNMP GetRequest-PDU in the same order that it held in your original list. Order matters, she's not shuffling anything 🎀

So what comes back?

  • In blocking mode, you get a reference to a hash that contains the contents of the VarBindList.
  • In non-blocking mode, you get a true value when no error has occurred.
  • In either mode, the undefined value is returned when an error has occurred — and you can use the error() method to figure out what went wrong. 😭

➡️ 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 notation passed to the method as an array reference using the -varbindlist argument. Each OBJECT IDENTIFER is placed into a single SNMP GetNextRequest-PDU in the same order that it held in the original list. Same deal as her sister method — very consistent queen ✨

And the returns?

  • In blocking mode, a reference to a hash comes back containing 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, and the error() method may be used to determine the cause of the failure. 🫶

okay so these next ones are the action methods — the ones that actually change stuff or shout at a manager. buckle up bestie, they're all icons 💅

🌸 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 one is literally how you modify data on the remote agent that's associated with the Net::SNMP object, using a SNMP set-request. The message gets built from a list of values made up of little groups: an OBJECT IDENTIFIER, an object type, and the actual value to be set. You pass that list in as an array reference with the -varbindlist argument. 🎀

The OBJECT IDENTIFIERs inside each trio have to be in dotted notation. The object type is an octet that corresponds to the ASN.1 type of the value you're setting. Every one of the supported ASN.1 types has been defined and is exported by the package by default (go peek at "EXPORTS", iykyk).

So what comes back? In blocking mode you get a reference to a hash that contains the contents of the VarBindList. In non-blocking mode you get a true value when no error has happened. Either way, if something went wrong you get the undefined value back — and the error() method is right there to tell you 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. Every single argument here is optional, and when you don't pass the matching named argument they all get these defaults:

  • 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.
  • 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 Transport Domains the -agentaddr is defaulted to "0.0.0.0". When specified, the agent-addr is expected to be an IpAddress in dotted notation.
  • 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").
  • The default value for the -specifictrap type is 0. No pre-defined values are available for specific-trap types.
  • 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.
  • The default value for the trap -varbindlist is an empty array reference. The variable-bindings are expected to be in an array format 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 has been defined and is exported by default (see "EXPORTS").

You get a true value back when the method is successful. You get the undefined value back when a failure has occurred, and error() can tell you the cause. But here's the thing — since there are no acknowledgements for Trap-PDUs, there is no way to determine if the remote host actually received the trap. it's giving "sent into the void" energy 💀

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. like, ever. 🙈
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 — think of it as the bulk-buy version of a get, and honestly, obsessed. All arguments are optional except -varbindlist, and they get these defaults when the corresponding named argument isn't there:

  • The default value for the get-bulk-request -nonrepeaters is 0. The non-repeaters value specifies the number of variables in the variable-bindings list for which a single successor is to be returned.
  • 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.
  • The -varbindlist argument expects an array reference consisting of a list of OBJECT IDENTIFIERs in dotted notation. Each OBJECT IDENTIFER is placed into a single SNMP GetBulkRequest-PDU in the same order that it held in the original list.

Blocking mode hands you back a reference to a hash containing the contents of the VarBindList. Non-blocking mode gives you a true value when no error has occurred. In either mode, the undefined value shows up when an error has occurred, and error() tells you why. 🫶

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 how you provide management information to the remote manager associated with the Net::SNMP object, using an inform-request. The message gets built from a list of values consisting of groups of an OBJECT IDENTIFIER, an object type, and the actual value to be identified. That list goes in as an array reference using the -varbindlist argument. The OBJECT IDENTIFIERs in each trio are in dotted notation, and the object type is an octet corresponding to the ASN.1 type of value that is to be identified. Each of the supported ASN.1 types has been defined and is exported by the package by default (see "EXPORTS"). ✨

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

  • sysUpTime.0 - ('1.3.6.1.2.1.1.3.0', TIMETICKS, $timeticks)
  • 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 from a list of values consisting of groups of an OBJECT IDENTIFIER, an object type, and the actual value to be identified, and that list comes in 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 supported ASN.1 types has been defined and is 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:

  • sysUpTime.0 - ('1.3.6.1.2.1.1.3.0', TIMETICKS, $timeticks)
  • 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, and error() can tell you the cause. Since there are no acknowledgements for SNMPv2-Trap-PDUs, there's no way to determine if the remote host actually received the snmpV2-trap — again, screaming into the group chat and hoping someone reads it 😭

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. so close yet so far bestie 💀

🧚 get_table() — retrieve a table from the remote agent 🧚

okay this one's a whole table situation, so here's the shape of it first:

$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
                    );

okay so this method just keeps hammering the remote agent with repeated SNMP get-next-request or get-bulk-request queries (get-bulk only when you're on SNMPv2c or SNMPv3, bestie — v1 could never 💅) to scoop up data from the host tied to your Net::SNMP object. The very first message it sends is built from the OBJECT IDENTIFIER in dotted notation you hand it through the -baseoid argument. Then it just keeps firing off SNMP requests until the OBJECT IDENTIFIER that comes back is no longer a child of the base OBJECT IDENTIFIER. Like, it walks away and it does not come back. 🚶‍♀️

The -maxrepetitions argument is how you tell it the max-repetitions value that gets passed along to the get-bulk-requests when you're on SNMPv2c or SNMPv3. Leave that argument out and it'll calculate a value for you based on the maximum message size of the Net::SNMP object. But if the value is set to 1 or less, it switches to get-next-requests instead of get-bulk-requests. fr fr, that's the vibe check. ✨

In blocking mode you get back a reference to a hash stuffed with the contents of the VarBindList. In non-blocking mode, a true value comes back when nothing went wrong. Either mode, you get the undefined value when an error happened, and the error() method is your bestie for figuring out the cause.

⚠️ WARNING: results from this method can become very large if the base OBJECT IDENTIFIER is close to the root of the SNMP MIB tree. Like, embarrassingly large. Do not come crying to me. 😭

🎀 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 one does the same repeated SNMP get-next-request or get-bulk-request thing (again, get-bulk only for SNMPv2c or SNMPv3) to gather data from the remote agent on the host connected to your Net::SNMP object. The difference? Every message is specifically asking for data for each OBJECT IDENTIFIER you listed in the -columns array. Those OBJECT IDENTIFIERs have to correspond to column entries for a conceptual row in a table — but lowkey they can be columns in different tables, as long as every table is indexed the same way. Slay, flexible. 💅

You can optionally drop -startindex and -endindex in there to limit the query to specific rows in the table(s).

-startindex can be a single decimal value or dotted notation if the index for that entry needs it. If you do specify -startindex, it gets included as part of the query results 🫶. If you don't specify one, the first request message goes out with no index. And here's the little trick to make sure -startindex is included: the last sub-identifier in the index gets decremented by one. If that last sub-identifier is zero, it just gets removed from the index entirely. Sneaky but iconic.

The optional -endindex argument can also be a single decimal value or dotted notation. If you specify -endindex, it gets included as part of the query results too. If you don't, it just keeps issuing repeated SNMP requests until the response stops returning entries that match any of the columns you listed in -columns.

-maxrepetitions does the max-repetitions thing again — the value passed to the get-bulk-requests on SNMPv2c or SNMPv3. Not present? It calculates a value based on the maximum message size of the object and the number of columns in your -columns array. Set it to 1 or less and it's get-next-requests instead of get-bulk-requests. Same deal as before. 🔁

Blocking mode → hash reference with the contents of the VarBindList. Non-blocking mode → true value when no error. Either mode → undefined value on error, and error() tells you why. You know the drill by now, bestie. 💖

🦋 version() — get the SNMP version from the object

$rfc_version = $session->version();

Returns the current SNMP version value for the object. And it's the version number the RFCs define for the protocol version field — so SNMPv1 == 0, SNMPv2c == 1, and SNMPv3 == 3. Yes, they skipped 2, no I will not be explaining, that's just how it is. 😭 These RFC versions are defined as constants by the module and you can export them by request (peep "EXPORTS").

🌸 error() — get the current error message from the object

$error_message = $session->error();

Returns a text string explaining why the last error happened. If nothing went wrong, you get an empty string. Peace and quiet. ✨

🧚 hostname() — get the hostname associated with the object

$hostname = $session->hostname();

Returns the parsed hostname string associated with the object. Any port info and formatting that you're allowed to include in the matching session() constructor argument? Stripped. Gone. Not part of the returned string. Clean girl aesthetic only. 🎀

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

$error_status = $session->error_status();

Returns the numeric value of the error-status sitting inside the last SNMP message the object received.

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

$error_index = $session->error_index();

Returns the numeric value of the error-index from that same last SNMP message. The dynamic duo of "something went wrong, here's where." 🔥

🌈 var_bind_list() — get the hash reference for the VarBindList values

$values = $session->var_bind_list();

Returns a hash reference built from the ObjectName and ObjectSyntax pairs in the VarBindList of the last SNMP message the object received. The hash keys are the OBJECT IDENTIFIERs in dotted notation, one for each ObjectName in the VarBindList. And if any of the OBJECT IDENTIFIERs you passed to the request method started with a leading dot, then all the OBJECT IDENTIFIER hash keys get prefixed with a leading dot. Consistency, we love her. 💅

If there are duplicate OBJECT IDENTIFIERs in the VarBindList, they get padded with spaces to make them a unique hash key — that's just how it has to be, don't @ me. Each hash entry's value is set equal to the value of the corresponding ObjectSyntax. And if there's been a failure? Undefined value. 💀

🍓 var_bind_names() — get the array of the ObjectNames in the VarBindList

@names = $session->var_bind_names();

Returns an array of the OBJECT IDENTIFIERs corresponding to the ObjectNames in the VarBindList, in the order they were received in the last SNMP message. These entries 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. 🫶

For the convenience methods get_table() and get_entries(), the array comes back in lexicographical order. If there's been a failure, you get an empty array. Sad but true. 😭

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

$types = $session->var_bind_types();

Returns a hash reference built from the ObjectName and the ASN.1 type of the ObjectSyntax in the VarBindList of the last SNMP message received by the object. Keys = OBJECT IDENTIFIERs in dotted notation, one per ObjectName in the VarBindList. Each entry's value is set equal to the ASN.1 type of the corresponding ObjectSyntax.

Constants for all the supported ASN.1 types are defined and exported by the package by default (go look at "EXPORTS"), so you don't even have to ask. 👑 And yeah — undefined value if there's been a failure.

🦋 timeout() — set or get the current timeout period for the object

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

Returns the current Transport Layer timeout value for the Net::SNMP object — that's the number of seconds the object will sit there waiting for a response from the agent on the remote host. Default timeout is 5.0 seconds. Patience is a virtue but only to a point. ⏳

If you pass a parameter, the object's timeout gets set to your value as long as it falls within the range 1.0 to 60.0 seconds. Outside that range? Undefined value comes back and error() will tell you what went wrong. 🙈

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

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

Returns the current number of times to retry sending an SNMP message to the remote host. Default number of retries is 1.

Pass a parameter and the retry count gets set to it, as long as it's within the range 0 to 20. Out of range → undefined value, and error() has the tea on why. 💅

🔥 max_msg_size() — set or get the current maxMsgSize for the object

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

Returns the current maximum message size (maxMsgSize) for the Net::SNMP object — the largest message size in octets that the object can prepare or process. Defaults, and these are very specific so pay attention bestie:

  • 1472 octets for UDP/IPv4
  • 1452 octets for UDP/IPv6
  • 1460 octets for TCP/IPv4
  • 1440 octets for TCP/IPv6

If you pass a parameter, maxMsgSize is set to your value as long as it's within the range 484 to 65535 octets. Undefined value on error, error() explains. 🫶

NOTE: with SNMPv3, the maxMsgSize is actually inside the SNMP message (as msgMaxSize). So if the value received from a remote device is less than the current maxMsgSize, the size automatically adjusts down to the lower value. It's giving "I'll meet you where you're at." ✨

💜 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 comes back in response to a SNMP message, certain values get translated into a more "human readable" form. Because raw ASN.1 is giving unreadable, and we don't deserve that. 😭 By default the following translations occur:

So, picking up the translate() glow-up checklist:

  • OCTET STRINGs and Opaques that contain any octet not part of the character set defined as a DisplayString in RFC 2679 get converted into a hexadecimal representation prefixed with 0x. The control codes NUL(0x00), BEL(0x07), BS(0x08), HT(0x09), LF(0x0A), VT(0x0b), FF(0x0C), and CR(0x0D) are part of the character set and will not trigger translation.
  • The sequence 'CR x' for any x other than LF or NUL is illegal and will trigger translation.
  • TimeTicks integer values are converted to a time format.
  • NULL values return the string "NULL" instead of an empty string.
  • noSuchObject exception values return the string "noSuchObject" instead of an empty string.
  • noSuchInstance exception values return the string "noSuchInstance" instead of an empty string.
  • endOfMibView exception values return the string "endOfMibView" instead of an empty string.
  • Counter64, Counter, Gauge, and TimeTick values that have been incorrectly encoded as signed negative values are returned as unsigned values.
🚨 Little caution moment: that 'CR x' thing is genuinely illegal unless x is LF or NUL, and it will trigger translation. No cap.

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

If the argument passed is any Perl variable type except an array reference, 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 mappings 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:

  • 0x02 — Message or PDU encoding and decoding
  • 0x04 — Transport Layer
  • 0x08 — Dispatcher
  • 0x10 — Message Processing
  • 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").

🛠️ SUBROUTINES 🛠️

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 Management Information Base (MIB). This function can be used in conjunction with the "get-next-request()" or "get-bulk-request()" methods to determine when an OBJECT IDENTIFIER in the GetResponse-PDU is no longer in the desired MIB tree branch.

oid_lex_cmp() - compare two OBJECT IDENTIFIERs lexicographically 🆚

$cmp = oid_lex_cmp($oid1, $oid2);

This function takes two OBJECT IDENTIFIERs in dotted notation and returns one of the values 1, 0, -1 if $oid1 is respectively lexicographically greater, equal, or less than $oid2.

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 suitable for presentation. Some ASN.1 type definitions map to the same octet value when encoded. This method cannot distinguish 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 representing 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 display 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 constants and subroutines. These exportable symbols are defined below and follow the rules and conventions of the Exporter module (see Exporter).

Default 💖

These come through by default, bestie:

&snmp_dispatcher, INTEGER, INTEGER32, OCTET_STRING,
OBJECT_IDENTIFIER, IPADDRESS, COUNTER, COUNTER32, GAUGE, GAUGE32,
UNSIGNED32, TIMETICKS, OPAQUE, COUNTER64, NOSUCHOBJECT,
NOSUCHINSTANCE, ENDOFMIBVIEW

Exportable 🎁

And here's the full exportable menu:

&snmp_debug, &snmp_dispatcher, &snmp_type_ntop, &oid_base_match,
&oid_lex_cmp, &oid_lex_sort,&ticks_to_time, 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_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_VERSION_2C, SNMP_VERSION_3, SNMP_PORT,
SNMP_TRAP_PORT, TRANSLATE_NONE,TRANSLATE_OCTET_STRING,
TRANSLATE_NULL, TRANSLATE_TIMETICKS,
TRANSLATE_OPAQUE,TRANSLATE_NOSUCHOBJECT, TRANSLATE_NOSUCHINSTANCE,
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_TRANSPORT, DEBUG_DISPATCHER, DEBUG_PROCESSING,
DEBUG_SECURITY

:generictrap 🚨

COLD_START, WARM_START, LINK_DOWN, LINK_UP,
AUTHENTICATION_FAILURE, EGP_NEIGHBOR_LOSS, ENTERPRISE_SPECIFIC

:snmp 🌐

&snmp_debug, &snmp_dispatcher, &snmp_type_ntop, &oid_base_match,
&oid_lex_cmp, &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,
TRANSLATE_TIMETICKS, TRANSLATE_OPAQUE, TRANSLATE_NOSUCHOBJECT,
TRANSLATE_NOSUCHINSTANCE, TRANSLATE_ENDOFMIBVIEW,
TRANSLATE_UNSIGNED, TRANSLATE_ALL

:ALL 👑

All of the above exportable items.

🦋 EXAMPLES 🦋

Okay bestie, this is the fun part — real code, real SNMP energy. Let's go 💅

1. Blocking SNMPv1 get-request for sysUpTime

This example gets the sysUpTime from a remote host. Classic, iconic, does exactly what it says on the label ✨

#! /usr/local/bin/perl

use strict;
use warnings;

use Net::SNMP;

my $OID_sysUpTime = '1.3.6.1.2.1.1.3.0';

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

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

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

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

printf "The sysUpTime for host '%s' is %s.\n",
       $session->hostname(), $result->{$OID_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() constructor are for the demonstration of syntax only. These parameters will need to be set according to the SNMPv3 parameters of the remote host. The "snmpkey" utility included with the distribution can be used to create the key values.

No cap, that key bit matters 🔑

#! /usr/local/bin/perl

use strict;
use warnings;

use Net::SNMP;

my $OID_sysContact = '1.3.6.1.2.1.1.4.0';

my ($session, $error) = Net::SNMP->session(
   -hostname     => 'myv3host.example.com',
   -version      => 'snmpv3',
   -username     => 'myv3Username',
   -authprotocol => 'sha1',
   -authkey      => '0x6695febc9288e36282235fc7151f128497b38f3f',
   -privprotocol => 'des',
   -privkey      => '0x6695febc9288e36282235fc7151f1284',
);

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

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

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

printf "The sysContact for host '%s' was set to '%s'.\n",
       $session->hostname(), $result->{$OID_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.

The ifPhysAddress object in the table has a syntax of an OCTET STRING. By default, translation is enabled and non-printable OCTET STRINGs are translated into a hexadecimal format. Sometimes the OCTET STRING contains all printable characters and this produces unexpected output when it is not translated. The example turns off translation for OCTET STRINGs and specifically formats the output for the ifPhysAddress objects 🎀

#! /usr/local/bin/perl

use strict;
use warnings;

use Net::SNMP qw(:snmp);

my $OID_ifTable = '1.3.6.1.2.1.2.2';
my $OID_ifPhysAddress = '1.3.6.1.2.1.2.2.1.6';

my ($session, $error) = Net::SNMP->session(
   -hostname    => shift || 'localhost',
   -community   => shift || 'public',
   -nonblocking => 1,
   -translate   => [-octetstring => 0],
   -version     => 'snmpv2c',
);

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

my %table; # Hash to store the results

my $result = $session->get_bulk_request(
   -varbindlist    => [ $OID_ifTable ],
   -callback       => [ \&table_callback, \%table ],
   -maxrepetitions => 10,
);

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

# Now initiate the SNMP message exchange.

snmp_dispatcher();

$session->close();

# Print the results, specifically formatting ifPhysAddress.

for my $oid (oid_lex_sort(keys %table)) {
   if (!oid_base_match($OID_ifPhysAddress, $oid)) {
      printf "%s = %s\n", $oid, $table{$oid};
   } else {
      printf "%s = %s\n", $oid, unpack 'H*', $table{$oid};
   }
}

exit 0;

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

   my $list = $session->var_bind_list();

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

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

   my @names = $session->var_bind_names();
   my $next  = undef;

   while (@names) {
      $next = shift @names;
      if (!oid_base_match($OID_ifTable, $next)) {
         return; # Table is done.
      }
      $table->{$next} = $list->{$next};
   }

   # Table is not done, send another request, starting at the last
   # OBJECT IDENTIFIER in the response.  No need to include the
   # calback argument, the same callback that was specified for the
   # original request will be used.

   my $result = $session->get_bulk_request(
      -varbindlist    => [ $next ],
      -maxrepetitions => 10,
   );

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

   return;
}

4. Non-blocking SNMPv1 get-request and set-request on multiple hosts

This example first polls several hosts for their sysUpTime. If the poll of the host is successful, the sysContact and sysLocation information is set on the host. The sysContact information is hardcoded to "Help Desk x911" while the sysLocation information is passed as an argument to the callback. Multi-host main character energy fr fr 🌟

#! /usr/local/bin/perl

use strict;
use warnings;

use Net::SNMP;

my $OID_sysUpTime = '1.3.6.1.2.1.1.3.0';
my $OID_sysContact = '1.3.6.1.2.1.1.4.0';
my $OID_sysLocation = '1.3.6.1.2.1.1.6.0';

# Hash of hosts and location data.

my %host_data = (
   '10.1.1.2'  => 'Building 1, Second Floor',
   '10.2.1.1'  => 'Building 2, First Floor',
   'localhost' => 'Right here!',
);

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

for my $host (keys %host_data) {

   my ($session, $error) = Net::SNMP->session(
      -hostname    => $host,
      -community   => 'private',
      -nonblocking => 1,
   );

   if (!defined $session) {
      printf "ERROR: Failed to create session for host '%s': %s.\n",
             $host, $error;
      next;
   }

   my $result = $session->get_request(
      -varbindlist => [ $OID_sysUpTime ],
      -callback    => [ \&get_callback, $host_data{$host} ],
   );

   if (!defined $result) {
      printf "ERROR: Failed to queue get request for host '%s': %s.\n",
             $session->hostname(), $session->error();
   }

}

# Now initiate the SNMP message exchange.

snmp_dispatcher();

exit 0;

sub get_callback
{
   my ($session, $location) = @_;

   my $result = $session->var_bind_list();

   if (!defined $result) {
      printf "ERROR: Get request failed for host '%s': %s.\n",
             $session->hostname(), $session->error();
      return;
   }

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

   # Now set the sysContact and sysLocation for the host.

   $result = $session->set_request(
      -varbindlist =>
      [
         $OID_sysContact,  OCTET_STRING, 'Help Desk x911',
         $OID_sysLocation, OCTET_STRING, $location,
      ],
      -callback    => \&set_callback,
   );

   if (!defined $result) {
      printf "ERROR: Failed to queue set request for host '%s': %s.\n",
             $session->hostname(), $session->error();
   }

   return;
}

sub set_callback
{
   my ($session) = @_;

   my $result = $session->var_bind_list();

   if (defined $result) {
      printf "The sysContact for host '%s' was set to '%s'.\n",
             $session->hostname(), $result->{$OID_sysContact};
      printf "The sysLocation for host '%s' was set to '%s'.\n",
             $session->hostname(), $result->{$OID_sysLocation};
   } else {
      printf "ERROR: Set request failed for host '%s': %s.\n",
             $session->hostname(), $session->error();
   }

   return;
}

🌈 REQUIREMENTS 🌈

Okay, vibe check time — here's what this module needs to actually run:

  • The Net::SNMP module uses syntax that is not supported in versions of Perl earlier than v5.6.0.
  • The non-core modules Crypt::DES, Digest::MD5, Digest::SHA1, and Digest::HMAC are required to support SNMPv3.
  • In order to support the AES Cipher Algorithm as a SNMPv3 privacy protocol, the non-core module Crypt::Rijndael is needed.
  • To use UDP/IPv6 or TCP/IPv6 as a Transport Domain, the non-core module Socket6 is needed.

💖 AUTHOR 💖

David M. Town <dtown@cpan.org>

🫶 ACKNOWLEDGMENTS 🫶

The original concept for this module was based on SNMP_Session.pm written by Simon Leinen <simon@switch.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 University. All rights reserved.

Copyright (c) 1998-2010 David M. Town. All rights reserved.

This program is free software; you may redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

That's the whole manual page, bestie — source/version perl v5.42.0, dated 2012-10-15, for Net::SNMP(3pm). Periodt 💅✨

📦 where this page comes from