INTERFACE - IPAQENET OSA-Express QDIO interfaces statement

Parameters

intf_name

The name of the interface. The maximum length is 16 characters.

Requirement: This name must be different than the name specified for the PORTNAME parameter.

DEFINE

Specifies that this definition is to be added to the list of defined interfaces.

DELETE

Specifies that this definition is to be deleted from the list of defined interfaces. The intf_name value must be the name of an interface previously defined by an INTERFACE statement. Specifying INTERFACE DELETE deletes the home IP address for the interface.

IPAQENET

Indicates that the interface uses the interface based on IP assist, which belongs to the QDIO family of interfaces, and uses the Ethernet protocol.

CHPIDTYPE

An optional parameter indicating the CHPID type of the OSA-Express QDIO interface.

OSD

Indicates an external data network type. This is the default value.

OSX

The intraensemble data network. See z/OS Communications Server: IP Configuration Guide for information about requirements necessary to make an OSX work.

Rule: You must specify an OSD interface definition to make this interface eligible to use Shared Memory Communications over Remote Direct Memory Access (SMC-R) or Shared Memory Communications - Direct Memory Access (SMC-D).

CHPID chpid

This parameter applies only to interfaces of CHPIDTYPE OSX and is used to specify the CHPID for the interface. This value is a 2-character hexadecimal value (00 - FF).

PORTNAME portname

Use this parameter to specify the PORT name that is in the TRLE definition for the QDIO interface. The TRLE must be defined as MPCLEVEL=QDIO. For details about defining a TRLE, see z/OS Communications Server: SNA Resource Definition Reference.

Requirement: The portname value must be different than the name specified for intf_name.

IPADDR

ipv4_address

The home IP address for this interface.

Requirement: The IP address must be specified in dotted decimal form.

num_mask_bits

An integer value in the range 0 - 32 that represents the number of leftmost significant bits for the subnet mask of the interface. This value also controls how ARP processing for VIPAs is handled for this interface. When you specify a nonzero value, the TCP/IP stack informs OSA to perform ARP processing for a VIPA only if the VIPA is configured in the same subnet as the OSA (as defined by this subnet mask). The default is 0 for CHPIDTYPE OSD. This parameter is required for CHPIDTYPE OSX..

Requirement: If you are configuring multiple IPv4 VLAN interfaces to the same OSA-Express feature, then you must specify a nonzero value for the num_mask_bits variable for each of these interfaces and the resulting subnet must be unique for each of these interfaces.

Rule: If you are using OMPROUTE and OMPROUTE is not configured to ignore this interface, ensure that the subnet mask value that you define on this parameter matches the subnet mask used by OMPROUTE for this interface. The subnet mask used by OMPROUTE is the subnet mask value defined on the corresponding OMPROUTE statement (OSPF_INTERFACE, RIP_INTERFACE, or INTERFACE) for this interface. If no OMPROUTE statement is specified for this interface, the subnet mask used by OMPROUTE is the class mask for the interface IP address.

TEMPIP

Specifies that the interface starts with an IP address of 0.0.0.0. The interface can be used for broadcast traffic. This parameter applies only to interfaces that are defined with CHPIDTYPE OSD.

Guideline: Use TEMPIP interfaces in a unit test environment to support an application that provides a DHCP client, such as IBM Rational Developer for System z® Unit Test feature (Rdz-UT). For more information about configuring a TEMPIP interface, see Using TEMPIP interfaces in z/OS Communications Server: IP Configuration Guide.

NONROUTER

If a datagram is received at this interface for an unknown IP address, the datagram is not routed to this TCP/IP instance. This is the default value.

The PRIROUTER and SECROUTER parameters interact with the VLANID parameter. See the VLANID parameter definition to understand this relationship.

Rule: This keyword applies only to interfaces of CHPIDTYPE OSD and is ignored if the VMAC parameter is configured on the INTERFACE statement.

PRIROUTER

If a datagram is received at this interface for an unknown IP address and is not destined for a virtual MAC, the datagram is routed to this TCP/IP instance. This parameter interacts with the VLANID parameter. See the VLANID parameter definition to understand this relationship.

Rule: This keyword applies only to interfaces of CHPIDTYPE OSD and is ignored if the VMAC parameter is configured on the INTERFACE statement.

