VIPADYNAMIC - VIPARANGE statement

Defines or deletes a subnet for which dynamic VIPA (DVIPA) activation requests, by way of a BIND, SIOCSVIPA IOCTL, or SIOCSVIPA6 IOCTL are honored. For guidance on defining this statement, see the APF-authorized application instance (ioctl) information and movement of unique application-instance (BIND) information in z/OS Communications Server: IP Configuration Guide.

Guidelines:
  • VIPARANGE statements that are common to more than one stack should be defined in a common file and included in the appropriate stack profiles. This can help you avoid keying errors that could result in a failure to activate an application on a stack.
  • Ensure that the DVIPAs (by IP address or subnet) in the VIPARANGE statements do not overlap the non-DVIPAs in the sysplex such that the created DVIPAs can appear as duplicate IP addresses. It is best to define the DVIPAs by IP address in the VIPARANGE statements when the DVIPAs are in the same subnet as the non-DVIPAs across the stacks in a sysplex. This can help you avoid potential network connectivity outages on network access interfaces where a registered non-DVIPA in one stack can get overridden by the created DVIPA with a duplicate IP address for a different stack upon registration.

Rule: For any DVIPA creation request, the most specific VIPARANGE statement match (IP address and subnet) is used.

Restriction: Up to 4096 VIPARANGE statements can be defined to one stack.

Syntax

Rule: Specify the parameters in the order shown here.

Read syntax diagramSkip visual syntax diagramVIPARange DEFINEDELEte MOVEable NONDISRUPTiveMOVEable DISRUPTiveaddress_maskipv4_addrMOVEable NONDISRUPTiveipv6_intfnameipv6_addr/prefix_len SAF  resname ZCX

Parameters

DEFINE
Specifies that this definition is to be added to the list of defined VIPARANGE definition statements. This is the default value.
DELETE
Specifies that this definition (with the same address_mask and ipv4_addr values or the same ipv6_intfname and ipv6_addr/prefix_len values) is to be removed from the list of allowable ranges for IOCTL or BIND implicit dynamic VIPA activation.

Tip: A VIPARANGE DELETE statement does not affect currently existing dynamic VIPAs in the range being deleted.

MOVEABLE NONDISRUPTIVE
Specifies an immediate nondisruptive movement of a dynamic VIPA from one stack to another stack. This value indicates that a dynamic VIPA in this VIPARANGE statement can be moved to another stack when that stack requests ownership of the DVIPA as the stack creates it; this occurs when an application binds to that DVIPA, the MODDVIPA utility is used to create the DVIPA through the SIOCSVIPA or SIOCSVIPA6 ioctl, or the application directly issues the SIOCSVIPA or SIOCSVIPA6 ioctl. The new owning stack forwards packets for any existing connections to the original stack in order that the existing connections are not disturbed. All new connection requests are directed to the new owning stack. The NONDISRUPTIVE option is the only option supported for IPv6 addresses and is the default value for IPv4 addresses.
MOVEABLE DISRUPTIVE
Indicates that nondisruptive movement does not occur for dynamic VIPAs created within this range on this stack. This option is not supported for IPv6.

A subsequent BIND on another stack for the same VIPA address fails. The VIPA on the original stack remains unchanged.

A subsequent SIOCSVIPA ioctl on another stack succeeds, and the VIPA on this stack is deleted. Any connections to the VIPA on this stack are broken.

address_mask
Provides the subnet mask that, when logically ANDed with the ipv4_addr value, determines the VIPARANGE subnet.

The address mask is specified in standard dotted decimal format for IP addresses. The address_mask variable is used only for IPv4. A subnet mask of 0.0.0.0 is not valid.

Rules: This value must meet the normal mask definition rules:
  • When converted to binary, the most significant bit must be a 1.
  • When converted to binary, all bits less significant than (to the right of) the first 0 encountered from the left must also be 0.
In other words, the IP addresses in the subnet must be a single contiguous range of IP addresses.
ipv4_addr
This determines a VIPARANGE subnet value when ANDed with the specified address mask. Any dynamic VIPA that is requested by way of IOCTL or by BIND to a specific address must match a defined VIPARANGE subnet value, after the dynamic VIPA has been logically ANDed with the corresponding address mask. The network address or network ID of the VIPARANGE subnet, which is the lowest possible address in the range, is excluded. The broadcast address of the VIPARANGE subnet, which is the highest address in the range, is also excluded.
ipv6_intfname
The interface name is used only for IPv6. This interface name is used for each DVIPA defined by this VIPARANGE statement.
ipv6_addr
This determines a VIPARANGE subnet value when used with the prefix_len value. Any dynamic VIPA that is requested by way of IOCTL or by BIND to a specific address must match a defined VIPARANGE subnet value, after the dynamic VIPA has been logically ANDed with the corresponding network prefix. The network address or network ID of the VIPARANGE subnet, which is the lowest possible address in the range, is excluded. The highest address in the range is also excluded.
/prefix_len
The number of bits in the ipv6_addr value defines the prefix. The range is 1 - 128.
SAF resname
Specifies the final qualifier of a System Authorization Facility (SAF) resource name. An application can create a dynamic VIPA in the specified VIPARANGE subnet if the user ID that is associated with the application is given READ access to the resource. The maximum length for the resname value is 8 characters.
Restriction: You can not specify a 1-character value of 0 (zero) for resname.

