Managing takeover IP address groups

Many IBM® i applications are accessed by using an IP address or a group of IP addresses.

In a traditional stand-alone environment, the IP address is directly tied to the IBM i system where the application is running. In a Db2® Mirror environment, the application could be running on either node. By making IP addresses switchable between the nodes, access to the application remains constant for users, regardless of the node where the application is running. These IP addresses are referred to as takeover IP addresses.

Db2 Mirror provides a GUI interface as well as SQL services to define and manage groups of takeover IP addresses. A takeover IP address group can be manually switched between nodes, which ends the TCP/IP interfaces on the current node and starts the TCP/IP interfaces on the other node. A takeover IP address group is automatically switched if its current node becomes unavailable or transitions to a state of BLOCKED. If the auto-switchback property associated with the takeover IP address group is set to Yes, the group will be automatically switched back to the preferred node when it transitions back to a state of ACTIVE.

An administrator can create up to 16 takeover IP address groups in a Db2 Mirror environment. Each group can contain up to 16 takeover IP addresses. Each group is associated with either SYSBAS or a database IASP and has a preferred node. This flexibility allows the definition of a takeover IP address group for each application when multiple applications could be running in SYSBAS or an IASP. It also allows defining groups with different preferred nodes for a situation where a certain application or group of users normally access an application on one node and other applications or users access the other Db2 Mirror node.

When an IP address is added to a group, the associated TCP/IP interface is started on the current node for the group if it is not already started. The interfaces will remain active on that node while the Db2 Mirror replication state is ACTIVE, unless the group is manually swapped to the other node. When a Db2 Mirror state change occurs for SYSBAS or a database IASP, the node or IASP which has transitioned to TRACKING state will take over any groups where the current node is now BLOCKED or unavailable. If the auto-switchback property associated with the takeover IP address group is set to Yes, the group will be automatically switched back to the preferred node when it transitions back to a state of ACTIVE.

Action must specifically be taken for any takeover IP address groups that are active on a node prior to a planned outage. Planned outages such as PWRDWNSYS on the primary node do not automatically switch the secondary node to a TRACKING state unless the automatic role swap property is set to Yes. Planned outages will also not automatically switch IP addresses to the other node. Prior to a planned outage of a node which is the current node for any takeover IP address group, the IP address group should be swapped to the other node using either the Db2 Mirror GUI or the QSYS2.SWAP_MIRROR_TAKEOVER_GROUP procedure.

Displaying takeover IP address groups

The list of takeover IP address groups can be displayed in the Db2 Mirror GUI by selecting Manage IP Takeover from the left navigation setup menu, as shown below.

Figure 1. Selecting takeover IP address groups

This will list all configured takeover IP address groups and their associated information. Each IP address assigned to the group is included.

The buttons at the bottom of the panel can be used to create and delete takeover IP address groups, add or remove IP addresses from a group, or swap a takeover IP address group to the other node.

The takeover IP address group information can also be displayed using the QSYS2.MIRROR_TAKEOVER_INFO view:

SELECT * FROM QSYS2.MIRROR_TAKEOVER_INFO;

Creating a takeover IP address group

Using the Db2 Mirror GUI, a takeover IP address group can be created by clicking Create Group on the Manage IP Takeover panel. This will display a panel as shown below.

A name for the group must be specified. The pull-downs can be used to select an ASP name and a preferred node. The auto-switchback property determines whether the group will switch back to the preferred node when it transitions to an ACTIVE state. A text description of up to 50 characters can also be specified. The list of defined and available IP addresses is shown on the panel. The arrows can be used to add or remove IP addresses in the Selected list. Once all required fields are specified and the IP addresses are selected, press OK to create the takeover IP address group.

Figure 3. Create takeover IP address group

The QSYS2.CREATE_MIRROR_TAKEOVER_GROUP procedure can also be used to create a takeover IP address group. The group-name parameter specifies the name of the group, the preferred-node parameter defines the node where the takeover IP addresses in the group will initially be started, and the iasp-name parameter can be *SYSBAS or the device description name of the primary database IASP that will be associated with the group. An optional text-description can be added, up to 50 characters long. The auto-switchback parameter determines whether the group will switch to the preferred node when it transitions to an ACTIVE state.

To add the APP1 takeover IP address group, associated with the DBIASP1 database IASP and a preferred node of NODE1:

CALL QSYS2.CREATE_MIRROR_TAKEOVER_GROUP(GROUP_NAME => 'APP1', 
                                        IASP_NAME => 'DBIASP1', 
                                        PREFERRED_NODE => 'NODE1',
                                        AUTO_SWITCHBACK => 'YES');

Takeover IP addresses are added to the group using the QSYS2.ADD_MIRROR_TAKEOVER_ADDRESS procedure. This is described in the next section.

Updating IP addresses and attributes in a takeover IP address group

Takeover IP addresses can be added to and removed from a takeover IP address group from the Manage IP Takeover panel in the GUI. Highlight the IP address group for which addresses are to be added or removed, and press Update IP Addresses. The following panel is displayed, with the IP addresses that are part of the group listed in the Selected IP Addresses box and other available IP addresses defined on the system in the Available IP Addresses box. The arrows between the two boxes can be used to move IP addresses between the boxes. Once the list of IP addresses is complete, press OK to add the IP addresses to the takeover IP address group and start the TCP/IP interfaces on the current node for the group.

