The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Cisco-SNMP-1.05
River stage zero No dependents
/ Cisco::SNMP::Interface

NAME

Cisco::SNMP::Interface - Interfaces Interface for Cisco Management

SYNOPSIS

  use Cisco::SNMP::Interface;

DESCRIPTION

The following methods are for interface management. These methods implement the IF-MIB.

METHODS

new() - create a new Cisco::SNMP::Interface object

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

Create a new Cisco::SNMP::Interface object with OPTIONS as optional parameters. See Cisco::SNMP for options.

ifOIDs() - return OID names

  my @ifOIDs = $cm->ifOIDs();

Return list of Interface MIB object ID names.

ipOIDs() - return OID names

  my @ipOIDs = $cm->ipOIDs();

Return list of IP MIB object ID names.

ifMetricOIDs() - return OID names

  my @ifMetricOIDs = $cm->ifMetricOIDs();

Return list of Interface metric MIB object ID names.

ifMetricUserOIDs() - return OID names

  my @ifMetricUserOIDs = $cm->ifMetricUserOIDs();

Return list of Interface metric MIB object ID names without the 'In'/'Out' prefix.

interface_getbyindex() - get interface name by ifIndex

  my $interface = $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 $interface = $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
  PhysAddress
  AdminStatus
  OperStatus
  LastChange
  Duplex

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', ...}

Allows the following accessors to be called.

ifIndex() - return interface index

  $ifs->ifIndex([#]);

Return the index of the interface at index '#'. Defaults to 0.

ifDescription() - return interface description

  $ifs->ifDescription([#]);

Return the description of the interface at index '#'. Defaults to 0.

ifType() - return interface type

  $ifs->ifType([#]);

Return the type of the interface at index '#'. Defaults to 0.

ifMTU() - return interface MTU

  $ifs->ifMTU([#]);

Return the MTU of the interface at index '#'. Defaults to 0.

ifSpeed() - return interface speed

  $ifs->ifSpeed([#]);

Return the speed of the interface at index '#'. Defaults to 0.

ifPhysAddress() - return interface physical address

  $ifs->ifPhysAddress([#]);

Return the physical address of the interface at index '#'. Defaults to 0.

ifAdminStatus() - return interface admin status

  $ifs->ifAdminStatus([#]);

Return the admin status of the interface at index '#'. Defaults to 0.

ifOperStatus() - return interface operational status

  $ifs->ifOperStatus([#]);

Return the operational status of the interface at index '#'. Defaults to 0.

ifLastChange() - return interface last change

  $ifs->ifLastChange([#]);

Return the last change of the interface at index '#'. Defaults to 0.

ifDuplex() - return interface duplex

  $ifs->ifDuplex([#]);

Return the duplex of the interface at index '#'. Defaults to 0.

ifName() - return interface name

  $ifs->ifName([#]);

Return the name of the interface at index '#'. Defaults to 0.

ifAlias() - return interface alias

  $ifs->ifAlias([#]);

Return the alias of the interface at index '#'. Defaults to 0.

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', ...}

Allows the following accessors to be called.

ifInMulticasts() - return interface InMulticasts

  $ifs->ifInMulticasts([#]);

Return the InMulticasts of the interface at index '#'. Defaults to 0.

ifOutMulticasts() - return interface OutMulticasts

  $ifs->ifOutMulticasts([#]);

Return the OutMulticasts of the interface at index '#'. Defaults to 0.

ifInBroadcasts() - return interface InBroadcasts

  $ifs->ifInBroadcasts([#]);

Return the InBroadcasts of the interface at index '#'. Defaults to 0.

ifOutBroadcasts() - return interface OutBroadcasts

  $ifs->ifOutBroadcasts([#]);

Return the OutBroadcasts of the interface at index '#'. Defaults to 0.

ifInOctets() - return interface InOctets

  $ifs->ifInOctets([#]);

Return the InOctets of the interface at index '#'. Defaults to 0.

ifOutOctets() - return interface OutOctets

  $ifs->ifOutOctets([#]);

Return the OutOctets of the interface at index '#'. Defaults to 0.

ifInUnicasts() - return interface InUnicasts

  $ifs->ifInUnicasts([#]);

Return the InUnicasts of the interface at index '#'. Defaults to 0.

ifOutUnicasts() - return interface OutUnicasts

  $ifs->ifOutUnicasts([#]);

Return the OutUnicasts of the interface at index '#'. Defaults to 0.

ifInDiscards() - return interface InDiscards

  $ifs->ifInDiscards([#]);

Return the InDiscards of the interface at index '#'. Defaults to 0.

ifOutDiscards() - return interface OutDiscards

  $ifs->ifOutDiscards([#]);

Return the OutDiscards of the interface at index '#'. Defaults to 0.

ifInErrors() - return interface InErrors

  $ifs->ifInErrors([#]);

Return the InErrors of the interface at index '#'. Defaults to 0.

ifOutErrors() - return interface OutErrors

  $ifs->ifOutErrors([#]);

Return the OutErrors of the interface at index '#'. Defaults to 0.

ifInUnknowns() - return interface InUnknowns

  $ifs->ifInUnknowns([#]);

Return the InUnknowns of the interface at index '#'. Defaults to 0.

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 $interface = $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 $interface = $cm->interface_updown(2);

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

  my $interface = $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.

DIRECT ACCESS METHODS

The following methods can be called on the Cisco::SNMP::Interface object directly to access the values directly.

get_ifIndex (#)
get_ifDescription (#)
get_ifType (#)
get_ifMTU (#)
get_ifSpeed (#)
get_ifPhysAddress (#)
get_ifAdminStatus (#)
get_ifOperStatus (#)
get_ifLastChange (#)
get_ifDuplex (#)
get_ifName (#)
get_ifAlias (#)
get_ifInMulticasts (#)
get_ifOutMulticasts (#)
get_ifInBroadcasts (#)
get_ifOutBroadcasts (#)
get_ifInOctets (#)
get_ifOutOctets (#)
get_ifInUnicasts (#)
get_ifOutUnicasts (#)
get_ifInDiscards (#)
get_ifOutDiscards (#)
get_ifInErrors (#)
get_ifOutErrors (#)
get_ifInUnknowns (#)

Get Interface OIDs where (#) is the OID instance, not the index from interface_info or interface_metrics. If (#) not provided, uses 0.

INHERITED METHODS

The following are inherited methods. See Cisco::SNMP for more information.

close
error
session

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.

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 2015

http://www.VinsWorld.com

All rights reserved