NAME

    SNMP::Info - Perl5 Interface to Network devices through SNMP.

VERSION

    SNMP::Info - Version 0.3

AUTHOR

    Max Baker ("max@warped.org")

    SNMP::Info was created for the Netdisco application at UCSC

COPYRIGHT AND LICENCE

    Copyright (c) 2002-3, 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.

SYNOPSIS

     # Connect with generic Info object
 
     my $info = new SNMP::Info( DestHost  => 'router' , 
                                 Community => 'public' );
 
     $name = $info->name();
 
     # Try and find a more specific subclass of SNMP::Info
     my $object_class = $info->device_type();
 
     my $more_specific_device = new $object_class(
                                      'Desthost' => 'mydevice',
                                      'Community' => 'public');
 
     # Find out the Duplex status for the ports
     my $interfaces = $more_specific_device->interfaces();
     my $i_duplex   = $more_specific_device->i_duplex();

     # Get CDP Neighbor info
     my $c_ip       = $more_specific_device->c_ip();
     my $c_port     = $more_specific_device->c_port();

     foreach my $iid (keys %$interfaces){
 
        my $duplex = $i_duplex->{$iid};
 
        # Print out physical port name, not snmp iid
        my $port  = $interfaces->{$iid};
 
        my $neighbor_ip   = $c_ip->{$iid};
        my $neighbor_port = $c_port->{$iid};

        print "$port: Duplex $duplex\n";
        print "       Neighbor : $neighbor_ip \@ $neighbor_port\n";

     }

REQUIREMENTS

    1. Net-SNMP
        To use this module, you must have Net-SNMP installed on your system.

        Net-SNMP can be found at http://net-snmp.sourceforge.net . Version
        5.0.2 or greater is recommended.

        The Perl module "SNMP" is found inside the distribution. Go to the
        perl/ directory and install it from there, or run "./configure
        --with-perl-modules" .

    2. MIBS
        Each sub-module that you use will also require specific MIBs,
        usually obtainable on the net. See the list above for a quick
        glance, and the documentation in each sub module for more
        information.

        Make sure that your snmp.conf is updated to point to your MIB
        directory and that the MIBs are world-readable.

        SNMP::Info requires RFC1213-MIB (and whatever supporting MIBs that
        are referenced).

        A good starting point are the Version 2 MIBs from Cisco, found at

         ftp://ftp.cisco.com/pub/mibs/v2/v2.tar.gz

        Run "cd /usr/local/share/snmp/mibs && tar xvfz ~/v2.tar.gz " to
        install them.

        Then run "snmpconf" and setup that directory as default. Move
        snmp.conf into /usr/local/share/snmp when you are done.

DESCRIPTION

    SNMP::Info gives an object oriented interface to information obtained
    through SNMP.

    This module is geared towards network devices. Speciality sub-classes
    exist for a number of vendors and products (see below).

  Design Goals

    1. Use of MIB variables and values instead of purely numeric OID
        All values are retrieved via MIB Leaf node names.

        This means that SNMP::Info only asks SNMP::Session to look for
        ``sysName'' instead of 1.3.6.1.2.1.1.5.

        It also means that you need to download MIB files for each sub
        module that you use.

        The other side effect to using MIBs is data results come back as
        meaningful text, instead of integers.

        Instead of looking up 1.3.6.1.2.1.2.2.1.3 and getting back "23"

        SNMP::Info will ask for "RFC1213-MIB::ifType" and will get back
        "ppp".

    2. SNMP::Info is easily extended to new devices
        You can create a new sub class for a device by filling in Four
        hashes %GLOBALS, %MIBS, %FUNCS, and %MUNGE with the names of the
        SNMP attributes that are specific to your device. See the bottom of
        this document for a sample Sub Class.

        When you make a new sub class for a device, please be sure to send
        it back to the developers at snmp@warped.org for inclusion in the
        next version.

