To use this module, you must have Net-SNMP installed on your system. More specifically you need the Perl modules that come with it.

DO NOT INSTALL SNMP:: or Net::SNMP from CPAN!

The SNMP module is matched to an install of net-snmp, and must be installed from the net-snmp source tree.

The Perl module SNMP is found inside the net-snmp distribution. Go to the perl/ directory of the distribution to install it, or run ./configure --with-perl-modules from the top directory of the net-snmp distribution.

Detects looping during getnext table column walks by comparing IIDs for each instance. A loop is detected if the same IID is seen more than once and the walk is aborted. Note: This will not detect loops during a bulkwalk operation, Net-SNMP's internal bulkwalk function must detect the loop.

Set to 1 "on" to ignore Net-SNMP configuration files by overriding the SNMPCONFPATH environmental variable during object initialization. Note: MibDirs must be defined or Net-SNMP will not be able to load MIBs and initialize the object.

When using SNMP Version 1, try reading values even if they come back as "no such variable in this MIB". Set to false if so desired. This feature lets you read SNMPv2 data from an SNMP version 1 connection, and should probably be left on.

Pass in a HashRef to prime the cache of retrieved data. Useful for creating an instance in Offline mode from a previously dumped cache. See also the cache() method to retrieve a cache after running actial queries.

If a connection is using the wrong community string or the wrong SNMP version, the creation of the object will not fail. The device still answers the call on the SNMP port, but will not return information. Check the error() method after you create the device object to see if there was a problem in connecting.

A note about SNMP Versions :

Some older devices don't support SNMP version 2, and will not return anything when a connection under Version 2 is attempted.

Some newer devices will support Version 1, but will not return all the data they might have if you had connected under Version 1

When trying to get info from a new device, you may have to try version 2 and then fallback to version 1.

Replace the existing session with a new one with updated values, without re-identifying the device. The only supported changes are to Community or Context.

Clears the object cache.

This is useful, e.g., when a device supports multiple contexts (via changes to the Community string, or via the SNMPv3 Context parameter), but a context that you want to access does not support the objects (e.g., sysObjectID, sysDescr) that we use to identify the device.

Number of octets sent/received on the interface including framing characters.

64 bit version may not exist on all devices.

NOTE: To manipulate 64 bit counters you need to use Math::BigInt, since the values are too large for a normal Perl scalar. Set the global $SNMP::Info::BIGINT to 1 , or pass the BigInt value to new() if you want SNMP::Info to do it for you.

"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." (IF-MIB)

"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."

"The IP address of the next hop of this route.
(In the case of a route bound to an interface
which is realized via a broadcast media, the value
of this field is the agent's IP address on that
interface.)"

other(1), -- none of the following
invalid(2), -- an invalidated route
-- route to directly
direct(3), -- connected (sub-)network
-- route to a non-local
indirect(4) -- host/network/sub-network
"The type of route. Note that the values
direct(3) and indirect(4) refer to the notion of
direct and indirect routing in the IP
architecture.
Setting this object to the value invalid(2) has
the effect of invalidating the corresponding entry
in the ipRouteTable object. That is, it
effectively disassociates the destination
identified with said entry from the route
identified with said entry. It is an
implementation-specific matter as to whether the
agent removes an invalidated entry from the table.
Accordingly, management stations must be prepared
to receive tabular information from agents that
corresponds to entries not currently in use.
Proper interpretation of such entries requires
examination of the relevant ipRouteType object."

The common topology table methods below will query the device for information from the specified topology protocols and return a single hash combining all information. As a result, there may be identical topology information returned from the two protocols causing duplicate entries. It is the calling program's responsibility to identify any duplicate entries and remove duplicates if necessary. If it is necessary to understand which protocol provided the information, utilize the protocol specific methods directly rather than the generic methods.

The methods support partial table fetches by providing a partial as the first argument.

If a reference to an array is provided as the second argument, those protocols will be queried for information. The supported array values are: lldp, cdp, sonmp, fdp, edp, amap.

If nothing is passed in as the second argument, the methods will call has_topo() to determine supported and running topology protocols on the device.

If multiple entries exist with the same local port, c_if(), with the same IPv4 address, c_ip(), it may be a duplicate entry.

If multiple entries exist with the same local port, c_if(), with different IPv4 addresses, c_ip(), there is either a device in between two or more devices utilizing a different topology protocol or multiple devices which are not directly connected.

NOTE: You must be connected to your device with a ReadWrite community string in order for set operations to work.

NOTE: This will only set data listed in %FUNCS and %GLOBALS. For data acquired from overridden methods (subroutines) specific set_METHOD() subroutines will need to be added if they haven't been already.

