SYSPLEXPORTS

Whenever two or more application instances use the same source IP address and initate connections to the same destination IP address and port, sysplex-wide coordination of assignment of ephemeral ports is required so that the 4-tuple for each connection remains unique. As long as the source IP address is on a single stack, this coordination is not a problem because the stack manages assignment of ephemeral ports. However, with sysplex distributor applications, multiple application instances might need to initiate connections using the same distributed DVIPA, potentially to the same destination IP address and port, so uniqueness of the connection 4-tuples cannot be guaranteed unless the stacks collaborate across the sysplex for ephemeral port assignment for distributed DVIPAs. This can be done by adding the optional SYSPLEXPORTS parameter to the VIPADISTRIBUTE statement.

You must specify the SYSPLEXPORTS parameter on the first VIPADISTRIBUTE statement processed for a particular DVIPA. SYSPLEXPORTS cannot be enabled after a DVIPA has been configured for distribution. After you have enabled SYSPLEXPORTS, you cannot disable it until you have deleted all distribution for the DVIPA. If you want to specify the SYSPLEXPORTS parameter on a VIPADISTRIBUTE statement in the data set referenced by a VARY TCPIP,,OBEYFILE command, you must delete the existing VIPADISTRIBUTE statement in one data set, and then add the statement back in a second data set. An example of the contents of a data set that deletes an existing distributed DVIPA is as follows:

VIPADYNAMIC 
VIPADISTRIBUTE DELETE 
10.1.1.1 PORT 20 21 
DESTIP ALL
ENDVIPADYNAMIC
; 

An example of the contents of a data set that adds SYSPLEXPORTS to this DVIPA is as follows:

VIPADYNAMIC
VIPADISTRIBUTE DEFINE SYSPLEXPORTS 
10.1.1.1 PORT 20 21 
DESTIP ALL
; 
ENDVIPADYNAMIC

When a distributed DVIPA can be active on more than one target stack, SYSPLEXPORTS can be specified to cause the stacks to collaborate in the assignment of ephemeral ports for outbound initiated TCP connections. This ensures that two different connections do not end up with the same connection 4-tuple.

At profile processing time, a stack with a profile that contains a SYSPLEXPORTS parameter on a VIPADISTRIBUTE statement connects to the coupling facility SYSPLEXPORTS structure containing sysplex port assignment information. The name of this structure is in the format EZBEPORTvvtt, where vv is the 2-character VTAM® group ID suffix specified on the XCFGRPID start option, and tt is the TCP group ID suffix specified on the GLOBALCONFIG statement in the TCP/IP profile. If no VTAM group ID suffix is specified, but a TCP/IP group ID suffix is specified, vv is 01. If no TCP/IP group ID suffix is specified, but a VTAM group ID suffix is specified, tt is not present. If neither group ID suffix is specified, both vv and tt are not present. The structure will be a list structure with an entry for each DVIPA address that has a VIPADISTRIBUTE statement with SYSPLEXPORTS specified anywhere in the sysplex (or within the subplex, if subplexing is being used). The first stack to connect to the EZBEPORTvvtt structure for a particular DVIPA creates an entry for that DVIPA in the coupling facility. The stack creates and initializes, in the EZBEPORTvvtt structure, a sublist for this DVIPA of assigned ports for this stack. For more information about setting up EZBEPORTvvtt, see Setting up the sysplex environment for VTAM and TCP/IP functions in z/OS Communications Server: SNA Network Implementation Guide.

The stack also maintains a list of allowable ephemeral ports on this stack. These ports are not reserved for TCP by a PORT or PORTRANGE statement, are not reserved in a GLOBALCONFIG EXPLICITBINDPORTRANGE statement, and are in the range provided on the EPHEMERALPORTS parameter of the TCPCONFIG statement. The default ephemeral port range is 1024 – 65535. Only port number values in the list maintained by the stack are allocated for use by the SYSPLEXPORTS DVIPAs of the stack. Because this list is unique to a particular stack and determined by stack configuration, a port number that is not permissible for one stack because it is reserved might be allowable for another stack, and could actually be allocated for use by that stack for a SYSPLEXPORTS DVIPA.

Under the following conditions, the first time that an application issues a TCP bind() with port 0 or a connect() request, TCP/IP receives an unassigned group of ports from the coupling facility structure that are allowable as ephemeral ports on the stack (not otherwise reserved by PORT or PORTRANGE or limited by the EPHEMERALPORTS parameter):

• The bind() or connect() request uses a distributed DVIPA as the source address (whether by the application explicitly binding the socket to the designated DVIPA or by the stack assigning the TCPSTACKSOURCEVIPA address).
• The distributed DVIPA is designated as SYSPLEXPORTS.

The stack will assign an ephemeral port from the obtained group as the source port for the TCP connection request, and the coupling facility structure will be updated to show the group of ports as assigned. The stack will assign ports from within this group for each subsequent equivalent bind() request. If all the ports within the group are used, the stack will obtain another group of ports from the coupling facility.

That is, a single z/OS® TCP stack supports no more than about 63000 simultaneously active, locally initiated TCP connections whose source ports are ephemeral ports assigned by the stack. If a stack is unable to successfully obtain an ephemeral port from the coupling facility for a SYSPLEXPORTS DVIPA, the connection request is terminated with an error indication.

If you send a connection request to a distributed DVIPA that is enabled for SYSPLEXPORTS and a random ephemeral port with no associated listener, then this connection will time out.

For information on diagnosing SYSPLEXPORTS problems, see z/OS Communications Server: IP Diagnosis Guide.