Net::S...etails(3pm)

📦 version 1.4, in ubuntu resolute, ubuntu stonking

✨ NAME ✨

Net::SNMP::Interfaces::Details — the manual page for it, living in User Contributed Perl Documentation, section 3pm. It's all about Object methods to obtain interface data 💖

🌸 SYNOPSIS 🌸

$in_octets = $interface->ifInOctets();

💅 DESCRIPTION 💅

Okay so bestie, listen. This class represents an individual interface as discovered by Net::SNMP::Interfaces. And yeah, technically you can call the constructor directly, but like... it is primarily intended that these objects get returned to you by methods of Net::SNMP::Interfaces. That's the vibe. That's the whole point. 🦋

🎀 METHODS 🎀

`new HASH $args`

The constructor for the class, periodt. Real talk though: user code should probably never need to call the constructor directly, because Net::SNMP::Interface::Details objects come back to you from the Net::SNMP::Interfaces methods all_interfaces() and interface(). Let the library do its thing, queen. 👑

There are three mandatory arguments, no cap:

Session — A valid Net::SNMP object, which gets used to make the requests for the interface info. Heads up though: this Net::SNMP object should currently only be of the blocking variety, because no provision has been made for non-blocking requests at present. So like, don't try it. 🙈
Index — The SNMP ifTable index for this interface.
Name — The name of this interface (e.g. 'eth0').

The Name and Index arguments should have previously been obtained by SNMP requests to the same host that the Session object was created for. Matching energy, y'know? ✨

`name`

Returns the name of this interface. Literally just the name. 💖

`index`

Returns the index of this interface.

`session`

Returns the Net::SNMP session object that's being used to make requests for this interface. Honestly this probably isn't needed, but it's here for completeness' sake. Filler episode but make it iconic. 💅

`error`

Returns the text of the last error returned from the SNMP session — and it will only be meaningful if the last method call returned undef, which is the signal that an error had occurred. So check for that undef first, bestie. 😭

`IANAifType`

Converts from an IANAifType integer value (as will be returned by ifType) to its text equivalent. Glow-up: numbers ➡️ words. ✨

The remainder of the methods are named after the literal names for the SNMP entries for network interfaces. The following descriptions are taken from the IF-MIB, with some additional comment from the author where necessary. And listen: if an error occurs in the SNMP session, these methods will return undef, and the text of the error message can be determined by calling the error() method. So keep error() on speed dial. 📞

`ifIndex`

A unique value, greater than zero, for each interface. It's recommended that values are assigned contiguously starting from 1. The value for each interface sub-layer must remain constant at least from one re-initialization of the entity's network management system to the next re-initialization. Stability is the whole serve. 💅

`ifDescr`

A textual string containing info about the interface. This string should include the name of the manufacturer, the product name, and the version of the interface hardware/software. 🏷️

(In practice this will be name of the interface e.g. 'eth0') — yeah, in reality it's just the interface name, iykyk.

`ifType`

The type of interface. Additional values for ifType are assigned by the Internet Assigned Numbers Authority (IANA), through updating the syntax of the IANAifType textual convention. So if you see a type you don't recognise, blame IANA, not me. 🌈

`ifMtu`

The size of the largest packet which can be sent/received on the interface, specified in octets. For interfaces used for transmitting network datagrams, this is the size of the largest network datagram that can be sent on the interface. Big packet energy. 📦

`ifSpeed`

An estimate of the interface's current bandwidth in bits per second. For interfaces which don't vary in bandwidth, or for those where no accurate estimation can be made, this object should contain the nominal bandwidth. And here's the tea: if the bandwidth of the interface is greater than the maximum value reportable by this object, then this object should report its maximum value (4,294,967,295) and ifHighSpeed must be used to report the interace's speed. For a sub-layer which has no concept of bandwidth, this object should be zero. 🚀

`ifPhysAddress`

The interface's address at its protocol sub-layer. For example, for an 802.x interface, this object normally contains a MAC address. The interface's media-specific MIB must define the bit and byte ordering and the format of the value of this object. For interfaces which don't have such an address (e.g., a serial line), this object should contain an octet string of zero length. No address? No problem. 🫶

`ifAdminStatus`

The desired state of the interface. The testing(3) state indicates that no operational packets can be passed. When a managed system initializes, all interfaces start with ifAdminStatus in the down(2) state. As a result of either explicit management action or per configuration information retained by the managed system, ifAdminStatus is then changed to either the up(1) or testing(3) states (or remains in the down(2) state). It's giving "what we want it to be". 💭

`ifOperStatus`

The current operational state of the interface. The testing(3) state indicates that no operational packets can be passed. If ifAdminStatus is down(2) then ifOperStatus should be down(2). If ifAdminStatus is changed to up(1) then ifOperStatus should change to up(1) if the interface is ready to transmit and receive network traffic; it should change to dormant(5) if the interface is waiting for external actions (such as a serial line waiting for an incoming connection); it should remain in the down(2) state if and only if there is a fault that prevents it from going to the up(1) state; it should remain in the notPresent(6) state if the interface has missing (typically, hardware) components. It's giving "what it actually is", and it's a whole mood board of states. 😭

`ifLastChange`

The value of sysUpTime at the time the interface entered its current operational state. If the current state was entered prior to the last re-initialization of the local network management subsystem, then this object contains a zero value. 🕰️

