The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Cisco-Management-0.09
River stage zero No dependents
++
/ Cisco::Management

NAME

Cisco::Management - Interface for Cisco Management

SYNOPSIS

  use Cisco::Management;

DESCRIPTION

This module is deprecated - please use Cisco::SNMP.

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.

CAVEATS

This module is deprecated - please use Cisco::SNMP.

As of version 0.06, Cisco::Management supports IPv6 on systems with IPv6 configured but requires Socket version 1.94 or greater. This may cause issues on Perl versions less than 5.14, where the default Socket module is of a lesser version. The requirement stems from the use of the getaddrinfo() and getnameinfo() functions not available on older versions of Socket.

METHODS

new() - create a new Cisco::Management object

  my $cm = Cisco::Management->new([OPTIONS]);

Create a new Cisco::Management object with OPTIONS as optional parameters. Valid options are:

  Option     Description                            Default
  ------     -----------                            -------
  -community SNMP read/write community string       private
  -family    Address family IPv4/IPv6               IPv4
               Valid values for IPv4:
                 4, v4, ip4, ipv4, AF_INET (constant)
               Valid values for IPv6:
                 6, v6, ip6, ipv6, AF_INET6 (constant)
  -hostname  Remote device to connect to            localhost
  -port      Port to connect to                     161
  -timeout   Timeout to wait for request in seconds 10
  -version   SNMP version to use                    1
  [Additional options available from Net::SNMP module]

Family provides hint for resolving names provided for hostname to addresses.

session() - 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 methods directly without having to create a new Net::SNMP object. For example:

  my $cm = Cisco::Management->new(
      -host      => 'router1',
      -community => 'snmpRW'
  );
  my $session = $cm->session();
  # get_request() is a Net::SNMP method
  $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", Cisco::Management->error;

Return last error.

Configuration Management Options

The following methods are for configuration file management. These methods implement 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.

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
  ------     -----------                            -------
  -catos     Catalyst OS boolean flag.  Enable if   0
             device runs Catalyst OS.
  -dest      'startup-config', 'running-config'     'startup-config'
             or filename for TFTP server
  -family    Address family IPv4/IPv6               [Inherit from new()]
               Valid values for IPv4:
                 4, v4, ip4, ipv4, AF_INET (constant)
               Valid values for IPv6:
                 6, v6, ip6, ipv6, AF_INET6 (constant)
  -source    'startup-config', 'running-config'     'running-config'
             or filename on TFTP server
  -tftp      TFTP server address                    localhost
  -timeout   Seconds until timeout for completion   10
             check

The default behavior with no options is copy running-config startup-config.

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.

A hostname value for tftp will be resolved to IPv4/v6 based on family. Family is inherited from the value set in new() but can be overriden. Providing a numeric address will also self-determine the IPv4/v6 address.

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 an 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 to 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
  ------     -----------                            -------
  -index     Return ifIndex instead (boolean)       0
  -interface String to resolve                      -REQUIRED-

Returns a string with the full interface name or ifIndex - if -index boolean flag is set.

interface_info() - return interface info

  my $ifs = $cm->interface_info([OPTIONS]);

Populate a data structure with interface information. Called with no arguments, populates data structure for all interfaces. Called with one argument, interpreted as the interface(s) to retrieve information for.

  Option     Description                            Default
  ------     -----------                            -------
  -interface ifIndex or range of ifIndex (, and -)  (all)

Interface information consists of the following MIB entries (exludes counter-type interface metrics):

  Index
  Description
  Type
  MTU
  Speed
  Duplex *
  PhysAddress
  AdminStatus
  OperStatus
  LastChange

NOTE: Duplex is found in the EtherLike-MIB and thus will not be populated for non-Ethernet interface types.

If successful, returns a pointer to a hash containing interface information.

  $ifs->{1}->{'Index', 'Description', ...}
  $ifs->{2}->{'Index', 'Description', ...}
  ...
  $ifs->{n}->{'Index', 'Description', ...}

interface_ip() - return IP info for interfaces

  my $ips = $cm->interface_ip([1]);

Populate a data structure with the IP information per interface. If successful, returns a pointer to a hash containing interface IP information. For /xx instead of dotted-octet format for mask, use the optional boolean argument.

  $ips->{1}->[0]->{'IPAddress', 'IPMask'}
             [1]->{'IPAddress', 'IPMask'}
             ...
  ...
  $ips->{n}->[0]->{'IPAddress', 'IPMask'}

First hash value is the interface ifIndex, next array is the list of current IP information per the interface ifIndex.

interface_metrics() - return interface metrics

  my $ifs = $cm->interface_metrics([OPTIONS]);

Populate a data structure with interface metrics.

NOTE: This method only provides the counter values - do NOT confuse this with utilization. This is the raw number of "metric" types seen since the counter was last reset.

