From 5c0fe59627b7fed57ce963504d36c3e2cd609b4b Mon Sep 17 00:00:00 2001 From: Max Baker <> Date: Mon, 30 Dec 2002 21:32:08 +0000 Subject: [PATCH] Initial Import. Ver 0.1 --- README | 706 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 706 insertions(+) create mode 100644 README diff --git a/README b/README new file mode 100644 index 00000000..aa9c2aba --- /dev/null +++ b/README @@ -0,0 +1,706 @@ +NAME + + SNMP::Info - Perl5 Interface to Network devices through SNMP. + +VERSION + + SNMP::Info - Version 0.1 + +AUTHOR + + Max Baker ("max@warped.org") + + SNMP::Info was created for the Netdisco application at UCSC + +COPYRIGHT AND LICENCE + + Copyright (c) 2002, 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(); + + foreach my $iid (keys %$interfaces){ + + my $duplex = $i_duplex->{$iid}; + + # Print out physical port name, not snmp iid + my $port = $interfaces->{$iid}; + + print "$port : $duplex\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 + 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::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 + Foundry -> SNMP::Info::Foundry + Aironet -> SNMP::Info::Aironet + Elsif Layer2 (no Layer3) -> SNMP::Info::Layer2 + 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 + Bay Networks -> SNMP::Info::Layer2::Bay + 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 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'). + + 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. +