To support a new class (vendor or platform) of device, add a Perl package with the data structures and methods listed below.

If this seems a little scary, then the SNMP::Info developers are usually happy to accept the SNMP data from your device and make an attempt at the class themselves. Usually a "beta" release will go to CPAN for you to verify the implementation.

The preference is to open a feature request in the SourceForge project. This allows all developers to have visibility into the request. Please include pointers to the applicable platform MIBs. For development we will need an snmpwalk of the device. There is a tool now included in the SNMP::Info distribution to help with this task, although you'll most likely need to download the distribution from CPAN as it's included in the "t/util" directory.

The utility is named make_snmpdata.pl. Run it with a command line like:

This will print to the file every MIB entry with data in a format that the developers can use to emulate read operations without needing access to the device. Preference would be to mask any sensitive data in the output, zip the file, and upload as an attachment to the Sourceforge tracker. However, if you do not feel comfortable uploading the output to the tracker you could e-mail it to the developer that has claimed the ticket.

Contains a hash in the form ( method_name => SNMP MIB leaf name ) These are scalar values such as name, uptime, etc.

To resolve MIB leaf name conflicts between private MIBs, you may prefix the leaf name with the MIB replacing each - (dash) and : (colon) with an _ (underscore). For example, ALTEON_TIGON_SWITCH_MIB__agSoftwareVersion would be used as the hash value instead of the net-snmp notation ALTEON-TIGON-SWITCH-MIB::agSoftwareVersion.

When choosing the name for the methods, be aware that other new Sub Modules might inherit this one to get it's features. Try to choose a prefix for methods that will give it's own name space inside the SNMP::Info methods.

Contains a hash in the form ( method_name => SNMP MIB leaf name) These are table entries, such as the ifIndex

To resolve MIB leaf name conflicts between private MIBs, you may prefix the leaf name with the MIB replacing each - (dash) and : (colon) with an _ (underscore). For example, ALTEON_TS_PHYSICAL_MIB__agPortCurCfgPortName would be used as the hash value instead of the net-snmp notation ALTEON-TS-PHYSICAL-MIB::agPortCurCfgPortName.

A map between method calls (from %FUNCS or %GLOBALS) and subroutine methods. The subroutine called will be passed the data as it gets it from SNMP and it should return that same data in a more human friendly format.

Note: high speed interfaces (usually 1 Gbps or faster) have their link speed in ifHighSpeed. i_speed() automatically determines whether to use ifSpeed or ifHighSpeed; if the latter is used, the value is munged by munge_highspeed(). SNMP::Info can return speeds up to terabit levels this way.

Used to run an SNMP set command on several new values in the one request. Returns the result of $info->_set(method).

Pass either a reference to a 4 element array [<obj>, <iid>, <val>, <type>] or a reference to an array of 4 element arrays to specify multiple values.

<obj> - One of the following forms:
1) leaf identifier (e.g., C<'sysContact'>)
2) An entry in either %FUNCS, %GLOBALS (e.g., 'contact')
<iid> - The dotted-decimal, instance identifier. For scalar MIB objects
use '0'
<val> - The SNMP data value being set (e.g., 'netdisco')
<type> - Optional as the MIB should be loaded.

If one of the set assignments is invalid, then the request will be rejected without applying any of the new values - regardless of the order they appear in the list.

Raw data returned from Net-SNMP might not be formatted correctly or might have platform-specific bugs or mistakes. The MUNGE feature of SNMP::Info allows for fixups to take place.

Accepts the leaf and value (scalar, or hashref for a table) and returns the raw or the munged data, as appropriate. That is, you do not need to know whether MUNGE is installed, and it's safe to call this method regardless.

Overrides UNIVERSAL::can() so that objects will correctly report their capabilities to include dynamic methods generated at run time via AUTOLOAD.

Calls parent can() first to see if method exists, if not validates that a method should be created then dispatches to the appropriate internal method for creation. The newly created method is inserted into the symbol table returning to AUTOLOAD only for the initial method call.

Each entry in either %FUNCS, %GLOBALS, or MIB Leaf node names present in loaded MIBs are used by AUTOLOAD() to create dynamic methods. Generated methods are inserted into the symbol table so that subsequent calls can avoid AUTOLOAD() and dispatch directly.

Changes from SNMP::Info Version 0.7 and on are: Copyright (c) 2003-2010 Max Baker and SNMP::Info Developers All rights reserved.

Original Code is: Copyright (c) 2002-2003, Regents of the University of California All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* Neither the name of the University of California, Santa Cruz nor the
names of its contributors may be used to endorse or promote products
derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.