NAME

Router::Statistics - Router Statistics and Information Collection

VERSION

Version 0.97_3

SYNOPSIS

Router Statistics and Information Colleciton. Currently this covers a multitude of areas from different types of routers and in a future release this will change. There are some 'action' functions within this module which do need moving to another module so no complaining too much, please.

The following examples shows how to setup the module to retrieve interface statistics from routers that support the standard IFMIB. All the work about OIDs etc is taken care of by the module so you are left with a hash tree, rooted by the router IPs information was received for.

    use Router::Statistics;
    use strict;

    my ( $result, $statistics );
    my ( %routers, %interfaces );

    $statistics = new Router::Statistics();

    $result = $statistics->Router_Add( "10.1.1.1" , "public" );
    $result = $statistics->Router_Ready_Blocking( "10.1.1.1" );
    ....
    $result = $statistics->Router_Add( "10.1.1.200" , "public" );
    $result = $statistics->Router_Ready_Blocking( "10.1.1.200" );

    $result = $statistics->Router_Test_Connection_Blocking(\%routers);

    if ( !%routers )
        { print "No access to Any of the Routers specified.\n";exit(0); }

    $result = $statistics->Router_get_interfaces_Blocking( \%interfaces );

    foreach my $router ( keys %interfaces )
	{
	print "Router IP is '$router'\n";
	print "Router Hostname is '$routers{$router}{'hostName'}'\n";
	foreach my $interface ( keys %{$interfaces{$router}} )
		{
		print "Interface ID '$interface'\n";
		print "Interface Description '$interfaces{$ubr}{$interface}{'ifDescr'}'\n";
		print "Interface ifType '$interfaces{$ubr}{$interface}{'ifType'}'\n";
		print "Interface ifMtu  '$interfaces{$ubr}{$interface}{'ifMtu'}'\n";
		print "Interface ifSpeed '$interfaces{$ubr}{$interface}{'ifSpeed'}'\n";
		print "Interface ifPhysAddress '$interfaces{$ubr}{$interface}{'ifPhysAddress'}'\n";
		print "Interface ifOperStatus '$interfaces{$ubr}{$interface}{'ifOperStatus'}'\n";
		print "Interface ifInOctets '$interfaces{$ubr}{$interface}{'ifInOctets'}'\n";
		print "Interface ifInUcastPkts '$interfaces{$ubr}{$interface}{'ifInUcastPkts'}'\n";
		print "Interface ifInNUcastPkts '$interfaces{$ubr}{$interface}{'ifInNUcastPkts'}'\n";
		print "Interface ifInDiscards '$interfaces{$ubr}{$interface}{'ifInDiscards'}'\n";
		print "Interface ifInErrors '$interfaces{$ubr}{$interface}{'ifInErrors'}'\n";
		print "Interface ifInUnknownProtos '$interfaces{$ubr}{$interface}{'ifInUnknownProtos'}'\n";
		print "Interface ifOutOctets '$interfaces{$ubr}{$interface}{'ifOutOctets'}'\n";
		print "Interface ifOutUcastPkts '$interfaces{$ubr}{$interface}{'ifOutUcastPkts'}'\n";
		print "Interface ifOutNUcastPkts '$interfaces{$ubr}{$interface}{'ifOutNUcastPkts'}'\n";
		print "Interface ifOutDiscards '$interfaces{$ubr}{$interface}{'ifOutDiscards'}'\n";
		print "Interface ifOutErrors '$interfaces{$ubr}{$interface}{'ifOutErrors'}'\n";
		print "\n";
		}
       }

I am currently in need of access to alternative vendor routers, ie. anyone but Cisco ( ABC ) as I only have real access to Cisco equipment so this code can not be confirmed 100% against anyone else.

I would also like to expand the library to cover other actions , rather than just DOCSIS functions, which is the primary action focus at the moment.

FUNCTIONS

Router_Add

This function adds a Router IP, Community String and Timeout to the internal list of usable routers. It does not initialise any SNMP functionality at this stage. If no timeout is specified 2 seconds is the default.

Router_Add ( "<ip>", "<community>", <timeout> );

Example of Use

my $result = $test->Router_Add( "10.1.1.1" , "public" );

is the same as this

my $result = $test->Router_Add( "10.1.1.1" , "public" , 2 );

Router_Remove

The function remotes a Router IP from the internal list of usable router. If there is an open SNMP session, it is closed.

Example of Use

my $result = $test->Router_Remove ( "10.1.1.1" );

Router_Ready

Router_Return_All

Router_Ready_Blocking

Router_get_networks

Router_get_interfaces

Router_get_interfaces_Blocking

Router_Test_Connection

Router_Test_Connection_Blocking

CPE_Add

CPE_Remove

CPE_Ready

CPE_Return_All

CPE_export_import_fields

CPE_export_fields

CPE_export_schema

CPE_export_data_start

CPE_export_data_end

CPE_export_data

CPE_gather_all_data_walk

CPE_gather_all_data

get_CPE_info_dead ** DO NOT USE IS NOT COMPLETE

