Table Of Contents

EtherChannelApp Service

Information About EtherChannelApp Service

addPortsToEtherChannelEndPoint

addPortsToEtherChannelEndPointWithForce

createEtherChannel

createEtherChannelForSpecifiedEndpoints

deleteEtherChannelEndPoints

deleteEtherChannels

disableLacp

enableLacp

getAllEtherChannels

getAllEtherChannelsForTopology

getEtherChannelGlobalSettings

getEtherChannelLinks

getEtherChannelsInNetworkElement

getEtherChannelsInNetworkElements

getEtherChannelsWithMemberPorts

getLacpStateOfNetworkElements

getNetworkCardsWithLoadBalanceSettings

modifyEtherChannelGlobalSetting

modifyEtherChannelInterfaces

modifyNetworkCardEtherChannelLoadBalanceSettings

modifyNetworkInterfaceLinks

removePortsFromEtherChannelEndPoint

EtherChannelApp Service

---

This chapter describes the DCNM web services' API methods for the EtherChannelApp service.

Information About EtherChannelApp Service

The port-channel technology allows you to scale the link bandwidth by aggregating, or bundling, parallel links. Two to eight links of Fast Ethernet (FE) or Gigabit Ethernet (GE) ports can be bundled into one logical link. Port channels also provide redundancy. If one link in the port channel goes down, traffic still flows through the port channel via another link that is up in the port channel. This situation does not bring down the port-channel interface, and a recomputation of the route in the network is not required. A higher aggregated bandwidth is obtained by the sum of the bandwidth of all the ports in the channel. The data traffic is load balanced across the member links, based on the hash algorithm.

The port-channel interfaces are logical interfaces (ports) that have a unique port channel ID within a device. A port-channel interface can be either a Layer 2 port-channel interface (SwitchedEtherChannelNetworkInterface) or a Layer 3 port-channel interface (RoutedEtherChannelNetworkInterface). Each port-channel interface can have 0 to 16 physical ports as members for Catalyst 6500 series switches, but those member ports should have common operational and configurational parameters. A Layer 2 port channel can be associated with Layer 2 physical ports only and a Layer 3 port channel can be associated with Layer 3 physical ports only.

The API categories are as follows:

•Query/Get APIs—Query data from the persistent database.

•Create APIs—Create new port channels.

•Modify APIs—Modify basic attributes of existing port-channel interfaces.

•Delete APIs—Delete existing port channels.

•Add and Remove APIs—Add and remove the association between the port channel and its member ports.

•Enable and Disable APIs—Enable and disable LACP service in the device.

addPortsToEtherChannelEndPoint

Associates the given ports to the given Ethernet channel end point. The given ports should operate in the same mode (switched or routed) as the given Ethernet channel end point.

Member port mode will be updated based on Ethernet channel end point protocol as follows:

ProtocolDefault Mode

LACPActive

NONEOn

ValidationException is thrown if any of the following situation occurs:

•If channelEpId is null.

•If channelEpId is not a valid Ethernet channel end point InstanceNameId.

•If the portIds collection is null or the collection is empty or the collection contains objects other than InstanceNameId of physical ports.

•If port security is enabled in any one of the given member ports (802.1x ports).

•If member ports are configured with different ACLs.

•If any one of the member ports is a Switched Port Analyzer (SPAN) destination

PropertiesException is thrown if any of the following situation occurs:

–If given Ethernet channel end point has 16 member port already.

–If given ports operate in different mode (ex : switched) than the given Ethernet channel end point(ex : routed).

IntegrityException is thrown if any of the following situation occurs:

–If the given channel end point does not exist in device.

–If the given ports do not exist in device.

Parameters

opContext—Operational context

channelEpId—InstanceNameId of the SwitchedEtherChannelNetworkInterface/RoutedEtherChannelNetworkInterface to which the given ports should be associated

portIds—list of InstanceNameId of ports (SwitchedNetworkInterface / RoutedNetworkInterface) to be added

Return Value

void

addPortsToEtherChannelEndPointWithForce