SECROUTER

If a datagram is received at this interface for an unknown IP address and is not destined for a virtual MAC, and there is no active TCP/IP instance defined as PRIROUTER, then the datagram is routed to this TCP/IP instance. This parameter interacts with the VLANID parameter. See the VLANID parameter definition to understand this relationship.

Rule: This keyword applies only to interfaces of CHPIDTYPE OSD and is ignored if the VMAC parameter is configured on the INTERFACE statement.

VLANID id

Specifies the decimal virtual LAN identifier to be assigned to the OSA-Express interface. This field should be a virtual LAN identifier recognized by the switch for the LAN that is connected to this OSA-Express interface. The valid range is 1 - 4094. This parameter is optional for CHPIDTYPE OSD and required for CHPIDTYPE OSX.

Guideline: Installation configuration on other platforms or related to Ensemble networking can limit the maximum VLANID of 4096.

The VLANID parameter interacts with the PRIROUTER and SECROUTER parameters. If you configure both the VLANID parameter and either PRIROUTER or SECROUTER parameter, then this TCP/IP instance acts as a router for this VLAN (ID) only. Datagrams that are received at this device instance for an unknown IP address and are not destined for a virtual MAC are routed only to this TCP/IP instance if it is VLAN tagged with this VLAN ID. For more information about VLANID parameter interactions, see OSA VLAN in z/OS Communications Server: IP Configuration Guide.

Rule: If you are configuring multiple VLAN interfaces to the same OSA-Express feature, then you must specify the VMAC parameter (with the default ROUTEALL attribute) on the INTERFACE statement for each of these interfaces.

Restriction: The stack supports a maximum of 32 IPv4 VLAN interfaces to the same OSA-Express port. Additional VLANID limitations might exist if this interface can be used with Shared Memory Communications over Remote Direct Memory Access (SMC-R). See VLANID considerations in z/OS Communications Server: IP Configuration Guide for details.

INBPERF

An optional parameter that indicates how processing of inbound traffic for the QDIO interface is performed.

There are three supported static settings that indicate how frequently the adapter should interrupt the host for inbound traffic: BALANCED, MINCPU, and MINLATENCY. The static settings use static interrupt-timing values. The static values are not always optimal for all workload types or traffic patterns, and the static values cannot account for changes in traffic patterns.

There is also one supported dynamic setting (DYNAMIC). This setting causes the host (stack) to dynamically adjust the timer-interrupt value while the device is active and in use. This function exploits an OSA hardware function called Dynamic LAN Idle. Unlike the static settings, the DYNAMIC setting reacts to changes in traffic patterns and sets the interrupt-timing values to maximize throughput. The dynamic setting does not incur additional CPU consumption that might be produced when you specify any of the static settings. In addition, the DYNAMIC setting uses the OSA Dynamic Router Architecture function to enable QDIO inbound workload queues for specific inbound traffic types.

Result: When you specify OLM on the INTERFACE statement, the INBPERF parameter is ignored and the statement takes the value DYNAMIC.

Valid values for INBPERF are:

BALANCED

This setting uses a static interrupt-timing value, which is selected to achieve reasonably high throughput and reasonably low CPU consumption. This is the default value for CHPIDTYPE OSD. .

DYNAMIC

This setting causes the host to dynamically signal the OSA-Express feature to change the timer-interrupt value, based on current inbound workload conditions. The DYNAMIC setting is effective only for OSA-Express2 or later features on at least an IBM System z9® that supports the corresponding Dynamic LAN Idle function. See the 2097DEVICE Preventive Service Planning (PSP) bucket for more information about the OSA-Express3 adapter that supports this function. The DYNAMIC setting should outperform the other three static settings for most workload combinations. This is the default value for CHPIDTYPE OSX.

If the DYNAMIC setting is specified for an OSA-Express adapter that does not support the dynamic LAN Idle function, the stack reverts to using the BALANCED setting.

WORKLOADQ | NOWORKLOADQ

This subparameter controls the QDIO inbound workload queueing function for the interface. QDIO inbound workload queueing is effective only for OSA-Express features in QDIO mode that support the corresponding Data Router Architecture. OSA-Express features that support workload queueing do not necessarily support workload queueing for all possible traffic types. For more information about the QDIO inbound workload queueing function and the OSA-Express features that support it, see QDIO inbound workload queueing in z/OS Communications Server: IP Configuration Guide.