Sub Classes

    SNMP::Info::Bridge
    SNMP::Info::CDP
    SNMP::Info::EtherLike
    SNMP::Info::MAU
    SNMP::Info::Layer1
    SNMP::Info::Layer2
    SNMP::Info::Layer3
    SNMP::Info::Layer1::Allied
    SNMP::Info::Layer1::Asante
    SNMP::Info::Layer2::Bay
    SNMP::Info::Layer2::C1900
    SNMP::Info::Layer2::C2900
    SNMP::Info::Layer2::Catalyst
    SNMP::Info::Layer2::HP
    SNMP::Info::Layer3::Aironet
    SNMP::Info::Layer3::Foundry
    SNMP::Info::Layer3::C3550
  Details

    * SNMP::Info::Bridge - BRIDGE-MIB - RFC1286 Support
        Requires BRIDGE-MIB

    * SNMP::Info::CDP - Cisco Discovery Protocol (CDP) Support.
        Provides Layer 2 Topology Information on Cisco and some HP Devices.

        Requires CISCO-CDP-MIB

    * SNMP::Info::EtherLike
        Requires ETHERLIKE-MIB - RFC1398

    * SNMP::Info::Layer1 - Generic Layer 1 Device Support
        Requires Standard V1 and V2 MIBs

    * SNMP::Info::Layer2 - Generic Layer 2 Device Support
        Inherits:

         SNMP::Info::CDP
         SNMP::Info::Bridge

        Required MIBs:

         CISCO-PRODUCTS-MIB - Gives model information for Cisco
         HP-ICF-OID         - Gives model information for HPs

    * SNMP::Info::Layer3 - Generic Layer 3 and Layer 2/3 Device Support
        Inherits:

         SNMP::Info::Bridge - For Layer 2/3 devices
         SNMP::Info::CDP
         SNMP::Info::EtherLike

        Required MIBs:

         CISCO-PRODUCTS-MIB - Gives model information for Cisco
         HP-ICF-OID         - Gives model information for HPs
         ENTITY-MIB         - Gives some chassis information
         OSPF-MIB           - Gives router information

    * SNMP::Info::MAU - RFC2668 - Media Access Unit (MAU) MAU-MIB
    * SNMP::Info::Layer1::Allied - Allied TeleSys Hub Support
        Requires ATI-MIB - Allied Devices MIB downloadable from
        http://www.allied-telesyn.com/allied/support/

    * SNMP::Info::Layer1::Asante - Asante 1012 Hubs
        Requires ASANTE-HUB1012-MIB - Download from http://www.mibdepot.com

    * SNMP::Info::Layer2::Bay - Bay Networks BayStack Switch Support
        Required MIBs:

         SYNOPTICS-ROOT-MIB  - Gives model information for Bay
         S5-ETH-MULTISEG-TOPOLOGY-MIB - Gives Layer 2 topology information for Bay

        Other supporting MIBs needed, see SNMP::Info::Bay for more info

    * SNMP::Info::Layer2::C1900 - Cisco 1900 and 1900c Device Support
        Requires STAND-ALONE-ETHERNET-SWITCH-MIB (ESSWITCH-MIB)

    * SNMP::Info::Layer2::C2900 - Cisco 2900 Series Device Support.
        Requires CISCO-C2900-MIB

    * SNMP::Info::Layer2::Catalyst - Cisco Catalyst WSC Series Switch
    Support
        Requires MIBs:

         CISCO-STACK-MIB
         CISCO-VTP-MIB

    * SNMP::Info::Layer2::HP - HP Procurve Switch Support
        Inherits:

         SNMP::Info::MAU

        Required MIBs:

         ENTITY-MIB
         RFC1271-MIB
         HP-ICF-OID

    * SNMP::Info::Layer3::Aironet - Cisco Aironet Wireless Access Points
    (AP) Support
        Required MIBs:

         AWCVX-MIB        - Aironet Specific MIB values
         IEEE802dot11-MIB - IEEE 802.11 Specific MIB (currently draft)

    * SNMP::Info::Layer3::C3550 - Cisco Catalyst 3550 Layer2/3 Switch
    * SNMP::Info::Layer3::Foundry - Older Foundry Networks Devices Support
        Inherits SNMP::Info::Bridge

        Requires FOUNDRY-SN-ROOT-MIB - Foundry specific values. See
        SNMP::Info::Layer3::Foundry for more information.