CPE_Test_Connection

Export_UBR_Slot_Inventory

Export_UBR_Port_Inventory

UBR_get_DOCSIS_upstream_interfaces

UBR_get_DOCSIS_upstream_interfaces_Blocking

UBR_get_DOCSIS_interface_information

UBR_get_DOCSIS_interface_information_Blocking

UBR_get_DOCSIS_downstream_interfaces

UBR_get_DOCSIS_downstream_interfaces_Blocking

UBR_get_CPE_information

UBR_get_CPE_information_Blocking

UBR_modify_cpe_DOCSIS_profile

UBR_reset_cpe_device

UBR_get_active_cpe_profiles

UBR_get_active_cpe_profiles_Blocking

UBR_get_active_upstream_profiles

UBR_get_active_upstream_profiles_Blocking

UBR_get_stm

The use of the STM functions come with a MASSIVE warning, that due to bugs in Cisco IOS your UBR ( Cable router ) will drop all currently connected devices if you poll it OUTSIDE of the configured STM time scope. This is a known defect so you HAVE BEEN WARNED. There are a couple of possible workarounds however none have been confirmed.

Use of the Non Blocking function should be done with care and the UBR_get_stm_Blocking is preferred.

Example of Use

use Router::Statistics;
use strict;

my $test= new Router::Statistics;
my %stm_information;
my $result = $test->Router_Add( "10.1.1.1" , "public" );
$result = $test->Router_Ready ( "10.1.1.1" );
$result = $test->UBR_get_stm( \%stm_information );

The %stm_information hash contains a tree rooted by the IP address of the routers Added initially and the STM information as follows

Router IP
     -- STM Instance Number
        --  ccqmEnfRuleViolateID ( never seems to be populated )
        --  ccqmEnfRuleViolateMacAddr  - MAC address of the device
        --  ccqmEnfRuleViolateRuleName - Name of the STM rule specified
        --  ccqmEnfRuleViolateByteCount - The Cisco specification is wrong
        --  ccqmEnfRuleViolateLastDetectTime - The time the violation occured
        --  ccqmEnfRuleViolatePenaltyExpTime - The time the violation finishes

It should be noted that due to another bug not all entries for STM violations end up in the STM MIB. This appears to be caused by the end time of the STM configuration, if a devices expiry time is after the end of the STM window, it does not go into the MIB.

UBR_get_stm_Blocking

The use of the STM functions come with a MASSIVE warning, that due to bugs in Cisco IOS your UBR ( Cable router ) will drop all currently connected devices if you poll it OUTSIDE of the configured STM time scope. This is a known defect so you HAVE BEEN WARNED. There are a couple of possible workarounds however none have been confirmed.

Example of Use

use Router::Statistics;
use strict;

my $test= new Router::Statistics;
my (%stm_inventory, %stm_telnet_inventory , %routers);
my $result = $test->Router_Add( "10.1.1.1" , "public" );
$result = $test->Router_Ready_Blocking ( "10.1.1.1" );
$result = $test->Router_Test_Connection_Blocking(\%routers);
$result = $test->UBR_get_stm_Blocking( 
    \%router,
    \%stm_information,
    \%stm_telnet_inventory,
    "telnetlogin",
    "telnetpassword" );

The %stm_information and %stm_telnet_inventory hashes contains a tree rooted by the IP address of the routers Added initially and the STM information as follows

Router IP
    -- STM Instance Number
       --  ccqmEnfRuleViolateID ( never seems to be populated )
       --  ccqmEnfRuleViolateMacAddr  - MAC address of the device
       --  ccqmEnfRuleViolateRuleName - Name of the STM rule specified
       --  ccqmEnfRuleViolateByteCount - The Cisco specification is wrong
       --  ccqmEnfRuleViolateLastDetectTime - The time the violation occured
       --  ccqmEnfRuleViolatePenaltyExpTime - The time the violation finishes

It should be noted that due to another bug not all entries for STM violations end up in the STM MIB. This appears to be caused by the end time of the STM configuration, if a devices expiry time is after the end of the STM window, it does not go into the MIB.

BUGS

It is has been discovered using Non blocking functions on Cisco routers does not always return the same consistent information compared to Blocking. It is the opinion of the author to only use Blocking unless you know what you are doing, and all functions will have Blocking mirrors in the first public release.

Module now semi supports blocking and non blocking mode. It has been discovered that non-blocking is significantly longer to execute. Not entirely sure why, however to speed things up some functions now have _Blocking mirrors so they can be called instead.

Added support to retrieve the STM information very simple implementation to poll the STM mib provided on Cisco equipment.

Added Network Link Map Generator Added CPE snmp read key cycler ( not finished ).

Please report any bugs or feature requests to bug-router-statistics at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Router-Statistics. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Router::Statistics

ACKNOWLEDGEMENTS

Cisco I suppose for making their products such a nightmare to manage using SNMP.

COPYRIGHT & LICENSE

Copyright 2006 Andrew S. Kennedy, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.