NOWORKLOADQ

Specifies that QDIO inbound workload queueing is not enabled for inbound traffic. All inbound traffic for this interface uses a single input queue. This is the default value.

WORKLOADQ

Specifies that QDIO inbound workload queueing (IWQ) is enabled for inbound traffic.

If the WORKLOADQ subparameter is specified, QDIO inbound workload queueing is enabled for specific inbound traffic types. A primary input queue is reserved for all other traffic types.

Ancillary input queues (AIQs) are created for the following inbound traffic types when supported by the OSA-Express feature:

• Sysplex distributor
• Streaming workloads (for example FTP)
• Enterprise Extender (EE)
• IP Security (IPSec)
• IBM z/OS Container Extensions (zCX)

Requirement: You must specify the VMAC parameter with WORKLOADQ to enable QDIO inbound workload queueing.

Restrictions:

• Bulk-mode TCP connection registration is supported only in configurations in which a single inbound interface is servicing the bulk-mode TCP connection. If a bulk-mode TCP connection detects that it is receiving data over multiple interfaces, QDIO IWQ is disabled for the TCP connection and inbound data from that point forward is delivered to the primary input queue.
• QDIO IWQ does not apply for traffic that is sent over an OSA port that is shared by the receiving TCP/IP stack when an indirect route (where the next hop and destination IP address are different) is being used; this traffic is placed on the primary input queue. QDIO IWQ does apply when traffic on the shared OSA path uses a direct route (where the next hop and destination IP address are the same).

Guideline: The WORKLOADQ parameter requires an additional amount of fixed 4K CSM HVCOMMON storage per AIQ. The amount of storage consumed per AIQ is based on the amount of storage defined for READSTORAGE for this interface. The bulk AIQ is always backed with this additional CSM storage. The remaining AIQs are not backed by the additional CSM storage until the specific function (EE, SD, IPSec, or zCX) is used. The EE AIQ is backed by fixed 4K CSM DSPACE64 storage (instead of HVCOMMON). To verify the amount of CSM storage that is being used for each input queue, display the VTAM® TRLE name that is associated with the interface. The WORKLOADQ parameter also requires an additional 36K of ECSA per AIQ.

Tip: The additional CSM storage consumed by each OSA interface using WORKLOADQ consumes fixed (real) storage. It is recommended that you verify that the additional fixed storage required by enabling WORKLOADQ (per OSA interface) will not approach any of the following limits:

• The CSM FIXED MAXIMUM value used by Communications Server (use the D NET, CSM command and see the CSM FIXED MAXIMUM value defined in IVTPRM00)
• The actual real storage available to this z/OS system (see D M=STOR or D M=HIGH)

If the WORKLOADQ setting is specified for an OSA-Express adapter that does not support the Data Router Architecture function, the stack reverts to using a single input queue.

MINCPU

This setting uses a static interrupt-timing value, which is selected to minimize host interrupts without regard to throughput. This mode of operation might result in minor queueing delays (latency) for packets flowing into the host, which is not optimal for workloads with demanding latency requirements.

MINLATENCY

This setting uses a static interrupt-timing value, which is selected to minimize latency (delay), by more aggressively sending received packets to the host. This mode of operation generally results in higher CPU consumption than the other three settings. Use this setting only if host CPU consumption is not an issue.

VMAC macaddr

Specifies the virtual MAC address, which can be represented by 12 hexadecimal characters. The OSA-Express device uses this address rather than the physical MAC address of the device for all IPv4 packets sent to and received from this TCP/IP stack. For CHPIDTYPE OSD, using a virtual MAC address is optional. For CHPIDTYPE OSX, using a virtual MAC address is required, so the VMAC parameter is the default

The macaddr value is optional. The macaddr value is optional for CHPIDTYPE OSD and cannot be specified for CHPIDTYPE OSX. If you do not code the macaddr value, then the OSA-Express device generates a virtual MAC address. If you do code the macaddr value, it must be defined as a locally administered individual MAC address. This means the MAC address must have bit 6 (the universal or local flag U bit) of the first byte set to 1 and bit 7 (the group or individual flag G bit) of the first byte set to 0. The second hexadecimal character must be 2, 6, A, or E. The bit positions within the 12 hexadecimal characters are indicated as follows:

