/ 
SNMP-Info-3.985000
⭐ Starred 39 / SNMP::Info::IEEE802dot3ad

NAME

SNMP::Info::IEEE802dot3ad - SNMP Interface to IEEE Aggregated Links

AUTHOR

SNMP::Info Developers

SYNOPSIS

# Let SNMP::Info determine the correct subclass for you.
my $info = new SNMP::Info(
    AutoSpecify => 1,
    Debug       => 1,
    DestHost    => 'myswitch',
    Community   => 'public',
    Version     => 2
) or die "Can't connect to DestHost.\n";

List one device's aggregates, its multi-chassis domains, and whether the tables were read in full:

my $interfaces = $info->interfaces();
my $groups     = $info->lag_groups();

foreach my $agg ( sort { $a <=> $b } keys %$groups ) {
    my $group = $groups->{$agg};
    printf "%s: lacp %s, actor %s, partner %s\n",
        $interfaces->{$agg}, $group->{lacp},
        $group->{actor_system}   // 'none',
        $group->{partner_system} // 'none';

    foreach my $port ( sort { $a <=> $b } keys %{ $group->{members} } ) {
        print "  member $interfaces->{$port}\n";
    }
    if ( my $mc = $group->{mc} ) {
        printf "  %s group %s in domain %s\n", $mc->{kind},
            $mc->{group}, $mc->{domain} // 'none';
    }
    print "  peer link\n" if $group->{peer_link};
}

my $domains = $info->mlag_domains();
foreach my $id ( sort keys %$domains ) {
    my $domain = $domains->{$id};
    printf "%s %s: peer %s, system %s\n", $domain->{kind}, $id,
        $domain->{peer} // 'none', $domain->{system_mac} // 'none';
}

my $complete = $info->lag_groups_complete();
warn "LAG tables were not fully read\n"
    if defined $complete and !$complete;

SNMP::Info reports each device on its own; grouping aggregates across devices is the caller's work. This example takes one object per polled device. It finds the actor systems that several devices present, as the two switches of an MLAG pair or the members of an ESI-LAG set do, and the aggregates on other devices whose partner is such a system:

# %devices: host name => SNMP::Info object
my %presented_by;    # actor system => { host => [ aggregate ifIndex ] }
foreach my $host ( sort keys %devices ) {
    my $groups = $devices{$host}->lag_groups();
    foreach my $agg ( sort { $a <=> $b } keys %$groups ) {
        my $system = $groups->{$agg}{actor_system} // next;
        push @{ $presented_by{$system}{$host} }, $agg;
    }
}

foreach my $host ( sort keys %devices ) {
    my $groups = $devices{$host}->lag_groups();
    foreach my $agg ( sort { $a <=> $b } keys %$groups ) {
        my $partner = $groups->{$agg}{partner_system} // next;
        my $peers   = $presented_by{$partner} or next;
        next unless keys %$peers > 1;
        printf "%s aggregate %s faces %s as one LACP system %s\n",
            $host, $agg, join( ' and ', sort keys %$peers ), $partner;
    }
}

DESCRIPTION

SNMP::Info::IEEE802dot3ad reports a device's link aggregates from IEEE8023-LAG-MIB: each aggregate's members, its LACP actor and partner, and, where the device class reads a vendor source, its multi-chassis group and the device's multi-chassis domains.

Every class that inherits SNMP::Info::Layer2 or SNMP::Info::Layer3 has these methods.

These methods report only what the device returns. They never infer an aggregate, a partner or a domain from another device. A field the device does not serve is undef or absent.

SNMP::Info::Layer3::Nexus, SNMP::Info::Layer3::Extreme and SNMP::Info::RapidCity fill mc and mlag_domains(); Nexus and RapidCity also fill peer_link. Members come from each class's agg_ports(), for example in SNMP::Info::Layer3::Juniper and SNMP::Info::Layer3::Extreme.

Terms

aggregate

Ports the device bundles into one logical link: a port-channel, LAG, MLT, trunk or ae interface.

aggregator row

A row of the IEEE8023-LAG-MIB dot3adAggTable, indexed by ifIndex, holding the LACP actor and partner of one aggregator. Some devices also serve a row for each member port.

actor

This device's end of an LACP aggregate: its LACP system ID and operational key.

partner

The far end of an LACP aggregate, as this device reports it.