Called with no arguments, populates data structure for all interfaces. Called with one argument, interpreted as the interface(s) to retrieve metrics for.

  Option     Description                            Default
  ------     -----------                            -------
  -interface ifIndex or range of ifIndex (, and -)  (all)
  -metrics   Metric or array of metrics to return   (all)
             eg:    -metrics => 'octets'
             eg:    -metrics => [octets, ...]
               (or) -metrics => \@mets

Interface metrics consist of the following MIB entries:

  Multicasts   (count of packets in/out)
  Broadcasts   (count of packets in/out)
  Octets       (count of octets in/out)
  Unicasts     (count of packets in/out)
  Discards     (count of packets in/out)
  Errors       (count of packets in/out)
  Unknowns *   (count of packets in)

NOTE: Providing an above value for -metrics returns the In and Out counter for the metric; except for Unknowns, which does not have an Out counter.

If successful, returns a pointer to a hash containing interface metrics.

  $ifs->{1}->{'InMulticasts', 'OutMulticasts', 'InOctets', ...}
  $ifs->{2}->{'InMulticasts', 'OutMulticasts', 'InOctets', ...}
  ...
  $ifs->{n}->{'InMulticasts', 'OutMulticasts', 'InOctets', ...}

interface_utilization() - return interface utilization

  my $ifs = $cm->interface_utilization([OPTIONS]);

or

  my ($ifs, $recur);
  ($ifs, $recur) = $cm->interface_utilization(
                                              [OPTIONS]
                                              -recursive => $recur
                                             );

Populate a data structure with interface utilizations.

NOTE: This method processes the counter values described in the interface_metrics method and returns utilizations in packets or octets per second. This is done by retrieving the metrics, waiting for a 'polling interval' of time, retrieving the metrics again and finally processing the utilizations, populating and returning the data structure.

Called with no arguments, populates data structure for all interfaces. Called with one argument, interpreted as the interface(s) to retrieve metrics for.

  Option     Description                            Default
  ------     -----------                            -------
  -interface ifIndex or range of ifIndex (, and -)  (all)
  -metrics   Metric or array of metrics to return   (all)
             eg:    -metrics => 'octets'
             eg:    -metrics => [octets, ...]
               (or) -metrics => \@mets
  -polling   The polling interval in seconds        10
  -recursive Variable with previous results         -none-

Interface utilizations consist of the following MIB entries:

  Multicasts   (packets/second in/out)
  Broadcasts   (packets/second in/out)
  Octets       (bits/second in/out)
  Unicasts     (packets/second in/out)
  Discards     (packets/second in/out)
  Errors       (packets/second in/out)
  Unknowns *   (packets/second in)

NOTE: Providing an above value for -metrics returns the In and Out utilization for the metric; except for Unknowns, which does not have an Out counter.

If successful, returns a pointer to a hash containing interface utilizations.

  $ifs->{1}->{'InMulticasts', 'OutMulticasts', 'InOctets', ...}
  $ifs->{2}->{'InMulticasts', 'OutMulticasts', 'InOctets', ...}
  ...
  $ifs->{n}->{'InMulticasts', 'OutMulticasts', 'InOctets', ...}

Notes on Interface Utilization

As previously mentioned, interface utilization is computed by retrieving interface metrics, waiting for a 'polling interval' of time, retrieving interface metrics again and calculating the difference (and other math in the case of octets). To accomplish this, the following is executed:

  User calls 'interface_utilization'

    'interface_utilization' method calls 'interface_metrics' method
    'interface_utilization' method waits for 'polling' seconds
    'interface_utilization' method calls 'interface_metrics' method
    'interface_utilization' method performs calculations and returns

  User program continues

This works well to get the interface utilization over a single polling interval. However, if the user program were to repeatedly obtain interface utilization statistics (for example, using a while() loop), this method can be improved.

Consider for example:

  my ($ifs, $recur);
  while (1) {
      ($ifs, $recur) = $cm->interface_utilization(
                                                  -recursive => $recur
                                                 );
      printf "%i\n", $ifs->{'1'}->{InOctets}
  }

The -recursive option along with an array return value ($ifs, $recur) allows the user to specify 2 return values: the first is the interface utilization statistics, the second is the interface metrics retrieved in the interface_utilization method's second call to the interface_metrics method. Upon first execution, this value is empty and the interface_utilization method calls interface_metrics twice. However, on subsequent calls to the interface_utilization method, it skips the first call to the interface_metrics method and just uses the previously obtained metrics found in $recur. This streamlines the utilization calculations by saving time, bandwidth and processing power on both the device running this script and the device under test.

To illustrate, assume we poll a device at 'T' polling intervals. We retrieve the metrics (M) at each interval and calculate the utilization (U) for each interval.

  |---- T ---|---- T ---|---- T ---|
  M1         M2         M3         M4

  Utilization 1 = M2 - M1
  Utilization 2 = M3 - M2
  Utilization 3 = M4 - M3