|               1|1              3|3              4|
|0              5|6              1|2              7|
+----------------+----------------+----------------+
|xxxxxxUGxxxxxxxx|xxxxxxxxxxxxxxxx|xxxxxxxxxxxxxxxx|
+----------------+----------------+----------------+

Rules:

• The same virtual MAC address generated by the OSA-Express device during interface activation remains in effect for this OSA-Express for this TCP/IP stack, even if the interface is stopped or becomes inoperative (INOPs). A new virtual MAC address is generated only if the INTERFACE statement is deleted and redefined or if the TCP/IP stack is recycled.
• The NONROUTER, PRIROUTER, and SECROUTER parameters are ignored for an OSA-Express interface if the VMAC parameter is configured on the INTERFACE statement.

Guideline: Unless the virtual MAC address representing this OSA-Express device must remain the same even after TCP/IP termination and restart, configure VMAC without a macaddr value and allow the OSA-Express device to generate it. This guarantees that the VMAC address is unique from all other physical MAC addresses and from all other VMAC addresses generated by any OSA-Express feature.

ROUTEALL

Specifies that all IP traffic destined to the virtual MAC is forwarded by the OSA-Express device to the TCP/IP stack. This is the default value. See the router information in z/OS Communications Server: IP Configuration Guide for more details.

ROUTELCL

Specifies that only traffic destined to the virtual MAC and whose destination IP address is registered with the OSA-Express device by this TCP/IP stack is forwarded by the OSA-Express. See the router information in z/OS Communications Server: IP Configuration Guide for more details.

SMCR | NOSMCR

Specifies whether this interface can be used with Shared Memory Communications over Remote Direct Memory Access (SMC-R) for external data network communications.

NOSMCR

Specifies that this interface cannot be used for new TCP connections with SMC-R for external data network communications.

SMCR

Specifies that this interface can be used for new TCP connections with SMC-R for external data network communications. This is the default setting.

Rules:

• SMCR and NOSMCR are valid with CHPIDTYPE OSD definitions only.
• SMCR has no effect unless at least one Peripheral Component Interconnect Express (PCIe) function ID (PFID) value is specified by using the PFID subparameter of the SMCR parameter on the GLOBALCONFIG statement.
• SMCR has no effect unless a nonzero subnet mask is configured on the INTERFACE statement.

Guideline: If you enable Multipath and equal-cost interfaces are associated with different IP subnets, enabling SMC for some of, but not all, the interfaces can cause unpredictable SMC usage. You must specify either SMCR or NOSMCR on all equal-cost interfaces.

SMCD | NOSMCD

Specifies whether this interface can be used with Shared Memory Communications - Direct Memory Access (SMC-D).

NOSMCD

Specifies that this interface cannot be used for new TCP connections with SMC-D.

SMCD

Specifies that this interface can be used for new TCP connections with SMC-D. This is the default setting.

Rules:

• SMCD and NOSMCD are valid with CHPIDTYPE OSD definitions only.
• SMCD has no effect unless a nonzero subnet mask is configured on the INTERFACE statement.

Guideline: If you enable Multipath and equal-cost interfaces are associated with different IP subnets, enabling SMC for some of, but not all, the interfaces can cause unpredictable SMC usage. You must specify either SMCD or NOSMCD on all equal-cost interfaces.

SOURCEVIPAINTERFACE vipa_name

Specifies which previously-defined static VIPA interface is used for SOURCEVIPA (when IPCONFIG SOURCEVIPA is in effect). The vipa_name value is the interface name (or link name) for a VIRTUAL interface. This parameter is optional.

Requirement: The VIRTUAL interface must be defined prior to specifying this INTERFACE statement to the TCP/IP stack. It must either already be defined, or the INTERFACE statement (or DEVICE and LINK statements) that define the static VIPA must precede this INTERFACE statement in the profile data set.

Tip: The SOURCEVIPAINTERFACE setting can be overridden. See the information about Source IP address selection in z/OS Communications Server: IP Configuration Guide for the hierarchy of ways that the source IP address of an outbound packet is determined.

MTU num

The maximum transmission unit (MTU), in bytes. This value can be in the range 576 - 8992. The minimum MTU for IPv4 is 576. The stack takes the minimum of the configured value and the value supported by the device (returned by OSA).