For an application to create a dynamic VIPA in the VIPARANGE subnet, the user ID associated with the application must have access to the appropriate SAF resource:

  • For an application that issues a bind socket call, the user ID must have READ access to the resource EZB.BINDDVIPARANGE.sysname.tcpname.resname.
  • For an application that issues a SIOCSVIPA or SIOCSVIPA6 ioctl call or invokes the MODDVIPA utility (which issues the SIOCSVIPA or SIOCSVIPA6 ioctl call on behalf of the user), the user ID must have READ access to the resource EZB.MODDVIPA.sysname.tcpname.resname.
where:
  • EZB.BINDDVIPARANGE and EZB.MODDVIPA are constant
  • sysname is the value of the MVS™ &SYSNAME. system symbol
  • tcpname is the name of the procedure used to start the TCP stack
  • resname is the 1-8 character resource name that follows the SAF keyword on the VIPARANGE statement
Results:
  • If the SAF keyword is specified and the user ID has READ access to the resource, the bind or ioctl call is processed.
  • If the SAF keyword is specified and the user ID does not have READ access to the resource, the bind or ioctl call fails.
  • If the SAF keyword is specified and the resource profile is not defined, the bind or ioctl call fails.
  • Generic profiles are handled in the following ways:
    • All of the following profile specifications that include wildcard values match the EZB.BINDDVIPARANGE.sysname.tcpname.resname resource profile name:
      • EZB.BINDDVIPARANGE.*.*
      • EZB.BINDDVIPARANGE.**
      • EZB.BINDDVIPARANGE.*.*.*
    • All of the following profile specifications that include wildcard values match the EZB.MODDVIPA.sysname.tcpname.resname resource profile name:
      • EZB.MODDVIPA.*.*
      • EZB.MODDVIPA.**
      • EZB.MODDVIPA.*.*.*

    The most specific match to a resource profile is always used.

For more information about defining a security profile for SIOCSVIPA, SIOCSVIPA6, and MODDVIPA and about defining a security profile for binding to DVIPAs in the VIPARANGE statement, see z/OS Communications Server: IP Configuration Guide.

Start of changeZCXEnd of change
Start of changeThis indicates that this VIPARANGE is to be reserved for use by z/OS® Container Extensions function. Dynamic VIPAs within this VIPARANGE subnet cannot be created by any other application by way of a Start of changeBIND, SIOCSVIPA IOCTL, SIOCSVIPA6 IOCTL, or MODDVIPA utility.End of change For more information about z/OS Container Extensions, see z/OS Communications Server: IP Configuration Guide.
Tip: Avoid configuring VIPARANGE statements with ZCX from overlapping with VIPARANGE subnets without the ZCX keyword.
Restriction: Dynamic VIPAs created from the VIPARANGE subnet with ZCX will not move from one stack to another stack. The MOVEable parameter is ignored.
End of change

Steps for modifying

  • To remove a VIPARANGE statement, use one of the following:
    VIPARANGE DELETE mask ipv4_addr 
    VIPARANGE DELETE ipv6_intfname ipv6_addr/prefix_len 
  • To change the subnet for a VIPARANGE statement, use one of the following two methods:
    • To replace the subnet, use one of the following:
      VIPARANGE DELETE original_mask original_ipv4_addr
      VIPARANGE new_mask new_ipv4_addr
      VIPARANGE DELETE ipv6_intfname ipv6_addr/prefix_len 
      VIPARANGE ipv6_intfname ipv6_addr/new_prefix_len 
    • To enlarge the subnet, use one of the following:
      VIPARANGE mask2 ipv4_addr2 
      VIPARANGE ipv6_intfname ipv6_addr/prefix_len2 
    This configures a VIPARANGE statement where mask2 ANDed with ipv4_addr2 determines a subnet that overlaps or includes the original one.
    Alternatively, you can enlarge the subnet by using one of the following:
    VIPARANGE mask2 ipaddr2
    VIPARANGE ipv6_intfname ipv6_addr/prefix_len2

    This configures a VIPARANGE statement where mask2 ANDed with ipaddr determines a subnet that overlaps or includes the original subnet.

  • Start of changeThe value of ZCX for a VIPARANGE statement cannot be changed without first removing the existing VIPARANGE statement and then redefining it. See the step To remove a VIPARANGE statement, use one of the following: within this section for more details.End of change

Examples

VIPARANGE DEFINE 255.255.255.0 10.10.10.1
VIPARANGE DEFINE 255.255.255.255 10.10.10.210 SAF APPL1
VIPARANGE DEFINE 255.255.255.255 10.10.10.211 SAF APPL2
VIPARANGE 255.255.255.0 9.67.240.0  
VIPARANGE V6DVIPARANGE 2000::9:67:270:0/112