Associates the given ports to the given etherchannel end point. The given ports can operate in the different mode (switched or routed) than the given etherchannel end point. In this case, port mode will be changed for the given ports as per the etherchannel end point.

In case of Cisco Nexus 5000 Series switches, when this API is called then port's mismatch config from the portChannel will be copied. This is done to support force option in Cisco Nexus 5000 Series switches for vPC wizard. Since Cisco Nexus 5000 Series switches does not supports routed interface, this mentioned behaviour expected only for switched interface and only for Cisco Nexus 5000 Series switches platform.

Below configurations will be captured from etherchannel end point and updated in member ports

•Port Setting (speed, duplex,etc)

•Flow Control Sent

•Flow Control Receive

•Traffic storm-control

•Switch Port mode (Access or Trunk)

•switchport access vlan if exist

•switchport trunk native vlan if exist

•switchport trunk allowed vlan if exist

Member port mode will be updated based on etherchannel end point protocol as follows:

Protocol	Default Mode
LACP	Active
NONE	On

ValidationException is thrown if any of the following situations occurs:

•If channelEpId is null.

•If channelEpId is not a valid etherchannel end point InstanceNameId.

•If the portIds collection is null or the collection is empty or the collection contains objects other than InstanceNameId of physical ports.

•If any one of the member ports is a Switched Port Analyzer (SPAN) destination

PropertiesException is thrown if any of the following situations occurs:

•If given etherchannel end point has 16 member port already.

IntegrityException is thrown if any of the following situations occurs:

•If the given channel end point does not exist in device.

•If the given ports do not exist in device.

Parameters

opContext—operational Context.

channelEpId—the InstanceNameId of the SwitchedEtherChannelNetworkInterface/RoutedEtherChannelNetworkInterface to which the given ports should be associated.

portIds—the list of InstanceNameId of ports (SwitchedNetworkInterface / RoutedNetworkInterface) to be added.

createEtherChannel

Creates the given new Ethernet channel and returns the list of instance name ids of newly created Ethernet channel endpoints.

The passed Ethernet channel object should have its both Ethernet channel network interface endpoints and their corresponding associations with channel members populated.This method is available for Cisco Nexus 7000 Series switches that run Cisco NX-OS Release 5.0(3) or later.

ValidationException is thrown if any of the following situation occurs:

•If newChannel is null.

•If Protocol is not set to NONE for any of the Ethernet channel end point which does not have member ports.

•If Protocol is set to PAgP for any of the Ethernet channel end point.

•If Protocol is set to LACP when any member port mode is AUTO or DESIRABLE

•If any member port is Port security(802.1x port) enabled.

•If member ports are configured with different ACLs.

•If any one member port is a Switched Port Analyzer (SPAN) destination port

PropertiesException is thrown if any of the following situation occurs:

•If newChannel is not valid.

Example:

•Ethernet channel ID should be in the range between 1-256 for Catalyst 6500 series switches and 1-4096 for Nexus 7000 series switch.

•only 16 ports can be added into an Ethernet channel end point as members

IntegrityException is thrown if any of the following situation occurs:

•If the Ethernet channel end point with the given Ethernet channel ID already exist in the device.

Parameters

opContext—Operational context

newChannel—new channel to be added

Return Value

The List of InstanceNameId of the new channel endpoints

createEtherChannelForSpecifiedEndpoints

Creates an Ethernet channel between the given ports with the given channel id.

This method creates endpoints using the given channel id and the given list of ports. The mode (switched / routed) of new Ethernet channel created will be based on the mode of given ports. All the given ports should be of same mode either as switched or routed. All the attributes of the Ethernet channel network interface endpoints and their association parameters are set to default values. If the given member ports list is empty, the protocol is set to NONE else the protocol and mode are set to default values: LACP and ACTIVE.

ValidationException is thrown if any of the following situation occurs:

•If sourceEpChannelId is null.

•If the sourceEpPortMemberIds is not a valid Network Interface InstanceNameId.

•If the neighborEpChannelIds contains one or more null element, or empty