The MTU default, which depends on the value that is supported by the device, is the following value:

• Gigabit Ethernet default MTU = 8992
• Fast Ethernet default MTU = 1492

The MTU default is 1492 for Fast Ethernet; otherwise, it is 8992.

Rule: If you are using OMPROUTE and OMPROUTE is not configured to ignore this interface, ensure that the MTU that you define on this parameter matches the MTU used by OMPROUTE for this interface. The MTU used by OMPROUTE is the MTU value defined on the corresponding OMPROUTE statement (OSPF_INTERFACE, RIP_INTERFACE, or INTERFACE) for this interface. If an MTU value is not defined on the corresponding OMPROUTE statement for this interface or if no OMPROUTE statement is specified for this interface, the MTU used by OMPROUTE is the minimum MTU for IPv4 (576).

Tip: See z/OS Communications Server: IP Configuration Guide, in section Maximum transmission unit considerations, for additional information about how TCP/IP uses the MTU to determine the largest size frame to send.

READSTORAGE

An optional parameter indicating the amount of fixed storage that z/OS Communications Server should keep available for read processing for each input queue for this interface. Multiple input queues are used when WORKLOADQ is enabled. See description of the WORKLOADQ parameter for more details.

Use the QDIOSTG VTAM start option to specify a value that applies to all OSA-Express adapters in QDIO mode. You can use the READSTORAGE keyword to override the global QDIOSTG value for this adapter based on the inbound workload that you expect over this interface on this stack. The valid values for READSTORAGE are:

GLOBAL

The amount of storage is determined by the QDIOSTG VTAM start option. This is the default value.

MAX

Use this value if you expect a heavy inbound workload over this interface.

AVG

Use this value if you expect a medium inbound workload over this interface.

MIN

Use this value if you expect a light inbound workload over this interface.

Tip: The amount of storage which corresponds to each of these values is different for an OSA with at least 25 GbE of bandwidth than for an OSA with less than 25 GbE of bandwidth. See QDIOSTG start option in z/OS Communications Server: SNA Resource Definition Reference for details about exactly how much storage is allocated by z/OS Communications Server for each of these values.

IPBCAST

Specifies that the interface both sends and receives IP broadcast packets. If this parameter is not specified, no IP broadcast packets are sent or received on this interface.

SECCLASS security_class

Use this parameter to associate a security class for IP filtering with this interface. For traffic over the interface to match a filter rule, the filter rule must have the same security class value as the interface or a value of 0. You can specify filter rules in the TCP/IP profile or in an IP security policy file that is read by the Policy Agent. Filter rules can include a security class specification on the IpService statement in an IP Security policy file or on the SECCLASS parameter on the IPSECRULE statement in the TCP/IP profile.

Valid security classes are identified as a number in the range 1 - 255. The default value is 255. For more information about security class values, see z/OS Communications Server: IP Configuration Guide.

The TCP/IP stack ignores this value if IPSECURITY is not specified on the IPCONFIG statement.

MONSYSPLEX | NOMONSYSPLEX

Specifies whether sysplex autonomics should monitor the interface's status.

NOMONSYSPLEX

Specifies that sysplex autonomics should not monitor the interface's status. This is the default value.

MONSYSPLEX

Specifies that sysplex autonomics should monitor the interface's status.

Restriction: The MONSYSPLEX attribute is not in effect unless the MONINTERFACE keyword is specified on the GLOBALCONFIG SYSPLEXMONITOR profile statement. The presence of dynamic routes over this interface is monitored if the DYNROUTE keyword is also specified on the GLOBALCONFIG SYSPLEXMONITOR profile statement.

DYNVLANREG | NODYNVLANREG

This parameter controls whether or not the VLAN ID for this interface is dynamically or statically registered with the physical switch on the LAN.

Restriction: This parameter is applicable only if a VLAN ID is specified on the statement.

Dynamic registration of VLAN IDs is handled by the OSA-Express feature and the physical switch on your LAN. Therefore, in order for the DYNVLANREG parameter to be effective, both must be at a level that provides the necessary hardware support for dynamic VLAN ID registration. After the interface is active, you can view the Netstat DEvlinks/-d report output to determine whether your OSA-Express feature can support VLAN dynamic registration. This Netstat report also displays whether dynamic VLAN ID registration has been configured for the interface.

