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.
- 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.
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.
- 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.
- 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.
- All of the following profile specifications that include wildcard values match the
EZB.BINDDVIPARANGE.sysname.tcpname.resname
resource profile name:
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.
- ZCX
- This 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 BIND, SIOCSVIPA
IOCTL, SIOCSVIPA6 IOCTL, or MODDVIPA utility. 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.
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
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.
- To replace the subnet, use one of the following:
- The 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.
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