SET PORT GROUP

Authorization

Privilege Class: B

Purpose

Use the SET PORT command to define or change the OSA-Express (QDIO) or Network Express (EQDIO) devices that make up a link aggregation group and to set the attributes of a link aggregation group.

If the SET PORT GROUP command is issued and uses the JOIN, LACP or INTERVAL operand, and the specified group does not exist, then the group is created. The group persists until the next time that z/VM® is IPLed or until the group name is deleted with a SET PORT groupname DELETE command. For options that are not specified on the command, the following defaults are used: LACP ACTIVE EXClusive INTERVAL 300.

For more information about Virtual Networking Options in VM, see z/VM: Connectivity.

Operands

groupname

is the name of the link aggregation group that is affected by the command. The groupname value is a single token (1-8 alphanumeric characters) that identifies a link aggregation group. This group name is associated with a virtual switch via the DEFINE VSWITCH or SET VSWITCH command or the DEFINE VSWITCH or MODIFY PORT statement in the System Configuration file.

JOIn

indicates that the devices (nnn or nnnn.Pn) specified join the specified group. If the group does not exist, it is created and remains until the next time that z/VM is IPLed or the group name is deleted with a SET PORT groupname DELETE command.

nnn

nnnn.Pn

specifies a real networking device that is affected by the command.

Specify each real device as a hexadecimal number. The specification can include a hexadecimal port number that is prefixed by lower case or upper case letter P. If no port number is included, it defaults to port 0. The port number follows the device number and is separated by a period.

For example, to specify port 1 for real device 300, specify 300.P1. The port number value is limited by how many ports the adapter hardware feature supports.

The following table describes the parameters for each device type:

Device type	Number of Devices	Device number range	Port number range
QDIO	3	X'0001' - X'FFFD'	X'0' - X'F'
EQDIO	1	X'0001' - X'FFFF'	X'0'

For an OSA-Express (QDIO) device, each real device number represents a trio of devices. For example, specifying JOIN 111 means that QDIO devices 111-113 are used to provide the connection to the real hardware LAN segment.

For a Network Express (EQDIO) device, each real device number represents a single device. For example, specifying JOIN 111 means that only EQDIO device 111 is used to provide the connection to the real hardware LAN segment.

You can specify a maximum of 8 real device numbers. If you specify more than one device number, then each must be separated from the others by at least one blank.