METHODS

        These are generic methods from RFC1213.  Some subset of these is 
    probably available for any network device that speaks SNMP.

  Constructor

    new()
        Creates a new object and connects via SNMP::Session.

        Arguments given are passed to SNMP::Session and can be used to
        overide defaults.

  Data is Cached

    A call to any of these methods will load the data once, and then return
    cached versions of that data.

    Use load_METHOD() to reload from the device

            $data = $cdp->c_ip();
            ...
            $cdp->load_c_ip();
            $newdata = $cdp->c_ip();

  Scalar Methods

    $info->device_type()
        Returns the SubClass name for this device. "SNMP::Info" is returned
        if no more specific class is available.

        First the device is checked for Layer 3 support and a specific
        subclass, then Layer 2 support and subclasses are checked for.

        This means that Layer 2 / 3 switches and routers will fall under the
        SNMP::Info::Layer3 subclasses.

        If the device still can be connected to via SNMP::Info, then
        SNMP::Info is returned.

        Algorithm for SubClass Detection:

                Layer3 Support                     -> SNMP::Info::Layer3
                    Aironet                        -> SNMP::Info::Layer3::Aironet
                    Catalyst 3550                  -> SNMP::Info::Layer3::C3550
                    Foundry                        -> SNMP::Info::Layer3::Foundry
                Elsif Layer2 (no Layer3)           -> SNMP::Info::Layer2 
                    Bay Networks                   -> SNMP::Info::Layer2::Bay
                    Catalyst 1900                  -> SNMP::Info::Layer2::C1900
                    Catalyst 2900XL (IOS)          -> SNMP::Info::Layer2::C2900
                    Catalyst WS-C (2926,5xxx,6xxx) -> SNMP::Info::Layer2::Catalyst
                    HP Procurve                    -> SNMP::Info::Layer2::HP
                Elsif Layer1 Support               -> SNMP::Info::Layer1
                    Allied                         -> SNMP::Info::Layer1::Allied
                    Asante                         -> SNMP::Info::Layer1::Asante
                Else                               -> SNMP::Info

    $info->has_layer(3)
        Returns non-zero if the device has the supplied layer in the OSI
        Model

        Returns "undef" if the device doesn't support the layers() call.

    $info->uptime()
        Uptime in hundreths of seconds since device became available.

        (sysUpTime)

    $info->contact()
        (sysContact)

    $info->name()
        (sysName)

    $info->location()
        (sysLocation)

    $info->layers()
        This returns a binary encoded string where each digit represents a
        layer of the OSI model served by the device.

            eg: 01000010  means layers 2 (physical) and 7 (Application) 
                          are served.

        Note: This string is 8 digits long.

        (sysServices)

    $info->ports()
        Number of interfaces available on this device.

        (ifNumber)

  Table Methods

    Each of these methods returns a hash_reference to a hash keyed on the
    interface index in SNMP.

     Example : $cdp->c_ip() returns 
                { '304' => '123.123.231.12' }

   Interfaces

    $info->interfaces()
        This methods is overriden in each subclass to provide a mapping
        between the Interface Table Index (iid) and the physical port name.

    $info->if_ignore()
        Returns a reference to a hash where key values that exist are
        interfaces to ignore.

        Ignored interfaces are ones that are usually not Physical ports or
        Virtual Lans (VLANs) such as the Loopback interface, or the CPU
        interface.

        SNMP::Info and it's subclasses tries to provide data on Physical
        ports.

    $info->i_index()
        Defaults to $info->interfaces()

        (ifIndex)

    $info->i_description()
        Returns reference to hash keyed by iid. Values are the Textual
        Description of the interface (port). Usually the physical /
        human-friendly name.

        (ifDescr)

    $info->i_type()
        Returns reference to hash keyed by iid. Values are the port type,
        such as Vlan, 10baseT, Ethernet, Serial...

        (ifType)

    $info->i_mtu()
        Returns reference to hash keyed by iid. Values are the MTU value for
        the port.

        (ifMtu)

    $info->i_speed()
        Returns reference to hash keyed by iid. Values are the speed of the
        link.

        (ifSpeed)

    $info->i_mac()
        Returns reference to hash keyed by iid. Values are the MAC address
        of the interface. Note this is just the MAC of the port, not
        anything connected to it.

        (ifPhysAddress)

    $info->i_up()
        Returns reference to hash keyed by iid. Values are the Link Status
        of the interface. Typical values are 'up' and 'down'.

        (ifOperStatus)

    $info->i_up_admin()
        Returns reference to hash keyed by iid. Values are the
        administrative status of the port. Typical values are 'enabled' and
        'disabled'.

        (ifAdminStatus)

    $info->i_name()
        Returns reference to hash keyed by iid. Values are the Interface
        Name field. Supported by a smaller subset of devices, this fields is
        often human set.

        (ifName)

    $info->i_alias()
        Returns reference to hash keyed by iid. Values are a differnent
        version of the Interface Description or Interface Name. For certain
        devices this is a more human friendly form of i_description() . For
        others it is a human set field like i_name().

        (ifAlias)

   IP Address Table

    Each entry in this table is an IP address in use on this device. Usually
    this is implemented in Layer3 Devices.

    $info->ip_index()
        Maps the IP Table to the IID

        (ipAdEntIfIndex)

    $info->ip_table()
        Maps the Table to the IP address

        (ipAdEntAddr)

    $info->ip_netmask()
        Gives netmask setting for IP table entry.

        (ipAdEntNetMask)

    $info->ip_broadcast()
        Gives broadcast address for IP table entry.

        (ipAdEntBcastAddr)

  Default %MUNGE

     ip     -> &munge_ip 

     mac    -> &munge_mac 

     i_mac  -> &munge_mac 

     layers -> &munge_dec2bin