`ifInOctets`

The total number of octets received on the interface, including framing characters. And heads up: discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of ifCounterDiscontinuityTime. ⚠️

`ifInUcastPkts`

The number of packets, delivered by this sub-layer to a higher (sub-)layer, which were not addressed to a multicast or broadcast address at this sub-layer. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of ifCounterDiscontinuityTime. ⚠️

`ifInNUcastPkts`

The number of packets, delivered by this sub-layer to a higher (sub-)layer, which were addressed to a multicast or broadcast address at this sub-layer. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of ifCounterDiscontinuityTime. 🚨 And major note: this object is deprecated in favour of ifInMulticastPkts and ifInBroadcastPkts. RIP bozo, you're old news. 💀

`ifInDiscards`

The number of inbound packets which were chosen to be discarded even though no errors had been detected to prevent their being deliverable to a higher-layer protocol. One possible reason for discarding such a packet could be to free up buffer space. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of ifCounterDiscontinuityTime. 🗑️

`ifInErrors`

For packet-oriented interfaces, the number of inbound packets that contained errors preventing them from being deliverable to a higher-layer protocol. For character-oriented or fixed-length interfaces, the number of inbound transmission units that contained errors preventing them from being deliverable to a higher-layer protocol. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of ifCounterDiscontinuityTime. 😭

`ifInUnknownProtos`

For packet-oriented interfaces, the number of packets received via the interface which were discarded because of an unknown or unsupported protocol. For character-oriented or fixed-length interfaces that support protocol multiplexing, the number of transmission units received via the interface which were discarded because of an unknown or unsupported protocol. For any interface that does not support protocol multiplexing, this counter will always be 0. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of ifCounterDiscontinuityTime. ❓

`ifOutOctets`

The total number of octets transmitted out of the interface, including framing characters. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of ifCounterDiscontinuityTime. 📤

`ifOutUcastPkts`

The total number of packets that higher-level protocols requested be transmitted, and which were not addressed to a multicast or broadcast address at this sub-layer, including those that were discarded or not sent. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of ifCounterDiscontinuityTime. ⚠️

`ifOutNUcastPkts`

The total number of packets that higher-level protocols requested be transmitted, and which were addressed to a multicast or broadcast address at this sub-layer, including those that were discarded or not sent. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of ifCounterDiscontinuityTime. 🚨 And again: this object is deprecated in favour of ifOutMulticastPkts and ifOutBroadcastPkts. Retired. Gone. 💀

`ifOutDiscards`

The number of outbound packets which were chosen to be discarded even though no errors had been detected to prevent their being transmitted. One possible reason for discarding such a packet could be to free up buffer space. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of ifCounterDiscontinuityTime. 🗑️

`ifOutErrors`

Okay so picture this: for packet-oriented interfaces, this is the number of outbound packets that straight up could not be transmitted because of errors 😭. For character-oriented or fixed-length interfaces? It's the number of outbound transmission units that couldn't be transmitted because of errors. Same energy, different unit, bestie.

And the classic warning: discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of ifCounterDiscontinuityTime. So don't come for her if the numbers jump around 💅

`ifOutQLen`

The length of the output packet queue (in packets). That's it, that's the whole vibe.

⚠️ Heads up bestie: this object has been deprecated as of rfc2863. It's giving legacy. Still listed, still real, but deprecated fr fr.

`ifSpecific`

A reference to MIB definitions specific to the particular media being used to realize the interface. ✨

It is recommended that this value point to an instance of a MIB object in the media-specific MIB, i.e., that this object have the semantics associated with the InstancePointer textual convention defined in RFC 1903. In fact — and this is the extra part — it is recommended that the media-specific MIB specify what value ifSpecific should/can take for values of ifType. 🫶

If no MIB definitions specific to the particular media are available, the value should be set to the OBJECT IDENTIFIER { 0 0 }. Zero zero, no notes.

the ifXTable girlies 👑

These next methods are from the ifXTable as described in rfc2863:

This table contains objects that have been added to the Interface MIB as a result of the Interface Evolution effort, or replacements for objects of the original (MIB-II) ifTable that were deprecated because the semantics of said objects have significantly changed. This table also contains objects that were previously in the ifExtnsTable.

Now the important bit, don't skip this one:

These methods may not be available from all network elements, and in those cases they will return undef. So check before you spiral, okay? 💀

`ifName`

The textual name of the interface. 🎀

The value of this object should be the name of the interface as assigned by the local device, and should be suitable for use in commands entered at the device's console. This might be a text name, such as le0, or a simple port number, such as 1, depending on the interface naming syntax of the device.

If several entries in the ifTable together represent a single interface as named by the device, then each will have the same value of ifName. Note that for an agent which responds to SNMP queries concerning an interface on some other (proxied) device, then the value of ifName for such an interface is the proxied device's local name for it. 🦋

If there is no local name, or this object is otherwise not applicable, then this object contains a zero-length string. Empty. Nothing. Silence. 🙈

`ifInMulticastPkts`

The number of packets, delivered by this sub-layer to a higher (sub-)layer, which were addressed to a multicast address at this sub-layer. For a MAC layer protocol, this includes both Group and Functional addresses. 🌈