PropertiesException is thrown if any of the following situation occurs:

•If sourceEpChannelId is not valid Ethernet channel ID.

•If neighborEpChannelIds does not contain valid Ethernet channel IDs.

Example:

•Ethernet channel ID should be in the range between 1 to 256 in Catalyst 6500 series switches,and 1 to 4096 in Nexus 7000 series switch.

IntegrityException is thrown if any of the following situation occurs:

•If the Ethernet channel network interface with the given Ethernet channel ID already exist in the database.

•If the sourceEpPortMemberIds collection contains a NetworkInterface InstanceNameId that does not exist in the database.

•If a NetworkInterface in the sourceEpPortMemberIds contains duplicate NetworkInterface objects.

Parameters

opContext—Operational context

sourceEpChannelId—channel id to be used for the source endpoint

sourceEpPortMemberIds—List of InstanceNameId of source endpoint port members (SwitchedNetworkInterface / RoutedNetworkInterface)

neighborEpChannelIds—List of channel ids (Integer) to be used for the neighbor endpoints

neighborEpPortMemberIds—List of List objects containing InstanceNameId of neighbor endpoint port members (SwitchedNetworkInterface/ RoutedNetworkInterface)

Return Value

The List of InstanceNameId of the new channel endpoints

deleteEtherChannelEndPoints

Deletes all the given Ethernet channel endpoints.

This method deletes all the given instances of SwitchedEtherChannelNetworkInterface / RoutedEtherChannelNetworkInterface endpoints and their port member associations.

ValidationException is thrown if any of the following situation occurs:

•If endPointIds collection is null or it is empty.

•If endPointIds collection contains an element that is not of type SwitchedEtherChannelNetworkInterface / RoutedEtherChannelNetworkInterface InstanceNameId.

IntegrityException is thrown if the given port channel end points do not exist in device.

Parameters

opContext—Operational context

