IBM i: The SQL Way · #15

Add an IBM i Service Tools Server Configuration Entry with SQL

Use QSYS2.ADD_SERVICE_TOOLS_SERVER_CONFIGURATION_ENTRY to store a partition-specific STS LAN configuration for alternate-hardware IPL and Remote Key Agent recovery scenarios.

A replicated or FlashCopy load-source image can start on hardware where its original Service Tools Server LAN configuration is unusable. IBM i 7.6 provides an SQL procedure for storing the configuration that should apply to a specific target partition.

The procedure is:

QSYS2.ADD_SERVICE_TOOLS_SERVER_CONFIGURATION_ENTRY

What it changes

The procedure adds a stored configuration entry.

It does not immediately change the currently active Service Tools Server LAN configuration.

The entry can be used during an IPL when IBM i detects that the load-source image is being used with different hardware.

Do not confuse it with:

QSYS2.CHANGE_SERVICE_TOOLS_SERVER

which changes the current STS configuration.

Before adding an entry

Collect and verify:

Target partition UUID
Communication resource name
IPv4 or IPv6 design
Gateway
Subnet mask
VLAN ID when used
IPv6 interface ID when used

The values should come from the actual target partition and the documented recovery design.

Obtain the partition UUID

Run this on the partition whose UUID the entry must match:

SELECT
    HEX(PARTITION_UUID) AS PARTITION_UUID_HEX
FROM QSYS2.SYSTEM_STATUS_INFO_BASIC;

Record all 32 hexadecimal characters.

Review existing entries

SELECT
    HEX(PARTITION_UUID) AS PARTITION_UUID_HEX,
    RESOURCE_NAME,
    IPV4_ADDRESS,
    GATEWAY_ADDRESS,
    SUBNET_MASK,
    IPV6_ADDRESS,
    VIRTUAL_LAN_ID,
    HEX(INTERFACE_ID) AS INTERFACE_ID_HEX
FROM QSYS2.SERVICE_TOOLS_SERVER_CONFIGURATION_ENTRY_INFO;

IBM permits a maximum of ten entries.

Check for an existing row for the same UUID before adding another configuration.

Example IPv4 entry

Use actual values from the target system:

CALL QSYS2.ADD_SERVICE_TOOLS_SERVER_CONFIGURATION_ENTRY
(
    PARTITION_UUID  =>
        BX'52C417A870DD4487986B33F74CE9FE47',
    RESOURCE_NAME   => 'CMN01',
    IPV4_ADDRESS    => '192.0.2.25',
    GATEWAY_ADDRESS => '192.0.2.1',
    SUBNET_MASK     => '255.255.255.0'
);

The 192.0.2.0/24 network is reserved for documentation. Do not copy these addresses into a production configuration.

Example with VLAN

CALL QSYS2.ADD_SERVICE_TOOLS_SERVER_CONFIGURATION_ENTRY
(
    PARTITION_UUID  =>
        BX'52C417A870DD4487986B33F74CE9FE47',
    RESOURCE_NAME   => 'CMN01',
    IPV4_ADDRESS    => '192.0.2.25',
    GATEWAY_ADDRESS => '192.0.2.1',
    SUBNET_MASK     => '255.255.255.0',
    VIRTUAL_LAN_ID  => 120
);

VLAN values must match the physical and virtual network configuration of the target environment.

Verify the new row

SELECT
    HEX(PARTITION_UUID) AS PARTITION_UUID_HEX,
    RESOURCE_NAME,
    IPV4_ADDRESS,
    GATEWAY_ADDRESS,
    SUBNET_MASK,
    IPV6_ADDRESS,
    VIRTUAL_LAN_ID,
    HEX(INTERFACE_ID) AS INTERFACE_ID_HEX
FROM QSYS2.SERVICE_TOOLS_SERVER_CONFIGURATION_ENTRY_INFO
WHERE PARTITION_UUID =
      BX'52C417A870DD4487986B33F74CE9FE47';

The presence of the row proves that the configuration entry was stored.

It does not prove:

• the resource exists on the recovery hardware
• the network values are correct
• the Remote Key Agent can connect
• the recovery system will complete IPL
• the overall DR procedure is ready

Those items require testing.

Production and target entries

IBM’s storage-replication guidance describes adding entries for both:

• the recovery target partition
• the production partition

An entry for the production partition can be required when replication later runs in the opposite direction and the original system becomes the recovery target.

The correct design depends on the replication and recovery topology.

Remote Key Agent context

When the Save/Restore master key is cached in Platform KeyStore, a copied load source may start on a managed system where that key is not present.

A Remote Key Agent can provide the key during IPL.

The STS LAN server must be able to communicate in that alternate environment, which is why partition-specific configuration entries are important.

Authority

The caller must:

Have *IOSYSCFG special authority
and
Be linked to a service tools user ID
with the Service Tools Security privilege

This is a privileged recovery and service-network configuration operation.

Do not run it from an ordinary application profile.

Change control

Treat the call like a controlled infrastructure change.

Record:

• who approved it
• target partition UUID
• hardware and resource name
• network values
• reason for the entry
• related DR or FlashCopy procedure
• date tested
• rollback or removal plan

IBM i 7.6 only

IBM lists the procedure as supported at:

IBM i 7.6 — Db2 Group PTF SF99960 Level 3

It is not listed as supported on IBM i 7.5 or earlier releases.

A safe implementation workflow

1. Build or identify the target recovery partition.
2. Retrieve its UUID from that partition.
3. Confirm the STS LAN resource through SST or DST.
4. Verify network and Remote Key Agent communication.
5. Return to the production system.
6. Review existing configuration entries.
7. Add the new partition-specific entry.
8. Query the view to confirm the stored values.
9. Update the recovery runbook.
10. Test the complete recovery process.

Final takeaway

ADD_SERVICE_TOOLS_SERVER_CONFIGURATION_ENTRY creates a small configuration record with significant recovery impact.

The SQL call is easy. The difficult and important work is ensuring the UUID, resource, network, Remote Key Agent, replication direction, and recovery procedure are all correct and tested.