NODYNVLANREG

Specifies that if a VLAN ID is configured for this interface, it must be manually registered with the physical switches on the corresponding LAN. This is the default value. If this parameter is specified without a VLAN ID, then it is ignored.

DYNVLANREG

Specifies that if a VLAN ID is configured for this interface, it is dynamically registered with the physical switches on the corresponding LAN. If this parameter is specified without a VLAN ID, then warning message EZZ0056I is issued and the NODYNVLANREG setting is used instead.

OLM | NOOLM

An optional parameter indicating whether an OSA-Express adapter operates in optimized latency mode.

NOOLM

Specifies that the OSA-Express adapter should not operate in optimized latency mode. This is the default value.

OLM

Specifies that the OSA-Express adapter operates in optimized latency mode (OLM). Optimized latency mode optimizes interrupt processing for both inbound and outbound data. Use this mode for workloads that have demanding latency requirements. Because this mode can provide significant increases of throughput, particularly for interactive, non-streaming workloads. For more information about optimized latency mode, see the optimized latency mode topic in z/OS Communications Server: IP Configuration Guide.

Guidelines:

• Because of the operating characteristics of optimized latency mode, you might need to change your configuration to direct traffic to particular OSA-Express write priority queues and to limit the number of concurrent users sharing an OSA-Express configured for optimized latency mode. For more information about OLM, see the optimized latency mode topic in z/OS Communications Server: IP Configuration Guide.
• The optimized latency mode function targets a z/OS environment with a high-volume, interactive workloads. Although optimized latency mode can compensate for some mixing of workloads, an excessive amount of high-volume streaming workloads, such as bulk data or file transfer, can result in higher CPU consumption.

Restrictions:

• This function is limited to OSA-Express3 or later Ethernet features in QDIO mode that are running with an IBM System z10 or later. See the 2097 DEVICE Preventive Service Planning (PSP) bucket for more information.
• Traffic that is either inbound over or being forwarded to an OSA-Express configured to use optimized latency mode is not eligible for the accelerated routing function provided by HiperSockets Accelerator and QDIO Accelerator.
• For an OSA-Express configured to use optimized latency mode, the stack ignores the configured or default INBPERF setting and uses the value DYNAMIC.

ISOLATE | NOISOLATE

Specifies whether packets should be directly routed between TCP/IP stacks that share the OSA adapter.

NOISOLATE

Route packets directly between TCP/IP stacks sharing the OSA adapter. In this mode, if the next hop address was registered by another stack that is sharing the OSA adapter, then the OSA-Express adapter routes the packet directly to the sharing stack without putting the packet on the external LAN.

ISOLATE

Prevent OSA-Express from routing packets directly to another TCP/IP stack that is sharing the OSA adapter. In this mode, OSA-Express adapter discards any packets when the next hop address was registered by another stack that is sharing the OSA adapter. Packets can flow between two stacks that share the OSA only by first going through a router on the LAN. For more details, see the OSA-Express connection isolation information in z/OS Communications Server: IP Configuration Guide.

Tips:

• If you isolate an interface, there might be an adverse effect on latency.
• You can selectively apply OSA-Express connection isolation to individual virtual LANs.
• The OSA-Express adapter requires that both stacks sharing the port be non-isolated for direct routing to occur. Therefore, for traffic between two stacks sharing the OSA adapter, as long as at least one of the stacks is isolated, connection isolation is in effect for traffic in both directions between these stacks.

Restriction: This function is limited to OSA-Express2 or later Ethernet features in QDIO mode and running at least an IBM System z9 Enterprise Class (EC) or z9 Business Class (BC). See the 2094DEVICE, 2096DEVICE, 2097DEVICE, or 2098DEVICE Preventive Service Planning (PSP) bucket for more information.

Steps for modifying

See Summary of INTERFACE statements for modification information.

Related topics

• BEGINROUTES statement
• BSDROUTINGPARMS statement
• DEVICE and LINK - MPCIPA OSA-Express QDIO devices statement
• GLOBALCONFIG statement
• INTERFACE - IPAQENET6 OSA-Express QDIO interfaces statement
• SACONFIG statement
• START statement
• STOP statement