endPointIds—array of InstanceNameId of endpoints (SwitchedEtherChannelNetworkInterface / RoutedEtherChannelNetworkInterface

Return Value

void

deleteEtherChannels

Deletes all the given ether channels.

This method deletes each given Ethernet channel by removing all the port members and the Ethernet channel endpoints of the given EtherChannels.

ValidationException is thrown if any of the following situation occurs:

•If channels collection is null or empty.

•If channels collection contains an element that is not of type Ethernet channel InstanceNameId.

IntegrityException is thrown if the given channels do not exist in devices.

Parameters

opContext—Operational context

channels—List of the Ethernet channel to be deleted

Return Value

void

disableLacp

Disables LACP service on one or more network element. This API is applicable only for devices running Cisco NX-OS.

ValidationException is thrown if any of the following situation occurs:

•If the neInstanceNameIdCol is null.

•If the neInstanceNameIdCol contains one or more null element, or the collection is empty or it is not type InstanceNameId.

Parameters

opContext—Operational context

neInstanceNameIdCol—list of InstanceNameId of the Network Element for which the LACP should be disabled

Return Value

void

enableLacp

Enables LACP service on one or more network element. This API is applicable only for devices running Cisco NX-OS.

ValidationException is thrown if any of the following situation occurs:

•If the neInstanceNameIdCol is null.

•If the neInstanceNameIdCol contains one or more null element, or the collection is empty or it is not type InstanceNameId.

Parameters

opContext—Operational context

neInstanceNameIdCol—list of InstanceNameId of the Network Element for which the LACP should be enabled

Return Value

void

getAllEtherChannels

Returns all the EtherChannels present in the network.

The EtherChannels returned by this method will have its both source and neighbor endpoints populated. Please note that Ethernet channel network interface endpoints will have all the attributes populated except the port member associations. These associations can be obtained using other specific get API, getEtherChannelLinks(OpContext, List).

Please note that the returned List will contain only one Ethernet channel instance per Ethernet channel in network level. This instance will have any one of the port-channel endpoints as source endpoint and other port-channel endpoints as neighbor endpoints.

Parameters

opContext—Operational context

Return Value

All the EtherChannels in network. The returned list will contain the list of either Ethernet channel instances.

Following associations will be there for an Ethernet channel:

•Source end of an Ethernet channel

•Neighbor end of an Ethernet channel

Following associations will be there for each end of an Ethernet channel:

(other associations will be cleared)

•Interface status

•Interface Capability

•Interface Setting

getAllEtherChannelsForTopology

Returns all the EtherChannels present in the network.

The EtherChannels returned by this method will have its both source and neighbor endpoints populated. Please note that etherchannel network interface endpoints will have all the attributes populated except the port member associations. These associations can be obtained using other specific get API, getEtherChannelLinks(OpContext, List).

Please note that the returned List will contain only one EtherChannel instance per etherchannel in network level. This instance will have any one of the port-channel endpoints as source endpoint and other port-channel endpoints as neighbor endpoints.This method is available for Cisco Nexus 7000 Series switches that run Cisco NX-OS Release 5.0(3) or later.

Parameters

opContext—operational Context.

Returns

All the EtherChannels in network. The returned list will contain the list of either EtherChannel instances.

Following associations will be there for an EtherChannel:

1. Source end of an etherchannel

2. Neighbor end of an etherchannel

Following associations will be there for each end of an etherchannel:

(other associations will be cleared)

1. Interface status

2. Interface Setting

getEtherChannelGlobalSettings

Returns the Ethernet channel global setting of the given network elements.

The Ethernet channel global setting objects will be ordered in the returned List based on the order of given network element instance ids.

ValidationException is thrown if the argument passed is null or it is not a valid network element InstanceNameIds.

Parameters

opContext—Operational context

networkElementIds—InstanceNameId of the network element instances whose Ethernet channel global setting information is required

Return Value

Ordered list of Ethernet channel global setting of the given network elements.

getEtherChannelLinks

Returns all the Ethernet channel links present in the given Ethernet channel endpoints.

Each link will have a collection (both ends) of physical interfaces. If the link does not exist, the collection will have only one end in the list.

Following associations will be available for each end of the link SwitchedNetworkInterface/RoutedNetworkInterface:

•SwitchedEtherChannelPortSetting/RoutedEtherChannelPortSetting

•SwitchedEtherChannelPortStatus/RoutedEtherChannelPortStatus

ValidationException is thrown if the argument passed is null or it is not a valid Switched/Routed Ethernet channel interface InstanceNameIds.

Parameters

opContext—Operational context

channelEndPointIds—InstanceNameId of the SwitchedEtherChannelNetworkInterface and RoutedEtherChannelNetworkInterface instances whose links information is required

Return Value

The Ethernet channel links present in the given EtherChannels. The returned List will contain the List objects containing either NetworkInterfaceLink instances or NetworkInterfaceLink instances.

getEtherChannelsInNetworkElement

Returns all the EtherChannels that have atleast one end point in the given network element.

The EtherChannels returned by this method will have its both source and neighbor endpoints populated. Please note that Ethernet channel network interface endpoints will have all the attributes populated except the port member associations. These associations can be obtained using other specific API get method, getEtherChannelLinks(OpContext, List).

ValidationException is thrown if the argument passed is null or it is not a valid network element InstanceNameId.

Parameters

opContext—Operational context

networkElementId—InstanceNameId of the network element for which the EtherChannels are required

Return Value

The EtherChannels present in the given network element. The returned list will contain the list of either Ethernet channel instances.

Following associations will be there for an Ethernet channel:

•Source end of an Ethernet channel

•Neighbor end of an Ethernet channel

Following associations will be there for each end of an Ethernet channel:

(other associations will be cleared)

•Interface status

•Interface Capability

•Interface Setting

getEtherChannelsInNetworkElements

Returns list of all the EtherChannels that have atleast one end point in the list of given network elements.

The EtherChannels returned by this method will have its both source and neighbor endpoints populated. Please note that etherchannel network interface endpoints will have all the attributes populated except the port member associations. These associations can be obtained using other specific API get method, getEtherChannelLinks(OpContext, List).This method is available for Cisco Nexus 7000 Series switches that run Cisco NX-OS Release 5.0(3) or later.

ValidationException is thrown if the argument passed is null or it is not a valid network element InstanceNameId.

Parameters

opContext—operational Context.

neInstanceNameIdCol—list of InstanceNameId of the network element for which the EtherChannels are required

Returns

The list of list of EtherChannels present in the list of given network elements. The returned list will contain the list of list of either EtherChannel instances.

Following associations will be there for an EtherChannel:

1. Source end of an etherchannel

2. Neighbor end of an etherchannel

Following associations will be there for each end of an etherchannel:

(other associations will be cleared)

1. Interface status

2. Interface Capability

3. Interface Setting

getEtherChannelsWithMemberPorts

Returns all the EtherChannels that have atleast one end point in the given network element.

The EtherChannels returned by this method will have its both source and neighbor endpoints populated. etherchannel network interface endpoints will have all the attributes populated and port member associations.This method is available for Cisco Nexus 7000 Series switches that run Cisco NX-OS Release 5.0(3) or later.

ValidationException is thrown if the argument passed is null or it is not a valid network element InstanceNameId.

Parameters

opContext—operational Context.

networkElementId—the InstanceNameId of the network element for which the EtherChannels are required.

isSwitched—if it is Boolean.True, returned List will have only Switched EtherChannels, if it is Boolean.False, returned List will have only Routed EtherChannels, if it is null, returned List will have both Switched and Routed EtherChannels.

Returns

the EtherChannels present in the given network element. The returned list will contain the list of either EtherChannel instances.

Following associations will be there for an EtherChannel:

1. Source end of an etherchannel

2. Neighbor end of an etherchannel

3. Each etherchannel end point will be populated with member ports and its link associations

Following associations will be there for each end of an etherchannel:

(other associations will be cleared)

1. Interface status

2. Interface Capability

3. Interface Setting

4. SwitchedEtherChannelPortSetting/RoutedEtherChannelPortSetting

5. SwitchedEtherChannelPortStatus/RoutedEtherChannelPortStatus

getLacpStateOfNetworkElements

Returns state of LACP service whether LACP is enabled or disabled in a list of network elements. Given the list of instance name IDs of the network elements, returns the list of Boolean values.

ValidationException is thrown if any of the following situation occurs:

•If neInstanceNameIdCol collection contains an element that is null or the collection is empty or it is not type InstanceNameId

•if the argument passed is null or it is not a valid network element InstanceNameId.

Parameters

opContext—Operational context

neInstanceNameIdCol—InstanceNameId of the one or more Network Element for which the AAA state is required

Return Value

The returned list will contain Boolean instances.

Boolean value TRUE represents LACP is enabled in the given network element.

Boolean value FALSE represents LACP is disabled in the given network element.

getNetworkCardsWithLoadBalanceSettings

Returns all the network cards of the given network element with their Ethernet channel load balance setting configurations populated.

The returned List will contain instances of NetworkCard.

ValidationException is thrown if the argument passed is null or it is not a valid network element InstanceNameId.

Parameters

opContext—Operational context

neInstanceNameId—InstanceNameId of the network element for which module level load balance settings are required

Return Value

List of NetworkCard instances. In the returned list of objects, only Load balance setting associations will be present,

modifyEtherChannelGlobalSetting

Modifies the Ethernet channel global setting of the given network element with the given global setting object.

ValidationException is thrown if any of the following situation occurs:

•if the argument passed is null or it is not a valid network element InstanceNameId.

•If networkCardSlotNos collection contains an element that is null or not Integer type

•If settings collection contains an element that is null oris not type NetworkCardEtherChannelLoadBalanceSetting

Parameters

opContext—Operational context

networkElementId—InstanceNameId of the network element whose global setting has to be updated

gSetting—new global setting object to be set

Return Value

void

modifyEtherChannelInterfaces

Modifies basic attributes(For Ex., Speed,duplex,etc) of an existing Ethernet channel end point with the modifications in the given Ethernet channel end points list.

This method updates the server with modifications in basic attributes of Ethernet channel endpoint only. Modification of port member association changes are not done in the given Ethernet channel end point.

ValidationException is thrown if any of the following situation occurs:

•If the portChannelNetworkIinterfaces is null or empty.

•If the portChannelNetworkIinterfaces contains one or more null element, or the collection contains objects that are not of type SwitchedEtherChannelNetworkInterface or RoutedEtherChannelNetworkInterface.

IntegrityException is thrown if any of the following situation occurs:

•If the given port channel network interfaces do not exist in device.

Use addPortsToEtherChannelEndPoint(OpContext, InstanceNameId, List)/#removePortsFromEtherChannelEndPoint(InstanceNameId, List)} for modifying port member associations.

Use modifyNetworkInterfaceLinks(OpContext, List)—For modifying all the attributes in the port members

Parameters

opContext—Operational context

portChannelNetworkIinterfaces—List of Modified Ethernet channel network interfaces (SwitchedEtherChannelNetworkInterface/RoutedEtherChannelNetworkInterface)

Return Value

void

modifyNetworkCardEtherChannelLoadBalanceSettings

Modifies the Ethernet channel load balance setting configuration of the given network cards in the given network element.

ValidationException is thrown if any of the following situation occurs:

•If the argument passed is null or it is not a valid network element InstanceNameId.

•If networkCardSlotNos collection contains an element that is null or empty.

•If settings collection contains an element that is null or empty.

•If the size of slot numbers and settings are not matching.

•If the card does not support load-balancing.

•If there is no module present in the given slot.

Parameters

opContext—Operational context

networkElementId—InstanceNameId of the network element whose network card Ethernet channel load balance settings have to be changed

networkCardSlotNos—slot numbers of the network cards whose load balance settings have to be modified. The list should contain the instances of Integer.

settings—load balance settings to be applied. The list should contain the instances of NetworkCardEtherChannelLoadBalanceSetting

Return Value

void

modifyNetworkInterfaceLinks

Modifies an existing port and channel association attributes in the given network interface links.

This methods updates only attributes(For ex: mode) in the association between port and channel not member port associations.

Member port mode will be updated based on Ethernet channel end point protocol as follows:

ProtocolDefault Mode

LACPActive

NONEOn

ValidationException is thrown if any of the following situation occurs:

•If the networkInterfaceLinks is null or empty.

•If the networkInterfaceLinks contains one or more null element, or the collection contains objects that are not of type NetworkInterfaceLink

Parameters

opContext—Operational context

networkInterfaceLinks—list of Ethernet channel links.It can be either NetworkInterfaceLink instances or NetworkInterfaceLink instances as value.

Return Value

void

removePortsFromEtherChannelEndPoint

Removes the given port members from the given Ethernet channel end point.

Protocol will be set to NONE, if the given Ethernet channel end point doesn't have member ports after removing given port memebers

ValidationException is thrown if any of the following situation occurs:

•If channelEpId is null.

•If channelEpId is not a valid Ethernet channel end point InstanceNameId.

•If the portIds collection is null or the collection is empty or the collection contains objects other than InstanceNameId of physical ports.

PropertiesException is thrown if any of the following situation occurs:

•If given ports operates in different mode (ex : switched) than the given Ethernet channel end point (ex : routed).

IntegrityException is thrown if any of the following situation occurs:

–If the channelEpId is a SwitchedEtherChannelNetworkInterface or RoutedEtherChannelNetworkInterface InstanceNameId that does not exist in the database.

–If the portIds collection contains a NetworkInterface InstanceNameId that does not exist in the database.

Parameters

opContext—Operational context

portIds—list of InstanceNameId of ports (SwitchedNetworkInterface / RoutedNetworkInterface) to be removed

channelEpId—InstanceNameId of the SwitchedEtherChannelNetworkInterface/RoutedEtherChannelNetworkInterface from which the given port members should be removed

Return Value

void