static aggregate

An aggregate that does not run LACP. It has no partner.

multi-chassis group

An aggregate whose members are split across two devices that present it to the far end as one aggregate: a Cisco vPC, an Extreme MLAG port, or an SMLT.

multi-chassis domain

The pairing of two devices that serve multi-chassis groups together: a vPC domain, an MLAG peer, or an IST or virtual IST session.

The aggregate that joins the two devices of a multi-chassis domain, such as a vPC peer link or an IST.

ESI-LAG has no field of its own. It shows only as one actor system that several devices present, as the second SYNOPSIS example finds.

Inherited Classes

SNMP::Info::Aggregate

Required MIBs

IEEE8023-LAG-MIB

For Class Authors

A device class adapts these methods by overriding five private hooks. Each has a default here.

_lag_aggregator_map()

Returns a HASH reference mapping each aggregator row's ifIndex to the key of the record that row describes. The default maps each row to itself. Override it when agg_ports() keys an aggregate by a different ifIndex, so the row and the members land on one record: SNMP::Info::RapidCity maps an MLT's row to its designated port, SNMP::Info::Layer3::Juniper maps a logical unit's row to its physical ae interface.

_lag_vendor_groups($groups)

Receives the records after the identity and members are placed, and adds or changes records in place, such as mc and peer_link. A new record starts from SNMP::Info::IEEE802dot3ad::_lag_new_record(). The return value is ignored. The default does nothing.

_lag_vendor_domains()

Returns the mlag_domains() HASH reference. The default returns an empty one.

_lag_vendor_walked()

Returns the names of the table methods the class's hooks read, so that lag_groups_complete() checks their walks too. The default returns an empty list.

_agg_ports_walked()

Returns the names of the tables agg_ports() walks, as it calls them, so that lag_groups_complete() checks their walks too. Define it in the package that defines agg_ports(); a test checks that every class resolves both to the same package. The default returns an empty list.

The record rules:

Members

Members come from agg_ports() when the class defines it; each value becomes a record key, so it should equal the key _lag_aggregator_map() gives the aggregate's own row, or the row and its members land on two records. An aggregate agg_ports() names no member of takes as members the ports whose dot3adAggPortAttachedAggID names it, through _lag_aggregator_map().

Identity

When several aggregator rows map to one key, the actor and partner come from the lowest-numbered row that is not a port attached to a different aggregator. When every row is such a port, they come from the lowest row.

Dropped rows

After _lag_vendor_groups(), a record is removed when it has no members, no mc and no peer_link, and its key is a port attached to a different aggregate. That row is the member port's own idle aggregator, not an aggregate.

METHODS

agg_ports_lag

Returns a HASH reference mapping from slave to master port for each member of a port bundle on the device. Keys are ifIndex of the slave ports, Values are ifIndex of the corresponding master ports.

lag_groups

Returns a HASH reference with one record per aggregate. The key is the ifIndex agg_ports() uses for the aggregate, else the ifIndex of its aggregator row. On most devices this is the aggregate interface. The exceptions:

Each record has these fields:

members

HASH reference keyed by member ifIndex. Each value is a HASH reference with partner_system and partner_key, the partner that member port reports (dot3adAggPortPartnerOperSystemID, dot3adAggPortPartnerOperKey). Both are undef when the port reports no partner, including a partner system ID of all zeros. members is empty when the device names no member.

actor_system, actor_key

The actor's LACP system ID and operational key, from the aggregator row. Undef when the device serves no aggregator row for the aggregate, as for a static aggregate on some devices.

partner_system, partner_key

The partner's LACP system ID and operational key, from the aggregator row. Both are undef when the device reports no partner, including a partner system ID of all zeros.

lacp

1 when partner_system is defined, 0 otherwise. It is 0 for a static aggregate and for an LACP aggregate that has not found its partner.

mc

Present only on a multi-chassis group. A HASH reference with these keys:

kind

vpc (Cisco NX-OS), mlag (Extreme EXOS) or smlt (Passport and Baystack).

group

The device's identifier for the group: the vPC id, the MLAG port id (extremeMlagPortId) or the MLT id.

domain

The key in mlag_domains() of the domain the group belongs to. Undef when the device serves none for the group.

state

The group's state, as the device serves it: the vPC host link status, the MLAG local link status or the MLT running type. Undef when the device serves none.

