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.

Guideline: 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.

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

Restriction: There is a limit of 1024 VIPARANGE definition statements.

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 implicit 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.

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 prefix defined by the prefix_len value.

Any dynamic VIPA that is requested by way of IOCTL or by implicit 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.

/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.

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.

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.