CREATING SUBCLASSES

  Data Structures Used in SNMP::Info and SubClasses

    A class inheriting this class must implement these data structures :

    $INIT
        Used to flag if the MIBs have been loaded yet.

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

        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.

    %FUNCS
        Contains a hash in the form ( method_name => SNMP iid) These are
        table entries, such as the IfIndex

    %MIBS
        A list of each mib needed.

        ('MIB-NAME' => 'itemToTestForPresence')

        The value for each entry should be a MIB object to check for to make
        sure that the MIB is present and has loaded correctly.

        $info->init() will throw an exception if a MIB does not load.

    %MUNGE
        A map between method calls (from %FUNCS or %GLOBALS) and sub routine
        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.

  Sample Sub Class

    Let's make a sample Layer 2 Device subclass :

     # SNMP::Info::Layer2::Sample

     package SNMP::Info::Layer2::Sample;

     $VERSION = 0.1;

     use strict;

     use Exporter;
     use SNMP::Info::Layer2;

     @SNMP::Info::Layer2::Sample::ISA = qw/SNMP::Info::Layer2 Exporter/;
     @SNMP::Info::Layer2::Sample::EXPORT_OK = qw//;

     use vars qw/$VERSION %FUNCS %GLOBALS %MIBS %MUNGE $AUTOLOAD $INIT $DEBUG/;

     %MIBS    = (%SNMP::Info::Layer2::MIBS,
                 'SUPER-DOOPER-MIB'  => 'supermibobject'
                );

     %GLOBALS = (%SNMP::Info::Layer2::GLOBALS,
                 'name'              => 'supermib_supername',
                 'favorite_color'    => 'supermib_fav_color_object',
                 'favorite_movie'    => 'supermib_fav_movie_val'
                 );

     %FUNCS   = (%SNMP::Info::Layer2::FUNCS,
                 # Super Dooper MIB - Super Hero Table
                 'super_hero_index'  => 'SuperHeroIfIndex',
                 'super_hero_name'   => 'SuperHeroIfName',
                 'super_hero_powers' => 'SuperHeroIfPowers'
                );

     %MUNGE   = (%SNMP::Info::Layer2::MUNGE,
                 'super_hero_powers' => \&munge_powers
                );

     # OverRide uptime() method from %SNMP::Info::GLOBALS
     sub uptime {
         my $sample = shift;

         my $name   = $sample->name();

         # this is silly but you get the idea
         return '600' if defined $name ; 
     }

     # Create our own munge function
     sub munge_powers {
         my $power = shift;

         # Take the returned obscure value and return something useful.
         return 'Fire' if $power =~ /reallyhot/i;
         return 'Ice'  if $power =~ /reallycold/i;
     
         # Else 
         return $power;
     }

     # Add Copious Documentation here!!!

    Be sure and send the debugged version to snmp@warped.org to be included
    in the next version of SNMP::Info.

  Data Munging Callback Subs

    munge_speed()
        Makes human friendly speed ratings using %SPEED_MAP

         %SPEED_MAP = (
                        '64000'      => '64 kbps',
                        '1500000'    => '1.5 Mbps',
                        '1544000'    => 'T1',
                        '2000000'    => '2.0 Mbps',
                        '2048000'    => '2.048 Mbps',
                        '4000000'    => '4.0 Mbps',
                        '10000000'   => '10 Mbps',
                        '11000000'   => '11 Mbps',
                        '20000000'   => '20 Mbps',
                        '16000000'   => '16 Mbps',
                        '45000000'   => 'DS3',
                        '45045000'   => 'DS3',
                        '64000000'   => '64 Mbps',
                        '100000000'  => '100 Mbps',
                        '149760000'  => 'OC-1'
                        '155000000'  => 'OC-1'
                        '400000000'  => '400 Mbps',
                        '622000000'  => 'OC-12',
                        '599040000'  => 'OC-12', 
                        '1000000000' => '1.0 Gbps',
                     );

    munge_ip()
        Takes a binary IP and makes it dotted ASCII

    munge_mac()
        Takes an octet stream (HEX-STRING) and returns a colon separated
        ASCII hex string.

    munge_octet2hex()
        Takes a binary octet stream and returns an ASCII hex string

    munge_dec2bin()
        Takes a binary char and returns its ASCII binary representation

    munge_bits
        Takes a SNMP2 'BITS' field and returns the ASCII bit string

  Internaly Used Functions

    $info->init()
        Used internally. Loads all entries in %MIBS.

    $info->debug(1)
        Turns on debugging info for this class and SNMP

    $info->class()
        Returns the class name of the object.

    $info->funcs()
        Returns a reference to the %FUNCS hash.

    $info->mibs()
        Returns a reference to the %MIBS hash.

    $info->globals()
        Returns a reference to the %GLOBALS hash.

    $info->munge()
        Returns a reference ot the %MUNGE hash.

    $info->session()
        Gets or Sets the SNMP::Session object.

   Functions for SNMP Scalars (%GLOBALS)

    $info->_global()
        Used internally by AUTOLOAD to load dynmaic methods from %GLOBALS.

        Example: $info->name() calls autoload which calls
        $info->_global('name').

    $info->_set(attr,val,iid)
        Used internally by AUTOLOAD to run an SNMP set command for dynamic
        methods listed in either %GLOBALS or %FUNCS.

        Example: $info->set_name('dog',3) uses autoload to resolve to
        $info->_set('name','dog',3);

   Functions for SNMP Tables (%FUNCS)

    $info->load_all()
        Runs $info->load_METHOD() for each entry in %FUNCS.

        Returns { iid => values_hash } where value_hash is in the format: {
        attribute => value }

    $info->all()
        Runs $info->load_all() once then returns the cached data.

        Use $info->load_all() to reload the data.

    $info->_load_attr()
        Used internally by AUTOLOAD to fetch data called from methods listed
        in %FUNCS.

        Called from $info->load_METHOD();

    $info->_show_attr()
        Used internaly by AUTOLOAD to return data called by methods listed
        in %FUNCS.

        Called like $info->METHOD().

        The first time ran, it will call $info->load_METHOD(). Every time
        after it will return cached data.

  AUTOLOAD

    Each entry in either %FUNCS or %GLOBALS is used by AUTOLOAD() to create
    dynamic methods.

    First Autoload sees if the method name is listed in either of the two
    hashes.

    If the method exists in globals, it runs $info->_global(method).

    Next it will check %FUNCS, run $info->_load_attr(method) if needed and
    return $info->_show_attr(method).

    Override any dynamic method listed in one of these hashes by creating a
    sub with the same name.

    Example : Override $info->name() by creating `` sub name {}'' in your
    Module.