Present, with the value 1, only on the aggregate that is a multi-chassis domain's peer link.

sources

HASH reference naming the MIB object each field with a value was read from, such as IEEE8023-LAG-MIB::dot3adAggActorSystemID. The members source is agg_ports when agg_ports() lists the members, else IEEE8023-LAG-MIB::dot3adAggPortAttachedAggID, or a vendor object the device class names.

An example record, a vPC running LACP:

369098761 => {
    members => {
        436207616 => {
            partner_system => '02:00:00:00:00:20',
            partner_key    => 1,
        },
    },
    actor_system   => '02:00:00:00:00:01',
    actor_key      => 32778,
    partner_system => '02:00:00:00:00:20',
    partner_key    => 1,
    lacp           => 1,
    mc             => {
        kind   => 'vpc',
        group  => 10,
        domain => 1,
        state  => 'up',
    },
    sources => {
        members        => 'agg_ports',
        actor_system   => 'IEEE8023-LAG-MIB::dot3adAggActorSystemID',
        actor_key      => 'IEEE8023-LAG-MIB::dot3adAggActorOperKey',
        partner_system => 'IEEE8023-LAG-MIB::dot3adAggPartnerSystemID',
        partner_key    => 'IEEE8023-LAG-MIB::dot3adAggPartnerOperKey',
        mc             => 'CISCO-VPC-MIB::cVpcStatusHostLinkIfIndex',
    },
}
mlag_domains

Returns a HASH reference with one record per multi-chassis domain, keyed by the domain's identifier on the device: the vPC domain id, the MLAG peer name, or vist or ist. Empty when the device class reads no multi-chassis source or the device serves no domain. Each record has kind and sources. The other fields are filled only for some vendors; a field the device does not serve is undef or absent:

kind

vpc (Cisco NX-OS), mlag (Extreme EXOS), or vist or ist (a virtual IST or an IST, on Passport and Baystack).

system_mac

The LACP system ID the domain presents for its multi-chassis groups.

role

The device's role in the domain. Cisco NX-OS only.

peer

The address of the other device of the domain.

peer_link

The ifIndex of the peer link aggregate, a key of lag_groups(). Cisco NX-OS only.

status

The state of the session with the other device, as the device serves it.

vlan

The VLAN the IST or virtual IST runs on. Passport and Baystack only.

sources

HASH reference naming the MIB object each field with a value was read from, as in lag_groups().

An example record, a vPC domain:

1 => {
    kind       => 'vpc',
    system_mac => '02:00:00:00:00:01',
    role       => 'primary',
    peer       => '192.0.2.2',
    peer_link  => 369098752,
    status     => 'alive',
    sources    => {
        system_mac => 'CISCO-VPC-MIB::cVpcSystemOperMacAddress',
        role       => 'CISCO-VPC-MIB::cVpcRoleStatus',
        peer       => 'CISCO-VPC-MIB::cVpcPeerKeepAliveDestAddr',
        peer_link  => 'CISCO-VPC-MIB::cVpcStatusPeerLinkIfIndex',
        status     => 'CISCO-VPC-MIB::cVpcPeerKeepAliveStatus',
    },
}
lag_groups_complete

Returns whether the IEEE8023-LAG-MIB and vendor multi-chassis tables behind lag_groups() and mlag_domains() were read in full, including the tables the class's agg_ports() reads. It performs the walks itself. It returns:

0

A walk of one of those tables was incomplete (see "Incomplete Walks" in SNMP::Info), including a walk that failed before returning any row. The records may be missing data.

undef

Every walk completed, and both methods returned no record. The device has no aggregate and no domain.

1

Every walk completed, and at least one method returned a record.

TABLE METHODS

These are methods that return tables of information in the form of a reference to a hash.

ad_lag_ports

(dot3adAggPortListPorts)

lag_actor_system

(dot3adAggActorSystemID)

lag_actor_key

(dot3adAggActorOperKey)

lag_partner_system

(dot3adAggPartnerSystemID)

lag_partner_key

(dot3adAggPartnerOperKey)

lag_port_attached

(dot3adAggPortAttachedAggID)

lag_port_partner_system

(dot3adAggPortPartnerOperSystemID)

lag_port_partner_key

(dot3adAggPortPartnerOperKey)