If the port group already has at least one operational device, any new device must be compatible with the current attributes (see usage note 1.

When the port group is defined with the SHARED option, some devices on the adapters that contain the specified devices are reserved for system use. See usage note 3 for information about device number assignment for shared port groups.

See Usage Note 1 for more information about the requirements for the networking devices.

LEAve

indicates that the specified devices (rdev) leave the specified group.

DELete

indicates that the groupname definition be removed from the system. You can not delete a group that is being used for an active virtual switch. Use SET VSWITCH DISCONNECT to make the virtual switch inactive and then SET VSWITCH NOGROUP to drop the association with the group.

A SET PORT GROUP DELETE for a port group configured with the SHARED option has global scope. A copy of the shared port group exists in each member of the IVL domain and ALL port groups with that name are deleted. You can not delete a shared port group that is in use on any other system.

LACP ACTive

LACP INActive

LACP ACTive mode specifies that the virtual switch initiates negotiations with the physical switch via the Link Aggregation Control Protocol (LACP) and responds to LACP packets that are sent by the physical switch. LACP INActive specifies that aggregation is performed, but without LACP. It is useful only when the physical switch is also operating without LACP. In this mode, there is no negotiation between the physical switch and the virtual switch.

Ensure the same LACP setting exists on both the virtual switch and the physical switch.

LACP ACTIVE is the default for a groupname until changed by a SET PORT GROUP LACP command.

You cannot change the LACP mode when the port group is associated with an active virtual switch. Use SET VSWITCH DISCONNECT to inactivate the virtual switch and then SET PORT GROUP to change the LACP mode followed by SET VSWITCH CONNECT.

SHARED cannot be specified with LACP INACTIVE.

EXClusive

An exclusive port group is a set of OSA-E features that are configured so that each OSA-E feature supports only a single VSWITCH QDIO connection. In other words, no sharing of the OSA-Express adapter is permitted.

Once the port group is defined with the EXClusive option, it cannot be changed to a SHAred port group without deleting the port group.

SHAred

When LACP ACTIVE SHARED is specified, it defines a shared port group. A shared port group is a set of OSA-E features configured so that one or more global virtual switches and global virtual switch members share the OSA-Express adapter(s) that make up the port group. This defines a Multi-VSwitch LAG (Link Aggregation Group) configuration.

A port group that is defined with the SHARED option can be used for only virtual switches that are defined with the GLOBAL option. The virtual switches can be in the same or different LPARs that resides in the same CPC.

The port group has a global scope which means it provides connectivity across multiple virtual switches and multiple systems that run z/VM. It is propagated to all other systems in the same IVL domain. In other words, the Control Program creates a copy of the shared port group with the same name on all other systems that run z/VM and that are in the domain (unless the shared port group member is already defined with that name). A change to the shared port group on one system affects all copies of the shared port group on all other systems in the IVL domain.

A port group defined with the SHARED option provides a single point of control for all virtual switches that use the shared port group. For example, a SET PORT GROUP groupname LEAVE command for a shared port group removes the specified port from all virtual switches on all IVL members that use a copy of the port group with that name.

Because of the global scope, once the port group is defined with the SHARED option, it cannot be changed to an EXClusive port group without deleting the port group. In addition, the LACP mode cannot be changed to INACTIVE.

See Multi-VSwitch LAG Configuration in z/VM: Connectivity for more information.

INTerval nnnn

INTerval OFF

specifies the interval that is used by the Control Program (CP) when doing load balancing of conversations across multiple links in the group. It is specified as the number of seconds between load balancing operations across the link aggregation group. It must be a decimal number between 1 and 9990 or the keyword OFF. The interval value is rounded up to the next multiple of thirty seconds. INTERVAL OFF indicates that no load balancing is done by CP.

INTERVAL 300 is the default for a groupname until changed by a SET PORT GROUP INTERVAL command.

When the port group is configured to use the Independent Load Balance management method, the scope of the SET PORT GROUP INTERVAL setting is local to the system it is issued on.

When the port group is configured to use the Collaborative Load Balance management method, the scope of the SET PORT GROUP INTERVAL setting is global (affects all systems within the IVL).

LOADBalancing INDependent

Each virtual switch that uses a Link Aggregated Group (LAG) to provide connectivity to an external network is responsible for balancing its own bandwidth across all the network adapters within the group. By default, exclusive port groups use the Independent Load Balance management method.

When the port group is shared, the scope of the SET PORT GROUP LOADBALANCING setting is global (affects all systems within the IVL).

LOADBalancing COLlaborative

The Collaborative Load Balance management method considers and serializes its operation with all the sharing VSwitches. By default, a shared port group uses Collaborative Load Balance Management Method.

The Collaborative Load Balance management method can be used only when all active systems connected to the same IVL Domain have support for Collaborative Load Balance. If any z/VM System is added or already exists in the domain which doesn't have support for Collaborative Load Balance, then all Shared Port Groups within the domain are automatically forced to use the Independent Load Balance management method.

Collaborative Load Balance is allowed only for shared port groups, and the scope of the SET PORT GROUP LOADBALANCING COLLABORATIVE setting is global (affects all systems with the IVL).

Usage Notes

1. The following restrictions pertain to the network devices in the specified group:
   • The network device must support IEEE802.3ad Link Aggregation.
   • To aggregate multiple network devices within a group, the following criteria must be met:
     • All devices must be the same type: OSA-Express (QDIO) or Network Express (EQDIO).
     • All devices must connect to the same physical LAG group.
     • All devices must run in full-duplex mode.
     • All devices must operate at the same speed.
     All ports in the group must connect to the same physical LAG group, run in full-duplex mode and operate at the same speed.
2. The following pertain to the OSA devices in an exclusive port group, that is, one that is configured with the EXClusive option:
   • When an OSA port is active in a link aggregated group, it cannot have more than a single QDIO connection established on the adapter (CHPID). Any requests to establish a QDIO connection using another device number on the same CHPID in any logical partition fail until the OSA port is no longer active within the group. Likewise, an OSA port with an active QDIO connection on any device number on the same CHPID is not able to join a link aggregated group until there are no active QDIO connections on the port.
   • When the port group is configured as LACP Inactive, all ports in the group must support the network disablement function. Cards that do not support the network disablement function can be used only in a port group that is configured with LACP Active.
3. The following notes pertain to the OSA devices in a shared port group, which is a group that is configured with the SHARED option:
   • Another shared port group with the same name that is defined anywhere in the IVL Domain must have a matching configuration. The Control Program propagates the shared port group to all other members of the domain if a copy of the port group does not already exist.
   • When a System Administrator specifies a device number on the SET PORT GROUP JOIN command, three devices (subchannels) associated with the OSA Express adapter are reserved for system use. The Control Program chooses three devices from within the range of those associated with the OSA Express adapter, starting with the first (most significant) available device number.

     Devices that are reserved for system use are shown with SYSTEM status in the Query OSA display.

   • When a specific network adapter is configured in a shared port group, a set of device numbers (three for QDIO or one for EQDIO) is reserved in each z/VM system that has an active IVL connection.
   • A shared port group can be shared by multiple global virtual switches that reside in the same system. Each shared port group is assigned an instance (0,1,2,3) when configured to a global virtual switch.
   • The administrator can use either port that is associated with a multiple-port network adapter. Once a port is activated in a shared port group, it is no longer available for guest usage and the ATTACH command cannot be used to specify devices that are reserved for system use. Likewise, a network connection established by a guest on a specific port prevents its use in a shared port group.
   • When a shared port group is in use on a global virtual switch, an RDEV list cannot be used for the virtual switch to provide back up connectivity. Instead, back up connectivity is provided by a different global virtual switch member using the shared port group.
   • A shared port group can be used by up to 64 global virtual switch members across the IVL domain. The members can be in the same or different global virtual switches.
4. The maximum number of groups that can be defined to CP is 128.
5. It is invalid to create a group name of ALL.
6. The number of devices that are identified by the RDEV keyword on the DEFINE or SET VSWITCH command combined with the number of devices in an associated GROUP cannot exceed eight devices.
7. When the virtual switch has been defined with the GROUP attribute (using exclusive port group), any devices that are identified by the RDEV keyword (on the DEFINE or SET VSWITCH command) are used for failover in the event of a real switch failure of the link aggregation group. Failover in this environment is to a single OSA-Express device that is connected to a second real switch. The virtual switch recognizes when the port group is available again and will initiate recovery to the port group member(s). When the virtual switch is defined with GROUP and RDEV NONE, it means that there is no link aggregation group failover in the event that the real switch should fail.
8. The port number that is specified by nnnn .Pnn is used to initialize device nnnn. If the port number is not specified, it defaults to port 0. If the port number is not supported, device initialization is terminated.

Responses

     Port group groupname is {created|updated|deleted}

Messages

• HCP002E Invalid operand - operand
• HCP2768E Missing groupname
• HCP2783E Port group groupname does not exist.
• HCP2799E SET PORT GROUP change is not allowed
• HCP2799E SET PORT GROUP change is not allowed
• HCP2832E Connection device for VSWITCH SYSTEM switchname is not active. This device does not match current VSWITCH attributes.
• HCP2838I Device device specified for VSWITCH switchname BRIDGEPORT is not a bridge-capable HiperSockets device.
• HCP2838I Port portnumber specified for device device is invalid; maximum port number is maxportnumber.
• HCP2857E SET PORT GROUP not performed; detach is in progress for associated VSWITCH SYSTEM switchname.
• HCP2857E SET PORT GROUP not performed; device device is already defined in port group.
• HCP2857E SET PORT GROUP not performed; device device not defined in port group.
• HCP2857E SET PORT GROUP not performed; group is defined to VSWITCH SYSTEM switchname.
• HCP2857E SET PORT GROUP not performed; group limit exceeded.
• HCP3001E Device device is defined for both port group groupname and VSWITCH SYSTEM switchname.
• HCP3162E SET PORT GROUP is not performed. No changes are permitted to LACP because the port group was defined with the SHARED option.
• HCP3162E SET PORT GROUP is not performed. Cannot change port group from EXCLUSIVE to SHARED.
• HCP3167E [ DEFINE VSWITCH switchnm | SET VSWITCH switchnm | SET PORT GROUP groupname ] failed. The IVL virtual switch does not exist or its UPLINK port is not connected.
• HCP3173E Device device is reserved for system use.
• HCP3178E [ VSWITCH SYSTEM switchnm | PORT GROUP groupname ] creation is deferred. The IVL virtual switch does not exist or its UPLINK port is not connected.
• HCP3180E SET PORT GROUP for shared port group groupname not performed; device device does not exist.
• HCP3183E SET PORT GROUP for shared port group groupname not performed; device device is not a real OSA-Express device.
• HCP3184E SET PORT GROUP for shared port group groupname not performed; all available devices on OSA PCHID pchid are already in use.
• HCP3186E [DEFINE VSWITCH GROUP | SET PORT GROUP | SET VSWITCH GROUP] for shared port group groupname not performed; devices on OSA PCHID pchid do not exist or are not available.
• HCP3194I Creating [ VSWITCH switchnm | PORT GROUP groupname ] now that the IVL Virtual switch is connected.
• HCP3197E SET PORT GROUP not performed; system systemname is busy executing a cross IVL Domain CP command.
• HCP3198E SET PORT GROUP not performed; an unexpected internal error occurred.
• HCP3200E SET PORT GROUP for shared port group groupname not performed; port groups cannot span CPCs.
• HCP3220E SET PORT GROUP for shared port group groupname not performed; OSA PCHID pchid is used by another port group.
• HCP3223E SET PORT GROUP for port group groupname not performed; COLLABORATIVE is not allowed for an exclusive port group.
• HCP3225E IVL DOMAIN does not support Collaborative Load Balancing.
• HCP6704E Missing token at end of line
• HCP6706E Invalid device address - rdev
• HCP6706E Invalid device address or port number - {vdev | portnumber}
• HCP6706E Invalid groupname - groupname