The attributes of the takeover IP address group can also be changed on the same panel. The ASP name, preferred node, auto-switchback attribute, and description may all be updated.

Figure 4. Update takeover IP address group

The QSYS2.CHANGE_MIRROR_TAKEOVER_GROUP procedure can be used to change attributes of a takeover IP address group. The group-name parameter specifies the group where attributes will be changed. The preferred-node, iasp-name, text-description, and auto-switchback parameters can be used to update those attributes.

To update the auto-switchback attribute to YES for the APP1 takeover IP address group:

CALL QSYS2.CHANGE_MIRROR_TAKEOVER_GROUP(GROUP_NAME => 'APP1', 
                                        AUTO_SWITCHBACK => 'YES');

The QSYS2.ADD_MIRROR_TAKEOVER_ADDRESS procedure can be used to add IP addresses to an existing takeover IP address group. The group-name parameter specifies the group where the IP address should be added. The ip-address parameter specifies the IPv4 or IPv6 address to be added.

To add IP address 10.5.2.1 to the APP1 takeover IP address group:

CALL QSYS2.ADD_MIRROR_TAKEOVER_ADDRESS(GROUP_NAME => 'APP1', 
                                       IP_ADDRESS => '10.5.2.1');

A TCP/IP interface for the IP address must exist on both nodes in the Db2 Mirror environment prior to adding it to a group. An IP address can only be included in one group. If the associated interface cannot be started on the current node of the IP address group, the address will not be added to the group.

The QSYS2.REMOVE_MIRROR_TAKEOVER_ADDRESS procedure can be used to remove IP addresses from a takeover IP address group. The group-name parameter specifies the group from which the IP address should be removed. The ip-address parameter specifies the IPv4 or IPv6 address to be removed.

To remove IP address 10.5.2.1 from the APP1 takeover IP address group:

CALL QSYS2.REMOVE_MIRROR_TAKEOVER_ADDRESS(GROUP_NAME => 'APP1', 
                                          IP_ADDRESS => '10.5.2.1');

Removing an IP address from a takeover IP address group will not end the TCP/IP interface for the address.

Swapping a takeover IP address group between nodes

Prior to a planned outage of a node, any takeover IP address groups with that node as the current node should be moved to the other Db2 Mirror node so that access to applications through the associated IP addresses is not ended.

A takeover IP address group can be swapped between Db2 Mirror nodes using the Manage IP Takeover panel in the GUI. Highlight the IP address group to be swapped and press Swap Node. The following confirmation window will be displayed. When Yes is selected, the associated TCP/IP interfaces for addresses in the takeover IP address group will be ended on the current node and started on the other Db2 Mirror node.

Figure 5. Swap takeover IP address group

The QSYS2.SWAP_MIRROR_TAKEOVER_GROUP procedure can be used to switch a takeover IP address group to the other node. The group-name parameter specifies the group to be swapped.

To swap the APP1 group:

CALL QSYS2.SWAP_MIRROR_TAKEOVER_GROUP(GROUP_NAME => 'APP1');

Deleting a takeover IP address group

A takeover IP address group can be deleted from the Manage IP Takeover panel in the Db2 Mirror GUI. Highlight the IP address group to be deleted and press Delete Group. A confirmation window will be displayed. When Yes is selected, the group will be deleted.

Figure 6. Delete takeover IP address group

The QSYS2.DELETE_MIRROR_TAKEOVER_GROUP procedure can be used to delete a takeover IP address group. The group-name parameter specifies the group to be deleted.

To remove the APP1 group:

CALL QSYS2.DELETE_MIRROR_TAKEOVER_GROUP(GROUP_NAME => 'APP1');

Deleting a takeover IP address group has no effect on the TCP/IP interfaces for the addresses which were a part of the group.

Troubleshooting takeover IP address groups

Exit program

Automatic swapping of takeover IP address group actions is performed using an exit program (QSYS/QMRDBSCHG) that is registered for the QIBM_QMRDB_STATE_CHG exit point. If this exit program is modified or deleted, automatic swapping of takeover IP address groups will not occur. If the exit program is no longer registered on a node, suspending the node for maintenance and resuming will re-register the exit program.

Cluster resource group

Takeover IP address groups are implemented using a cluster technology called a device cluster resource group (CRG). Each IP address group is a separate CRG. The CRG is started when the first takeover IP address is added to the group and every time Db2 Mirror starts. In most cases, the use of CRGs is transparent to the user and the CRGs should not be managed using the cluster interfaces. All management of takeover IP address groups should be completed using the Db2 Mirror GUI or the related SQL procedures. If a failure occurs when configuring a takeover IP address group, it may be necessary to suspend Db2 Mirror for maintenance and then resume, or to take action on the CRG in order to complete the takeover IP address group request. The error message returned when a failure occurs explains in the recovery section what action can be taken. If this does not solve the issue, then IBM service should be contacted.