Configuring the unique application-instance scenario

The unique application-instance scenario ties a DVIPA to a specific instance of an application. To isolate errors in configuring applications, TCP/IP needs a mechanism to identify permissible DVIPAs. This is provided with one or more VIPARANGE statements. The VIPARANGE statement identifies a range of IP addresses which can be activated as DVIPAs by an application instance. Each TCP/IP stack can have up to 4096 VIPARANGE definition statements for both IPv4 and IPv6. The VIPARANGE statement consists of an IPv4 address and subnet mask, or an interface name and an IPv6 address and prefix length, and defines a subnet for DVIPAs. More than one VIPARANGE statement with different ranges can be defined on a TCP/IP. VIPARANGE does not itself cause any DVIPAs to be activated. Rather, DVIPAs are activated either by an application issuing a bind() for a specific IP address, by use of the SIOCSVIPA or SIOCSVIPA6 ioctl() command issued by an authorized application, or by the MODDVIPA utility.

When an application issues bind() for a specific IP address or an address was selected using the BIND keyword on the PORT statement, the receiving stack checks it against addresses in the HOME list. If the IP address has already been activated on this stack (whether for a physical device, a static VIPA, or a dynamic VIPA), the bind() execution is successful. If the IP address is not active on this TCP/IP, the current VIPARANGE statements are checked to see if the IP address falls within one of them. If an appropriate VIPARANGE is found, the IP address is activated as a DVIPA and the operation succeeds. If no appropriate VIPARANGE is found, or if the IP address is active elsewhere in the sysplex other than by a NONDISRUPTIVE bind(), the request fails and bind() returns EADDRNOTAVAIL.

When an authorized application issues the SIOCSVIPA or SIOCSVIPA6 ioctl() command to create a DVIPA, or when the MODDVIPA utility is executed in JCL or an OMVS script to activate a DVIPA on behalf of an application instance, the current VIPARANGE statements are checked to see whether the IP address falls within one of them. If an appropriate VIPARANGE is found, and the IP address is not currently active on this TCP/IP as a VIPADEFINE/VIPABACKUP dynamic VIPA, then the IP address is activated as a DVIPA. However if no appropriate VIPARANGE is found on this TCP/IP, or if the IP address is currently defined on this TCP/IP or configured elsewhere in the sysplex as a VIPADEFINE/VIPABACKUP dynamic VIPA, then the request fails with errno and errnojr set to indicate the reason for the failure and the utility ends with a nonzero condition code. See Dynamic VIPA creation results for more information.

Application-instance DVIPAs provide high availability features for applications and workloads that exploit them. The creation and movement of these DVIPAs is quite flexible, as it can be triggered without modification to the TCP/IP profile and without issuing TCP/IP operator commands. While this flexibility is useful, it can also present problems for the network administrator in determining when and how a DVIPA is activated on a TCP/IP stack.

To help alleviate these problems, TCP/IP provides auditing facilities to track the state changes of application-instance DVIPAs. When an application-instance DVIPA is created or deleted dynamically through an explicit bind, by executing the MODDVIPA utility or by invoking the SIOCSVIPA or SIOCSVIPA6 ioctl command, messages are issued (EZD1204I, EZD1205I, EZD1206I, or EZD1207I) to the job log of the TCP/IP started procedure and to the system log. These messages include the method (bind, ioctl, or MODDVIPA utility) used to create or delete the DVIPAs, and the job name at the time the bind, ioctl, or MODDVIPA utility was invoked. For more information about EZD1204I, EZD1205I, EZD1206I, and EZD1207I, see z/OS Communications Server: IP Messages Volume 2 (EZB, EZD).

The Netstat VIPADyn/-v report is enhanced for application-instance DVIPAs to include the job name and the time stamp that this DVIPA was activated on the local TCP/IP stack (either because it is the owner of the DVIPA or is a target for this DVIPA). For more details about Netstat VIPADyn/-v, see z/OS Communications Server: IP System Administrator's Commands.

In the unique application-instance scenario, each application instance is assigned a unique IP address as its DVIPA. Before defining individual DVIPAs, one or more blocks of IP addresses must be defined for these DVIPAs, and the individual DVIPAs must be defined from within the blocks. Each block should be represented as a subnet, so that a VIPARANGE statement can be defined for it.

Follow these steps when setting up any unique application instances:

1. For each application instance, assign a DVIPA from one of the blocks of IP addresses for this purpose. Do not assign an IP address which is also assigned to another application instance, or which is defined by VIPADEFINE for the multiple application-instance scenario. Configure the application to use this DVIPA [if it issues bind() for a particular IP address], or add a BIND parameter to the PORT reservation statement for the port of the application's listening socket to cause the listening socket to be bound to this DVIPA. Alternatively, add the MODDVIPA utility to the JCL or OMVS script and configure the MODDVIPA utility to activate the DVIPA before starting the application. When the application ends, use the MODDVIPA utility to delete the DVIPA.
2. For each application instance, determine on which stack the application instance will normally be executed and to which stacks the application instance could be moved in case of failure of the normal stack or the application itself. For each such stack, add a valid VIPARANGE statement to the profile.
   Note: The dynamic VIPA must be within the VIPARANGE subnet. The broadcast address and the net prefix cannot be used.
3. Perform steps 1 and 2 until all application instances have been allocated a unique DVIPA.

The application restart strategy should ensure that the worst-case failure scenario does not attempt to activate more than 4096 DVIPAs on a single stack. If such an attempt is made, activation of the 4097th DVIPA fails, with possible resulting loss of connectivity from clients to the server application.

Note: The limit of 4096 DVIPAs on a single TCP/IP applies to all DVIPAs, whether the DVIPAs are defined by the VIPADEFINE or VIPABACKUP configuration statements, by a VIPADISTRIBUTE statement on another stack, by a bind() call, or by executing the MODDVIPA utility.

Defining a single block makes the definition process easier, but also provides less individual control. Alternatively, because the smallest subnet consists of four IP addresses, defining a unique subnet for each DVIPA in this scenario wastes three other IP addresses that could have been used for DVIPAs.