Cisco::Accounting - Cisco and IPCAD ip accounting parser and aggregator
version 1.01
use Cisco::Accounting; use Data::Dumper; ## make a new Cisco::Accounting object eval { $acct = Cisco::Accounting->new(%data); }; ## get list of interfaces on remote host ## enable ip accounting on interfaces 1 and 2 (indexes are found with get_interfaces()) ## disable ip accounting on interface 2 eval { @interfaces = $acct->get_interfaces(); print &Dumper(\@interfaces); $acct->enable_accounting(2,1); #$acct->disable_accounting(2); }; ## fetch ip accounting from a remote device and clear ip accounting afterwards eval { $acct->do_accounting(); $acct->clear_accounting(); }; ## get the aggregated output, the overall statistics and the historical summarized data $output = $acct->get_output(); $stats = $acct->get_statistics(); $historical = $acct->get_history(); print &Dumper($stats); print &Dumper($output); print &Dumper($historical);
The Cisco::Accounting module parses and aggregates the output of 'show ip accounting' data on Cisco routers and also on hosts running IPCAD.
Every time the 'show ip accounting' output is parsed for a specific host the information is being aggregated and stored in a hash. General statistics and historical summarized data is also being stored.
The module connects to a remote device and retrieves a complete list of interfaces on that device. It is possible to automatically enable or disable IP Accounting on one or more interfaces at once using Cisco::Accounting.
Use this module if you quickly want to fetch IP accounting information for a short period or if you want to report IP Accounting data for a long period.
CIPAT is a front-end application for Cisco::Accounting that also has reporting features. CIPAT is available on http://www.sourceforge.net/projects/cipat
More information about IPCAD can be found at http://lionet.info/ipcad
This is the constructor.
my $acct = new Cisco::Accounting( 'host' => $host, [required] 'user' => $user, [optional] 'pwd' => $password, [optional] 'tacacs' => $tacacs, [optional] 'enable_user' => $enable_user, [optional] 'enable_pwd' => $enable_pwd, [optional] 'persistent' => 0 | 1, [default = 1] 'acct_type' => cisco | ipcad, [default = cisco] 'keep_history' => Ø | 1, [default = 1] 'lastpoll_details' => 0 | 1, [default = 0] 'telnet_options' => { Net::Telnet options } );
This creates a new Cisco::Accounting object.
Parameters :
host router or host that we need to connect to (via telnet only) user default username (if required) pwd default password (if required) tacacs tacacs password (if required) enable_user enable username (if required - for routers only) enable_pwd enable password (if required - for routers only) persistent if enabled then try to keep the telnet session open until close() is called if disabled then connection is closed after each 'transaction' acct_type either 'cisco' or 'ipcad' depending if host is a Cisco router or host with IPCAD keep_history if enabled then we keep a summarized history of each time 'show ip accounting' was parsed if disabled no history info is kept, to save memory if we're polling for a long period lastpoll_details if enabled then we also keep the detailed, non-summarized, data of the last poll. can be useful if you're polling many times and want to have the summarized data in the end but also the details for each separate poll telnet_options add additional default Net::Telnet options to this hash
Clears the IP accounting table on a Cisco router or IPCAD host. This sends 'clear ip accounting' to the host. For IPCAD hosts : make sure that you have sufficient rights to do this, by default this is not enabled for normal user accounts.
$acct->clear_accounting()
This clears the statistcs that were gathered so far. This has the same effect as closing the object and creating a new one except that we don't have to close the telnet session.
$acct->clear_output();
Disable IP accounting on one or more interfaces. This can only be done on Cisco routers, not on IPCAD hosts. It has the same effect as configuring 'no ip accounting output-packets' on a router interface.
You need to be able to go to config mode on the router !
$acct->disable_accounting(1,3,6);
@interfaces An array of interface indices, the index can be retrieved with get_interfaces()
This actually retrieves the IP accounting data from a Cisco router or IPCAD host. The data is being parsed and aggregated in the output buffer. This procedure can be called as many times as you want during the lifetime of the Cisco::Accounting object, each time it's called the new data will be aggregated with the old data.
$rc = $acct->do_accounting();
Return value :
$rc this is a reference to the output buffer, same result as get_output()
Enable IP accounting on one or more interfaces. This can only be done on Cisco routers, not on IPCAD hosts. It has the same effect as configuring 'ip accounting output-packets' on a router interface.
$acct->enable_accounting(1,3,6)
Returns a reference to a hash of summarized historical information. For each time that we've polled the IP accounting data using do_accounting() an entry is stored with the timestamp of that poll and the total bytes, packets, host pairs during that poll. If for example you would call do_accounting() every 5 minutes for one hour then the hash would contain 12 elements.
$history = $acct->get_history();
$history Reference to hash that contains 'timestamp' => { 'totalBytes' => '', 'totalPackets' => '', 'hostPairs' => '', }
Get a list of all interfaces of the Cisco router or IPCAD device and the status if IP accounting is already enabled or not. The list contains references to Cisco::Accounting::Interface objects.
@interfaces = $acct->get_interfaces()
Return value =
@interfaces array of Cisco::Accounting::Interface objects, one object for each interface found The Interface object contains the unique id, used in enable_accounting() and disable_accounting() as well as the name (ex. FastEthernet0/0) and if IP accounting is already enabled or not. See perldoc of Cisco::Accounting::Interface for more information
Returns a hash containing the detailed, not aggregated, data of the very last poll. This contains only data if the Cisco::Accounting was created with the 'lastpoll_data => 1' option.
This output can be useful if you're polling many times and you are interested in the summarized data of all polls but you also want to know the details of each separate poll.
$output = $acct->get_lastpoll_output();
$output Reference to hash with all the aggregated information. The hash contains for each unique source-destination host pair the following values :
'source' => source ip address 'destination' => destination ip address 'lastPollBytes' => number of bytes for this pair seen during last do_accounting() 'lastPollPackets' => number of packets for this pair seen during last do_accounting() 'totalBytes' => total number of bytes seen for this pair every time do_accounting() was called 'totalPakcets' => total number of packets seen for this pair every time do_accounting() was called 'polls' => number of times this pair was seen every time do_accounting() was called ex. if we've 'polled' twice and only once this pair was seen then the value = 1
Returns a reference to the hash containing all aggregated information.
$output = $acct->get_output();
Returns a reference to a hash of some general statistics.
$stats = $acct->get_statistics()
$stats Reference to hash containing some general statistics :
starttime timestamp of the first time do_accounting() was called lastpolltime timestamp of the last time do_accounting() was called totalpolls number of times do_accounting() was called totalbytes total number of bytes seen for every time do_accounting() was called totalpackets total number of packets seen for every time do_accounting() was called totalpolledlines total number of lines that was parsed and aggregated totalskippedlines total number of lines that were skipped (headers etc.) uniquehostpairs total number of unique host pairs that were seen
If you have a persistent connection but you're only calling do_accounting() every 5 minutes for example then you might receive a connection timeout. This can be solved by sending a keepalive every 30 seconds for example. The keepalive just sends a newline character to the remote host avoiding a connection timeout.
$acct->keepalive()
At the moment only telnet connections are supported, not SSH.
All Cisco routers and switches that support 'IP Accounting'. Make sure that you have enable permissions and in configure permissions in case you're enabling or disabling IP Accounting on interfaces.
All hosts (usually Unix hosts) that are running the IPCAD daemon with default settings. Make sure that the username has sufficient permissions on the host.
Some working examples can be found in the test folder of the source code.
Also you can check out 'CIPAT' on SourceForge. This is a front-end to Cisco::Accounting and allows you to easily enter the required parameters using a small wizard and to generate reports in different formats.
CONNECT TO CISCO ROUTER AND PARSE IP ACCOUNTING 5 TIMES
use Cisco::Accounting; use Data::Dumper; my %data = ( 'host' => "foo", 'user' => "user", 'pwd' => "pass", 'enable_user' => "user", 'enable_pwd' => "enable_pass", ); my $acct; my @interfaces; my $output; my $stats; my $historical; my $count = 5; my $i = 0; my $interval = 10; ## initialize : make a new object, get the interfaces and enable ip accounting on 2 interfaces eval { $acct = Cisco::Accounting->new(%data); @interfaces = $acct->get_interfaces(); $acct->enable_accounting(2,1); }; die ($@) if ($@); ## start polling, 5 times with interval of 60 seconds while ($i < $count) { ## parse IP accounnting info and clear the accounting after each 'poll' eval { print "getting accounting information"; $acct->do_accounting(); print " ... OK\n"; $acct->clear_accounting(); }; if ($@) { warn $@; } $i++; sleep $interval if ($i < $count); } $output = $acct->get_output(); $stats = $acct->get_statistics(); $historical = $acct->get_history(); # print output print &Dumper(\@interfaces); print &Dumper($output); print &Dumper($stats); print &Dumper($historical);
Only telnet connections are supported, not SSH. Slow telnet connections may timeout, possibly this needs to be finetuned.
IPCAD is supported but has been tested ONLY with default configuration. It's possible to configure IPCAD to do its own aggregation etc. but Cisco::Accounting is not configured for this.
We assume that ALL interfaces have accounting enabled on IPCAD hosts, although it's possible to configure this otherwise in the IPCAD config files.
Also make sure that your user has permissions for IPCAD to clear the statistics! If this doesn't work then check your IPCAD configuration.
This package makes configuration changes on Cisco routers (enabling and removing 'ip accounting' + clearing ip accounting statistics). Use at your own risk !
The Cisco::Accounting package was in the first place intended for Cisco devices, although IPCAD seems to be working fine as well this has not been fully tested.
Maarten Wallraf, <perl at 2nms.com>
<perl at 2nms.com>
1 POD Error
The following errors were encountered while parsing the POD:
Non-ASCII character seen before =encoding in 'Ø'. Assuming UTF-8
To install Cisco::Accounting, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Cisco::Accounting
CPAN shell
perl -MCPAN -e shell install Cisco::Accounting
For more information on module installation, please visit the detailed CPAN module installation guide.