NAME
Cisco::Management - Interface for Cisco Management
SYNOPSIS
use Cisco::Management;DESCRIPTION
Cisco::Management is a class implementing several management functions for Cisco devices - mostly via SNMP. Cisco::Management uses the Net::SNMP module to do the SNMP calls.
METHODS
new() - create a new Cisco::Management object
my $cm = new Cisco::Management([OPTIONS]);or
my $cm = Cisco::Management->new([OPTIONS]);Create a new Cisco::Management object with OPTIONS as optional parameters. Valid options are:
Option Description Default
------ ----------- -------
-hostname Remote device to connect to localhost
-port Port to connect to 161
-community SNMP read/write community string private
-timeout Timeout to wait for request in seconds 10session() - return Net::SNMP session object
$session = $cm->session;Return the Net::SNMP session object created by the Cisco::Management new() method. This is useful to call Net::SNMP related methods without having to create a new Net::SNMP object. For example:
my $cm = new Cisco::Management(-host => 'router1',
-community => 'snmpRW'
);
my $session = $cm->session();
$session->get_request('1.3.6.1.2.1.1.4.0');In this case, the get_request call is a method provided by the Net::SNMP module that can be accessed directly via the $session object returned by the $cm->session() method.
close() - close session
$cm->close;Close the Cisco::Management session.
error() - print last error
printf "Error: %s\n", Net::Syslogd->error;Return last error.
Configuration Management Options
The following methods are for configuration file management.
config_copy() - configuration file management
my $cc = $cm->config_copy([OPTIONS]);Manage configuration files. Options allow for TFTP upload or download of running-config or startup-config and a copy running-config to startup-config or vice versa. Valid options are:
Option Description Default
------ ----------- -------
-tftp TFTP server address localhost
-source 'startup-config', 'running-config' 'running-config'
or filename on TFTP server
-dest 'startup-config', 'running-config' 'startup-config'
or filename for TFTP server
-catos Catalyst OS flag 0The default behavior with no options is copy running-config startup-config.
This method implements the CISCO-CONFIG-COPY-MIB for configuration file management. If these operations fail, the older method in OLD-CISCO-SYS-MIB is tried. All Catalyst OS operations are performed against the CISCO-STACK-MIB.
NOTE: Use care when performing TFTP upload to startup-config. This MUST be a FULL configuration file as the config file is NOT merged, but instead OVERWRITES the startup-config.
Allows the following methods to be called.
config_copy_starttime() - return config copy start time
$cc->config_copy_starttime();Return the start time of the configuration copy operation relative to system uptime.
config_copy_endtime() - return config copy end time
$cc->config_copy_endtime();Return the end time of the configuration copy operation relative to system uptime.
CPU Info
The following methods are for CPU utilization. These methods implement the CISCO-PROCESS-MIB and OLD-CISCO-SYS-MIB.
cpu_info() - return CPU utilization info
my $cpuinfo = $cm->cpu_info();Populate a data structure with CPU information. If successful, returns pointer to array containing CPU information.
$cpuinfo->[0]->{'Name', '5sec', '1min', ...}
$cpuinfo->[1]->{'Name', '5sec', '1min', ...}
...
$cpuinfo->[n]->{'Name', '5sec', '1min', ...}Interface Options
The following methods are for interface management. These methods implement the IF-MIB.
interface_getbyindex() - get interface name by ifIndex
my $line = $cm->interface_getbyindex([OPTIONS]);Resolve an ifIndex the full interface name. Called with one argument, interpreted as the interface ifIndex to resolve.
Option Description Default
------ ----------- -------
-index The ifIndex to resolve -REQUIRED-Returns the full interface name string.
interface_getbyname() - get interface name/ifIndex by string
my $name = $cm->interface_getbyname([OPTIONS]);Get the full interface name or ifIndex number by the Cisco 'shortcut' name. For example, 'gig0/1' or 's0/1' resolves to 'GigabitEthernet0/1' and 'Serial0/1' respectively. Called with one argument, interpreted as the interface string to resolve.
Option Description Default
------ ----------- -------
-interface String to resolve -REQUIRED-
-index Return ifIndex number instead (flag) 0Returns the full interface name string or ifIndex (if -index flag).
interface_info() - return interface info
my $ifs = $cm->interface_info();Populate a data structure with interface information including IP information if found. If successful, returns pointer to hash containing interface information.
Interface information consists of the following MIB entries (exludes counter-type interface metrics):
Index
Description
Type
MTU
Speed
Duplex *
PhysAddress
AdminStatus
OperStatus
LastChangeNOTE: Duplex is found in the EtherLike-MIB.
$ifs->{1}->{'Index', 'Description', ...}
$ifs->{2}->{'Index', 'Description', ...}
...
$ifs->{n}->{'Index', 'Description', ...}IP information can be accessed directly or with the following method.
interface_info_ip() - return IP info on current interface
my $ips = $ifs->{n}->interface_info_ip();Return a reference to an array containing the IP info for the current interface.
my $ifs = $cm->interface_info();
...
if (defined(my $ips = $ifs->{$_}->interface_info_ip())) {
$ips->[0]->{'IPAddress', 'IPMask'}
...
$ips->[n]->{'IPAddress', 'IPMask'}interface_updown() - admin up/down interface
my $line = $cm->interface_updown([OPTIONS]);Admin up or down the interface. With no arguments, all interfaces are made admin up.
Option Description Default
------ ----------- -------
-operation 'up' or 'down' 'up'
-interface ifIndex or range of ifIndex (, and -) (all)To specify individual interfaces, provide their number:
my $line = $cm->line_clear(2);Admin up ifIndex 2. To specify a range of interfaces, provide a range:
my $line = $cm->line_clear(
operation => 'down',
interfaces => '2-4,6,9-11'
);Admin down ifIndex 2 3 4 6 9 10 11.
Returns a pointer to an array containing the interfaces admin up/down if successful.
Line Options
The following methods are for line management. Lines on Cisco devices refer to console, auxillary and terminal lines for user interaction. These methods implement the OLD-CISCO-TS-MIB which is not available on some newer forms of IOS.
line_clear() - clear connection to line
my $line = $cm->line_clear([OPTIONS]);Clear the line (disconnect interactive session). With no arguments, all lines are cleared. To specify individual lines, provide their number:
my $line = $cm->line_clear(2);or
my $line = $cm->line_clear(lines => 2);Clear line 2. To specify a range of lines, provide a range:
my $line = $cm->line_clear('2-4,6,9-11');or
my $line = $cm->line_clear(range => '2-4,6,9-11');Clear lines 2 3 4 6 9 10 11.
Returns a pointer to an array containing the lines cleared if successful.
line_info() - return line info
my $line = $cm->line_info();Populate a data structure with line information including active sessions if found. If successful, returns pointer to hash containing line information.
$line->{0}->{'Number', 'TimeActive', ...}
$line->{1}->{'Number', 'TimeActive', ...}
...
$line->{n}->{'Number', 'TimeActive', ...}If the line is active, then session information is returned also. It can be accessed directly or with the following method.
line_info_sessions() - return session info on current line
my $session = $line->{n}->line_info_sessions();Return a reference to an array containing the session info for the current line. Should be called on active line as in the following.
my $line = $cm->line_info();
...
if ($line->{$_}->{'Active'} == 1) {
my $sessions = $line->{$_}->line_info_sessions()
$sessions->[0]->{'Session', 'Type', 'Dir' ...}
...
$sessions->[n]->{'Session', 'Type', 'Dir' ...}line_message() - send message to line
my $line = $cm->line_message([OPTIONS]);Send a message to the line. With no arguments, a "Test Message" is sent to all lines. If 1 argument is provided, it is interpreted as the message to send to all lines. Valid options are:
Option Description Default
------ ----------- -------
-lines Line or range of lines (, and -) (all)
-message Double-quote delimited string "Test Message"Returns a pointer to an array containing the lines messaged if successful.
line_numberof() - return number of lines
my $line = $cm->line_numberof();Returns the number of lines on the device.
Memory Info
The following methods are for memory utilization. These methods implement the CISCO-MEMORY-POOL-MIB.
memory_info() - return memory utilization info
my $meminfo = $cm->memory_info();Populate a data structure with memory information. If successful, returns pointer to array containing memory information.
$meminfo->[0]->{'Name', 'Used', 'Free', ...}
$meminfo->[1]->{'Name', 'Used', 'Free', ...}
...
$meminfo->[n]->{'Name', 'Used', 'Free', ...}Proxy Ping
The following methods are for proxy ping. These methods implement the CISCO-PING-MIB.
proxy_ping() - execute proxy ping
my $ping = $cm->proxy_ping([OPTIONS]);Send proxy ping from the object defined in $cm to the provided destination. Called with no options, sends the proxy ping to the localhost. Called with one argument, interpreted as the destination to ping. Valid options are:
Option Description Default
------ ----------- -------
-host Destination to send proxy ping to (localhost)
-count Number of pings to send 1
-size Size of the ping packets in bytes 64
-wait Time to wait for replies in seconds 1
-vrf VRF name to source pings from [none]Allows the following methods to be called.
proxy_ping_sent() - return number of pings sent
$ping->config_copy_sent();Return the number of pings sent in the current proxy ping execution.
proxy_ping_received() - return number of pings received
$ping->config_copy_received();Return the number of pings received in the current proxy ping execution.
proxy_ping_minimum() - return minimum round trip time
$ping->config_copy_minimum();Return the minimum round trip time in milliseconds of pings sent and received in the current proxy ping execution.
proxy_ping_average() - return average round trip time
$ping->config_copy_average();Return the average round trip time in milliseconds of pings sent and received in the current proxy ping execution.
proxy_ping_maximum() - return maximum round trip time
$ping->config_copy_maximum();Return the maximum round trip time in milliseconds of pings sent and received in the current proxy ping execution.
System Info
The following methods interface with the System MIB defined in SNMPv2-MIB.
system_info() - populate system info data structure.
my $sysinfo = $cm->system_info();Retrieve the system MIB information from the object defined in $cm.
Allows the following methods to be called.
system_info_description() - return system description
$sysinfo->system_info_description();Return the system description from the system info data structure.
system_info_objectID() - return system object ID
$sysinfo->system_info_objectID();Return the system object ID from the system info data structure.
system_info_uptime() - return system uptime
$sysinfo->system_info_uptime();Return the system uptime from the system info data structure.
system_info_contact() - return system contact
$sysinfo->system_info_contact();Return the system contact from the system info data structure.
system_info_name() - return system name
$sysinfo->system_info_name();Return the system name from the system info data structure.
system_info_location() - return system location
$sysinfo->system_info_location();Return the system location from the system info data structure.
system_info_services() - return system services
$sysinfo->system_info_services([1]);Return a pointer to an array containing the names of the system services from the system info data structure. For the raw number, use the optional boolean argument.
system_info_osversion() - return system OS version
$sysinfo->system_info_osversion();Return the system OS version as parsed from the sysDescr OID.
SUBROUTINES
Password subroutines are for decrypting and encrypting Cisco type 7 passwords. The algorithm is freely available on the Internet on several sites; thus, I can/will not take credit for it.
password_decrypt() - decrypt a Cisco type 7 password
my $passwd = Cisco::Password->password_decrypt('00071A150754');Where 00071A150754 is the encrypted Cisco password in this example.
password_encrypt() - encrypt a Cisco type 7 password
my $passwd = Cisco::Password->password_encrypt('cleartext'[,# | *]);
print "$_\n" for (@{$passwd});Where cleartext is the clear text string to encrypt. The second optional argument is a number in the range of 0 - 52 inclusive or random text.
This sub returns a pointer to an array. The array is constructed based on the second argument to password_encrypt.
Option Description Action
------ ----------- -------
No argument provided Return all 53 possible encryptions.
# Number 0-52 inclusive Return password encrypted with # index.
(other) Random text Return a random password.NOTE: Cisco routers by default only seem to use the first 16 indexes (0 - 15) to encrypt passwords. You notice this by looking at the first two characters of any type 7 encrypted password in a Cisco router configuration. However, testing on IOS 12.x and later show that manually entering a password encrypted with a higer index (generated from this script) to a Cisco configuration will not only be allowed, but will function normally for authentication. This may be a form of "security through obscurity" given that some older Cisco password decrypters don't use the entire translation index and limit 'valid' passwords to those starting with the fist 16 indexes (0 - 15). Using passwords with an encryption index of 16 - 52 inclusive may render older Cisco password decrypters useless.
Additionally, the Cisco router command prompt seems to be limited to 254 characters, making the largest password 250 characters (254 - 4 characters for the pas (followed by space) command to enter the password).
EXPORT
None by default.
EXAMPLES
Configuration File Management
This example connects to a device (router1) with SNMP read/write community (readwrite) and performs a configuration file upload via TFTP and if successful, a copy run start.
use strict;
use Cisco::Management;
my $cm = Cisco::Management->new(
hostname => 'router1',
community => 'readwrite'
);
if (defined(my $conf = $cm->config_copy(
-tftp => '10.10.10.1',
-source => 'foo.confg',
-dest => 'run'
))) {
printf "START: %s\n", $conf->config_copy_starttime();
printf "END : %s\n", $conf->config_copy_endtime();
# Only if above successful,
# Default action is "copy run start"
if (defined($conf = $cm->config_copy())) {
print "copy run start\n"
} else {
printf "Error: %s\n", Cisco::Management->error
}
} else {
printf "Error: %s\n", Cisco::Management->error
}
$cm->close();Cisco Password Decrypter
This example implements a simple Cisco password decrypter.
use Cisco::Management;
if (!defined($ARGV[0])) {
print "Usage: $0 encypted_password\n";
exit 1
}
if (my $passwd = Cisco::Management->password_decrypt($ARGV[0])) {
print "$passwd\n";
} else {
printf "Error - %s\n", Cisco::Management->error
}LICENSE
This software is released under the same terms as Perl itself. If you don't know what that means visit http://perl.com/.
AUTHOR
Copyright (C) Michael Vincent 2010
All rights reserved