WITHOUT the -recursive option, the following less efficient (but still effective) operation occurs:

   |---- T ---||---- T ---||---- T ---|
  M1         M2M3        M4M5        M6

  Utilization 1 = M2 - M1
  Utilization 2 = M4 - M3
  Utilization 3 = M6 - M5

interface_updown() - admin up/down interface

  my $line = $cm->interface_updown([OPTIONS]);

Admin up or down the interface. Called with no arguments, admin up all interfaces. Called with one argument, interpreted as the interface(s) to admin up.

  Option     Description                            Default
  ------     -----------                            -------
  -interface ifIndex or range of ifIndex (, and -)  (all)
  -operation 'up' or 'down'                         'up'

To specify individual interfaces, provide their number:

  my $line = $cm->interface_updown(2);

Admin up ifIndex 2. To specify a range of interfaces, provide a range:

  my $line = $cm->interface_updown(
                                   -operation => 'down',
                                   -interface => '2-4,6,9-11'
                                  );

Admin down ifIndex 2 3 4 6 9 10 11.

If successful, returns a pointer to an array containing the interfaces admin up/down.

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). Called with no arguments, clear all lines. Called with one argument, interpreted as the lines to clear.

  Option     Description                            Default
  ------     -----------                            -------
  -lines     Line or range of lines (, and -)       (all)

To specify individual lines, provide their number:

  my $line = $cm->line_clear(2);

Clear line 2. To specify a range of lines, provide a range:

  my $line = $cm->line_clear('2-4,6,9-11');

Clear lines 2 3 4 6 9 10 11.

If successful, returns a pointer to an array containing the lines cleared.

line_info() - return line info

  my $line = $cm->line_info();

Populate a data structure with line information. If successful, returns a pointer to a hash containing line information.

  $line->{0}->{'Number', 'TimeActive', ...}
  $line->{1}->{'Number', 'TimeActive', ...}
  ...
  $line->{n}->{'Number', 'TimeActive', ...}

line_sessions() - return session info for lines

  my $session = $cm->line_sessions();

Populate a data structure with the session information per line. If successful, returns a pointer to a hash containing session information.

  $sessions->{1}->[0]->{'Session', 'Type', 'Dir' ...}
                  [1]->{'Session', 'Type', 'Dir' ...}
                  ...
  ...
  $sessions->{n}->[0]->{'Session', 'Type', 'Dir' ...}

First hash value is the line number, next array is the list of current sessions per the line number.

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, 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"

If successful, returns a pointer to an array containing the lines messaged.

line_numberof() - return number of lines

  my $line = $cm->line_numberof();

If successful, 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 a pointer to an 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 proxy ping. Valid options are:

  Option     Description                            Default
  ------     -----------                            -------
  -count     Number of pings to send                1
  -family    Address family IPv4/IPv6               [Inherit from new()]
               Valid values for IPv4:
                 4, v4, ip4, ipv4, AF_INET (constant)
               Valid values for IPv6:
                 6, v6, ip6, ipv6, AF_INET6 (constant)
  -host      Destination to send proxy ping to      (localhost)
  -size      Size of the ping packets in bytes      64
  -vrf       VRF name to source pings from          [none]
  -wait      Time to wait for replies in seconds    1

A hostname value for host will be resolved to IPv4/v6 based on family. Family is inherited from the value set in new() but can be overriden. Providing a numeric address will also self-determine the IPv4/v6 address.

Allows the following methods to be called.

proxy_ping_sent() - return number of pings sent

  $ping->proxy_ping_sent();

Return the number of pings sent in the current proxy ping execution.

proxy_ping_received() - return number of pings received

  $ping->proxy_ping_received();

Return the number of pings received in the current proxy ping execution.

proxy_ping_minimum() - return minimum round trip time

  $ping->proxy_ping_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->proxy_ping_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->proxy_ping_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 implement the System MIB defined in SNMPv2-MIB and the ENTITY-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.

system_inventory() - return system inventory info

  my $inventory = $cm->system_inventory();

Populate a data structure with inventory information. If successful, returns a pointer to an array containing inventory information.

  $inventory->[0]->{'Descr', 'VendorType', ...}
  $inventory->[1]->{'Descr', 'VendorType', ...}
  ...
  $inventory->[n]->{'Descr', 'VendorType', ...}

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 or ANY liability for its use.

password_decrypt() - decrypt a Cisco type 7 password

  my $passwd = Cisco::Management->password_decrypt('00071A150754');

Where 00071A150754 is the encrypted Cisco password in this example.

password_encrypt() - encrypt a Cisco type 7 password

  my $passwd = Cisco::Management->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.

Returns a pointer to an array 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 shows that manually entering a password encrypted with a higher 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

This distribution comes with several scripts (installed to the default bin install directory) that not only demonstrate example uses but also provide functional execution.

SEE ALSO

Cisco::SNMP

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

http://www.VinsWorld.com

All rights reserved