# SNMP support for Perl 5: Changes

Copyright (c) 1995-2023, Simon Leinen
All rights reserved

This program is free software; you can redistribute it under the "Artistic License" included in this distribution.

Author: Simon Leinen <simon.leinen@switch.ch>

## Recent Changes:

- SNMP_Session.pm 1.16: Packaging improvements from Michal Josef Špaček.
- test/get-cisco-power-usage.pl: New demo script to receive power utilization from Cisco routers using CISCO-ENTITY-SENSOR-MIB.
- SNMP_Session.pm 1.15: Apply Socket6 patch from FreeBSD ports.
- SNMP_Session.pm 1.14: `open_trap_session` now takes an optional `ipv4only` argument. It defaults to 1, but by passing 0, you can create a session that accepts traps over IPv6 in addition to IPv4. The `receive_trap` method has been enhanced by returning an additional value which is the address family. There is a new `receive_trap_1` method, which differs from `receive_trap` in that it simply returns the trap and a sockaddr structure, rather than the trap, the host address, the port, and the address family.
- BER.pm 1.14: Added POD documentation. Started adding automated unit tests.
- SNMP_Session.pm 1.14: Added POD documentation.
- SNMP_util.pm 1.13: Parse OIDs in NOTIFICATION-TYPE names. Change by Mike Mitchell/jaccobs.
- SNMP_Session.pm 1.13: Fixed the optional socket-reuse code to handle IPv4 and IPv6 sockets separately.
- SNMP_Session.pm 1.12: Upgraded to Artistic License 2.0 upon a suggestion from Tom Callaway.
- SNMP_util.pm 1.12: Rewritten MIB parsing code from Mike Mitchell.
- SNMP_util.pm 1.11: Improvement to loop detection in snmpwalk. Should cope with more broken agents. Change by Mike Mitchell.
- SNMP_Session.pm 1.10: Mike Fischer reported that on some systems, notably Linux, `recv()` may block even though a preceding `select()` for readability has returned successfully. Once condition where this can happen is when a UDP checksum on an incoming datagram doesn't verify. To avoid our library from blocking in this case, we have to pass `MSG_DONTWAIT` to `recv()`. This behaviour is selected by a new optional argument to `receive_response_3`, and used by `request_response_5`.
- SNMP_util.pm 1.09: Fix from Mike Mitchell for parsing qualified symbolic OIDs.
- SNMP_Session.pm 1.08: Fixed a bug in the SNMPv2c version of `map_table_start_end` that would cause errors when the `$end` argument is actually being used. Thanks to Jan van Keulen for submitting the patch.
- SNMP_Session.pm 1.07: Fixed `strict subs` error with newer versions of Perl. Thanks to Gerry Dalton for spotting this.
- SNMP_Session.pm 1.06: `decode_trap_request` now understands SNMPv2 inform requests in addition to SNMPv1 traps and SNMPv2 traps. Contributed by Andrew Cornford-Matheson.
- SNMP_util.pm 1.06: `snmpwalkhash` fix by Laurent Girod.
- `index.html`: The code is no longer available from `ftp.switch.ch`, but via HTTP from `www.switch.ch`.
- SNMP_Session.pm 1.05: No change; version incremented for `SNMP_util.pm` and `BER.pm`.
- BER.pm 1.05: Internal restructuring: The new (BER.pm 1.02) pretty-printer registration method is now used for most standard SNMP types, too.
- SNMP_util.pm 1.04: The subroutines `snmpget`, `snmpgetnext` and `snmpset` will now detect when they are called in scalar context, and return only the first (and typically the only) of the retrieved values in this case.
- SNMP_util.pm 1.03: Added a missing part of Mike Mitchell pretty-printer registration patch.
- BER.pm 1.02: Additional decoders (``pretty printers'') can now be registered and unregistered for type codes using the `register_pretty_printer` and `unregister_pretty_printer` subroutines. Implemented by Mike Mitchell.
- BER.pm 1.02: Corrected encoding of large integer-like values.
- SNMP_util.pm 1.02: `snmpwalkhash` now takes an additional optional argument that should be a reference to a hash. If used, `snmpwalkhash` will insert the retrieved values into that hash.
- BER.pm 1.01: Properly parse the variant length format in integers. Thanks to Milen Pavlov for pointing out this bug. Also, decoding should be slightly more efficient in general, because one `substr()` operation per (sub-) object has been eliminated.
- SNMP_Session 1.00: Added Luc Pauwels' implementation of the `use_16bit_request_ids` option. Some SMC devices seem to require this.
- SNMP_Session 0.99: Improved request ID generation so that `avoid_negative_request_ids` is always obeyed.
- SNMP_util 0.99: Added `Gauge32` support to `snmpset`. Thanks to Christopher J. Tengi for the idea. Mike Mitchell provided new code that supports all known types.
- SNMP_Session 0.98: Portability fix in IPv6 support.
- SNMP_util 0.98: Support encoding of OIDs containing multiple quoted strings.
- SNMP_util 0.97: Added support for TimeTicks values in `snmpset`. Patch from Joerg Kummer
- SNMP_Session 0.97: Exported `$SNMP_Session::default_avoid_negative_request_ids`, by Philippe Simonet.
- SNMP_Session 0.97: IPv6 support added by Valerio Bontempi and Lorenzo Colitti.
- SNMP_Session 0.96: Intermediate version with IPv6 support; not published.
- BER.pm 0.95: Fixed operator precedence bug in decode_sequence().
- SNMP_Session.pm 0.94: A new slot `capture_buffer` has been added to the SNMP_Session classes, courtesy Jakob Ilves. See the sample script `test/capturetest.pl` for an example of how to use this.
- BER.pm 0.94: New subroutines `pretty_generic_sequence`, `decode_generic_tlv`, courtesy Jakob Ilves.
- BER.pm 0.94: `decode_by_template`, `decode_oid`, `decode_sequence`, `decode_string`: Explicitly signal error when the PDU is undefined or too short. This improves error handling for some malformed PDUs, as generated by certain test suites.
- SNMP_Session.pm 0.93: There's a new variable `$default_avoid_negative_request_ids`. If it is set to a non-zero value, newly created `SNMP_Session` objects will be configured so that only request IDs in the range 0..231-1 will be used. This is needed to work around a bug in several SNMP agents. If you sometimes see requests fail, and the error message always shows a negative request ID when that happens, please notify the vendor of your agent of the bug. While the vendor fixes the problem, you can set the variable mentioned above to work around the bug. The problem has been described in a few mails on the mrtg-developers mailing list that can hopefully be found here in the archive.
- SNMP_util.pm 0.93: `snmpwalk` now will walk multiple OID trees simultaneously. If more than one OID is passed to the function, the returned OID:value pairs will contain the entire OID instead of just the leaf from the starting point.
- SNMP_util.pm 0.93: `snmpwalkhash` now passes the textual OID of the starting point as the seventh argument to the passed-in hash function.
- SNMP_util.pm 0.92: New subroutine `snmpmaptable4`, which allows specifying the max-repeaters.
- SNMP_util.pm 0.92: New MIB parsing code. Most MIBs are processed in one pass, but if an OID cannot be fully resolved, an extra pass is done. Also, `OBJECT-GROUP` entries are now recognized.
- SNMP_util.pm 0.92: The string-to-OID conversion routines now transparently convert quoted strings to instance indexes. For example, `"/usr"` (including the quotes) would be converted to `4.47.118.97.114`.
- SNMP_Session.pm 0.91: Fixed a bug in `map_table_start_end` for `SNMPv2_Session` (which uses `get-bulk`) which had caused a superfluous query after the entire table has already been provably traversed. Thanks to Michael Deegan for pointing this out.
- SNMP_util.pm 0.90: New version from Mike Mitchell. `snmpwalkhash` and `snmpwalk` now share most code.
- SNMP_util.pm 0.90: Corrected handling of the optional port number in `snmpopen`.
- test/if-counters.pl: Support 64-bit counters, and use `ifAlias` to portably get interface descriptions.
- SNMP_util.pm 0.89: New version from Mike Mitchell, with new `snmpwalkhash` subroutine by Laurent Girod.
- SNMP_Session.pm 0.89: Made `lenient_source_port_matching` the default.
- SNMP_util.pm 0.89: Fixed a long-standing bug where the code would generate PDUs with `request-id`s with large positive values, violating the SNMP spec which mandates that `request-id`s be `Integer32`s. Thanks to Sergio Macedo for finding this bug.
- SNMP_util.pm 0.88: Added missing `use Carp;` statements in packages `SNMPv1_Session` and `SNMPv2_Session`. Thanks to Michael Deegan.
- SNMP_util.pm 0.87: No change from 0.86, but increased version number to reflect change in BER.pm (SNMPv2 exception codes).
- BER.pm 0.87: `pretty_print` now silently returns undef when decoding SNMPv2 exception codes (`noSuchObject`, `noSuchInstance`, or `endOfMibView`, see RFC 1905). Original patch by Bert Driehuis.
- BER.pm 0.86: `pretty_print` now silently returns undef when given an undefined value, rather than issuing incomprehensible warnings.
- SNMP_util.pm 0.86: New `snmpmaptable` subroutine. This is a more user-friendly version of `map_table` and is described in the README.SNMP_util file. From Mike Mitchell.
- SNMP_util.pm 0.86: Support for the awesome `get-bulk` operator, both directly through the new `snmpgetbulk` subroutine, and transparently via `snmpwalk` when the session's SNMP version is >= 2 and the `use_getbulk` slot is set (as it is by default). From Mike Mitchell.
- SNMP_Session.pm 0.85: If a local address is specified in `snmpopen`, don't convert it using `inet_aton`, because this is handled by the Socket library. Fix from Mike McCauley.
- SNMP_Session.pm 0.85: Added `lenient_source_port_matching` slot to the session object. Set this to communicate with weird SNMP agents that send the response from a port other than 161. Suggestion from Henri Gomez.
- SNMP_util.pm 0.84: New version from Mike Mitchell. `snmpopen` now parses an optional hash argument for options. Also reintroduced defaulting of the UDP port to 161 for ``normal'' sessions.
- SNMP_Session.pm 0.84: Clarified documentation concerning the `%pretty_oids` hash, upon a suggestion from Alistair Mills.
- SNMP_Session.pm 0.83: The source address in response packets is now ignored when matching responses against outstanding queries. In a couple of previous revisions, the source address in response packets had to match the destination address in the corresponding query. Unfortunately some agents may use a different source address in responses. If you want the strict behavior back, you can send the `lenient_source_address_matching` slot of the session object to zero.
- SNMP_Session.pm 0.83: The source address for outgoing packets can now be specified as an additional optional argument to `open`. If you don't specify it, the system will choose the source address by itself, usually corresponding to the interface on which packets are sent.
- SNMP_Session.pm 0.83: Fixed a bug which had caused requests to be resent upon receipt of packets which don't match the outstanding query.
- SNMP_Session.pm 0.82: Fixed retry logic to avoid sending a last retry without waiting for the response anymore. Thanks to Brett T Warden for the fix.
- BER.pm 0.82: OIDs with only two subids can now be encoded. The most common case is the "null" OID (0.0). Thanks to Brett T Warden for pointing out that this didn't work.
- BER.pm 0.82: pretty_print() now handles UInteger32 objects. Patch by Brett T Warden.
- BER.pm 0.81: Subids in the range 2^31 - 2^32-1 are now encoded correctly. Thanks to Rik Hoorelbeke for noticing the problem.
- SNMP_Session.pm 0.81: A cosmetic bug in the SNMPv2 version of `map_table` (which uses `get-bulk`) was corrected. The user-supplied function is now always called on the same number of arguments. Before this, missing values at the end of a table row would lead to the function being called with fewer arguments. Now there will be `undef` values for those, too. Thanks to Ulrich Schmid for pointing this out.
- SNMP_Session.pm 0.80: A portability bug was fixed in the code that matches incoming responses to outstanding requests. The bug had manifested itself, notably on some FreeBSD versions, by timeouts waiting for responses, because the library thought the responses came from another address than the corresponding requests had been sent to.
- SNMP_Session.pm 0.79: A new variable `$SNMP_Session::recycle_socket` has been introduced. When this variable is set to a non-zero value (the default is zero), all newly created SNMP_Session objects will share the same UDP socket. This saves file descriptors and system calls, but will cause problems with multiple outstanding SNMP requests on different session objects. Applications which don't perform parallel/asynchronous SNMP requests can safely set this variable to reduce OS overhead somewhat. Suggestion from Ulrich Schmid.
- SNMP_Session.pm 0.79: The handling of incoming packets from unexpected addresses has been cleaned up. If a packet is received from an IP address other than the one to which the request has been sent, this packet is silently ignored, as mandated by the SNMP standard.
- SNMP_Session.pm 0.79: Receive-only session objects (such as the ones created by `open_trap_session` now have `undef` as the `remote_addr` value, rather than IP address `0.0.0.0`.
- BER.pm 0.79: There are new exported subroutines for encoding different types of values: `encode_uinteger32`, `encode_counter32`, `encode_counter64`, `encode_gauge32`.
- SNMP_Session.pm 0.78: The `map_table` implementation for SNMPv2 sessions has been completely rewritten to reliably support tables with holes in them. Note that this hasn't been completely validated or tested yet, but at least it has been found to handle common cases reasonably.
- BER.pm 0.77: Added support for long integers, so that `Counter64` values can be handled without risk of losing precision (due to automatic coercion to floating-point representation by Perl). When a BER-encoded integer is so long that it might not fit in a 32-bit unsigned integer, then we use `Math::BigInt` arithmetics to convert it. Warning: code which calls the decoding functions should be prepared to handle `Math::BigInt` values if `Counter64` values can be accessed. In most respect, those long integers behave just like ordinary integers. A notable exception is that they print with a leading ```+`'' sign.
- SNMP_Session 0.77: The SNMPv2 implementation of `map_table_start_end` has been enhanced to cope with the case where a response PDU ends with a truncated table row, courtesy Paul E. Erkkila. Note that tables with missing entries still aren't handled correctly when SNMPv2 (and thus the `get-bulk` operator is used).
- SNMP_util 0.73: Added a fix from Mike Mitchell (originally Johannes Demel) to treat `OBJECT-IDENTITY` like `OBJECT IDENTIFIER`.
- SNMP_Session 0.76: Added some debugging support for `map_table`, which still doesn't work reliably when the SNMPv2 `get-bulk` operator is used.
- test/if-counters.pl: Added `-c` option to enable Cisco-specific variables (which are no longer retrieved by default as in previous versions).
- SNMP_Session 0.75: Fixed a bug in versions 0.73-0.74 where creation of trap listener sockets would fail. Rather than using `bind` to bind to the trap port, we now pass a `LocalPort` argument to `INET->new`.
- SNMP_Session 0.75: Parse SNMPv2-Trap-Requests in addition to SNMPv1 ones. A caller can tell whether an SNMPv1 or an SNMPv2 request has been received by testing whether the SNMPv1-specific fields are defined. The sample script `test/trap-listener` has been updated to understand SNMPv2 Traps.
- SNMP_Session 0.75: New subroutine `v2_trap_request_send` which sends SNMPv2 Trap PDUs. The sample script `test/trap-send` has been extended to generate either type of trap on request.
- SNMP_Session 0.74: Put under copyright and Artistic License.
- SNMP_util 0.72: Changed `snmpgetnext` so it will return the next lexicographical larger OID number, even if it is not in the same OID tree. Before the change snmpget would discard the return value if the OID wasn't in the same tree. In `snmpMIB_to_OID`, an "unitialized variable" warning was removed. (Changes by Mike Mitchell, the author)
- SNMP_Session 0.73: The UDP socket associated with each SNMP session object is now created using `IO::Socket::INET->new`. Before this change, a Perl file descriptor name was generated for each new socket. Apparently this caused a file descriptor leak. The new code is much cleaner and doesn't have that problem anymore. Hopefully the newly introduced dependency on the Socket::IO module is not a problem. Thanks to Andrew W. Elble for suggesting this change.
- BER.pm 0.72: A new variable, `$BER::pretty_print_timeticks`, has been introduced to give users control over the degree of pretty-printing of `TimeTicks` values. If left at the defaults, `TimeTicks` values will be converted to strings such as `14 days, 6:56:07`. If you set it to zero, the same value will simply pretty-print as `123456789`, which should be interpreted in units (ticks) of 10ms.
- SNMP_util.pm 0.71: New subroutines `snmpLoad_OID_Cache` and `snmpQueue_MIB_File` for loading MIBs in compact format.
- SNMP_util.pm 0.71: `snmpset` now accepts `ipaddr` as a type specifier.
- SNMP_util.pm 0.70: Mike Mitchell added code for parsing MIB files. See the description of `snmpMIB_to_OID` in `README.SNMP_util`.
- SNMP_util.pm 0.69: Enable parsing of community strings which contain `@` characters.
- SNMP_util.pm 0.58: Check for errors from `encode_oid`, so that illegal OIDs generate error messages. Allow for suppression of warnings by setting `$SNMP_Session::suppress_warnings` to a value greater than one.
- SNMP_Session.pm 0.68: Added methods `receive_request` and `decode_request` to support SNMP agents. Contributed by Mike McCauley.
- SNMP_Session.pm 0.67: Implement a `map_table_start_end` method for `SNMPv2c_Session` which uses `get-bulk`. See Walking Tables With `get-bulk` for more information.
- SNMP_Session.pm 0.66: Fix from Alan Nichols to the handling of error replies. In the last few revisions of SNMP_Session, requests to which the agent responded with a non-zero `errorStatus` were erroneously retried.
- SNMP_Session.pm 0.66: When the `errorStatus` is zero, we don't care about the `errorIndex`. This makes us liberal enough to cope with very old versions of the CMU agent code which sometimes put a non-zero `errorIndex` in normal response packets.
- BER.pm 0.66: Changed the `$VERSION` number to be in line with SNMP_Session.pm's.
- BER.pm 0.66: Changed `encode_oid` so that it signals an error when passed an illegal Object ID, such as one whose first subid isn't 0, 1 or 2. This should help people who try to use output from CMU/UCD SNMP directly in MRTG.
- SNMP_Session.pm 0.65: Fix error message when binding to UDP port fails (Jonathan Zhukovsky).
- SNMP_util.pm 0.57: Small change to avoid warnings with "-w" when session parameters are defaulted.
- SNMP_util.pm 0.56: New subroutine `snmpmapOID`, Mike Mitchell.
- SNMP_Session.pm 0.64: Fix of a bug in the detection of missing responses by Mike Mitchell.
- SNMP_Session.pm 0.63: Fixed response matching logic to ignore out-of-sequence responses. This has been a long-standing bug which made it very hard to use a single session object for multiple queries to devices that are (sometimes) slow in responding.
- SNMP_Session.pm 0.62: Scoping problem with pretty_address() fixed.
- Makefile.PL: New file which allows for easy installation according to standard Perl convention. Kudos to Clinton Wong.
- SNMP_Session.pm 0.61: The sender address of the last response received for a session is stored in $session->{'last_sender_addr'}. In connection with broadcast or multicast addresses, this can be used to discover SNMP agents listening to specific communities, as illustrated in `test/discover`.
- SNMP_Session.pm 0.60: Added support for receiving SNMPv1 traps.
- SNMP_session.pm 0.59: Added methods `set_timeout`, `set_retries`, and `set_backoff` that can be used to tune the retransmission algorithm. Fixed a bug in `map_table` that would cause an index of "0" to terminate the table walk.
- SNMP_util.pm 0.54: First version to be distributed with the package, courtesy Mike Mitchell.
- BER.pm 0.58: Added `encode_timeticks()` subroutine. This was used in the sample script for sending traps, but was only defined in `test/trap-test.pl`. Thanks to Gary Berger for noticing this.
- BER.pm 0.57: Added `encode_ip_address()` subroutine on a suggestion by Mike Diehn.
- SNMP_Session 0.58: Added support for generating traps, courtesy Mike Mitchell, see Sending Traps.
- `test/ber-test.pl`: Added more test cases contributed by Mike Mitchell.
- SNMP_Session 0.57: table walking support See ``Walking Tables'' below for how this is used.
- BER 0.56: New `encode_int()` subroutine contributed by Mike Mitchell. Fixes incorrect encoding in the range +-2^15-2^23 and generalized to integers of any size.
- BER 0.55: Fix an arithmetic bug in the uptime pretty-printer. Kudos to Niels Bakker for noticing this.
- SNMP_Session 0.56: Fix a bug which occurs when an error should be signaled while an SNMPv1_Session is being opened. Noticed by Dan Cox and Iouri Pakhomenko.
- BER 0.52: Ignore a leading dot when encoding an OID. This is to avoid trouble when people cut&paste OIDs from CMU/UCD SNMP, where a leading dot is used to mark a "fully qualified" OID.
- SNMP_Session 0.55: The SNMP_Session module no longer calls `warn` when the variable `$SNMP_Session::suppress_warnings` is set to non-zero (it is zero by default). The error message from SNMP_Session can be retrieved as `$SNMP_Session::errmsg`.
- SNMP_Session 0.54, BER.pm 0.51: Errors in the BER module are now passed upwards by the SNMP_Session module. Before this change, one could not distinguish malformed SNMP responses from no response at all. The BER module now no longer calls die(), but returns undefined values.
- Added `test/arp` which prints the NetToMedia table from a remote host.
- SNMP_Session 0.53: Avoid passing numeric IP addresses to `inet_ntoa()`, by Daniel L. Needles
- SNMP_Session 0.52: setRequest support based on code contributed by Matthew Trunnell. See ``Set Requests'' below for how this is used.
- SNMP_Session 0.51: Improved error messages by printing the session in error messages if possible, and the OID and error message whenever the agent sends back an error.
- SNMP_Session 0.50, BER 0.50: The BER and SNMP_Session modules both have version numbers according to the convention in Exporter.pm. That is, you can now insist on a minimal version of the modules by saying e.g.

      use BER "0.50";
      use SNMP_Session "0.52";

  The initial version numbers are 0.50 for both modules.
- The pretty printer should now print unsigned 32-bit values (such as Counters and Gauges) correctly, i.e. values larger than 231 are printed as large positive numbers rather than negative numbers. Note that this can cause problems depending on how you handle the output of the pretty printer, since those string representations of large numbers may not be convertible to integers using atoi() or similar functions.
- The subroutines in SNMP_Session never call die() anymore if it encouters error situations. Instead, they issue a warning and return undef. Brad Ritchie managed to convince me that library code should never die. Unfortunately I haven't revised BER.pm yet, so subroutines related with BER transfer syntax encoding and decoding may still die.
- The code has been cleaned up to use more of the standard functionality of the Perl 5 Socket.pm module. That should have eliminated some potential portability problems (and delegated responsability for potential bugs :-). Note that this means that the code requires Perl 5.002 or later.
- Both source files now make extensive use of strict for better compile-time error checking. Please notify me in case you have any problems because of this.
- The library now attempts to retransmit queries for which no reponse has been received during a given time. The default parameters for the retransmission logic have been discussed at length in the mrtg mailing list, and seem to work quite well, both against overloaded routers that simply drop some SNMP requests and against routers that are behind slow or lossy links. If you have feedback on the default parameters, please drop me an e-mail.
- When I implemented the retransmission logic, I also fixed handling of request IDs. In older versions, the request ID was never changed between reqeuest, which could lead to (late) resposes being associated with the wrong request. Now the request ID is incremented for each request, and mismatching responses are ignored. For retransmissions, the request ID isn't changed. If we did change it, we could estimate response time and implement an adaptive retransmission algorithm. This has been left for further study.
- Added code contributed by mrtg users:
  - Encoding of larger subids, by Philippe Simonet and Yufang HU
  - Decoding sysUpTime, by Dave Rand
  - Decoding longer (unsigned) integers, by Tobias Oetiker
  - Decoding longer strings, by Andrzej Tobola
  - More reasonable socket initialization, by Heine Peters
  - Correct integer BER-encoding, by Mike Mitchell