IBM i: The SQL Way · #17

Remove an IBM i Service Tools Server Configuration Entry with SQL

Use QSYS2.REMOVE_SERVICE_TOOLS_SERVER_CONFIGURATION_ENTRY to delete an obsolete partition-specific STS LAN recovery configuration by UUID.

A retired partition, rebuilt recovery LPAR, or abandoned test environment can leave a stale Service Tools Server configuration entry. IBM i 7.6 provides an SQL procedure for removing the entry by partition UUID.

The procedure is:

QSYS2.REMOVE_SERVICE_TOOLS_SERVER_CONFIGURATION_ENTRY

What removal affects

The procedure removes a stored partition-specific configuration entry.

It does not disable or immediately reconfigure the currently active Service Tools Server.

The active configuration is separate.

Review the entry first

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';

Confirm that:

• the UUID belongs to the retired or obsolete partition
• no current replication direction depends on the entry
• no recovery runbook references the configuration
• the entry is not required for Remote Key Agent communication

Remove the entry

CALL QSYS2.REMOVE_SERVICE_TOOLS_SERVER_CONFIGURATION_ENTRY
(
    PARTITION_UUID =>
        BX'52C417A870DD4487986B33F74CE9FE47'
);

The UUID uniquely identifies the stored entry.

Confirm removal

SELECT
    HEX(PARTITION_UUID) AS PARTITION_UUID_HEX,
    RESOURCE_NAME,
    IPV4_ADDRESS
FROM QSYS2.SERVICE_TOOLS_SERVER_CONFIGURATION_ENTRY_INFO
WHERE PARTITION_UUID =
      BX'52C417A870DD4487986B33F74CE9FE47';

Expected result:

No rows

Also review the remaining set:

SELECT
    HEX(PARTITION_UUID) AS PARTITION_UUID_HEX,
    RESOURCE_NAME,
    IPV4_ADDRESS,
    IPV6_ADDRESS
FROM QSYS2.SERVICE_TOOLS_SERVER_CONFIGURATION_ENTRY_INFO
ORDER BY PARTITION_UUID_HEX;

When removal is appropriate

Examples include:

• recovery partition permanently retired
• LPAR recreated with a new UUID
• old FlashCopy test environment decommissioned
• duplicate or incorrect entry replaced
• network design abandoned
• Remote Key Agent topology changed
• entry created during a temporary test

When removal may be dangerous

Do not remove an entry merely because its IP address is not currently active.

The entry may exist specifically for:

• a DR partition that is normally powered off
• a storage-replication target
• a FlashCopy recovery environment
• reverse replication after failover
• Remote Key Agent access during IPL

A configuration used only during an emergency can appear unused during normal operations.

Maximum entry count

IBM allows up to ten stored entries.

Removing obsolete entries helps keep the list understandable and prevents old UUIDs from consuming the limited set.

But capacity alone is not a reason to remove an entry without verifying the recovery design.

Authority

The caller must:

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

The procedure is a privileged infrastructure change.

Preserve evidence

Before removal, capture the row in a secured change record.

For example:

SELECT
    CURRENT TIMESTAMP AS CAPTURE_TIMESTAMP,
    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';

Do not place the details in an unsecured application log.

Rollback planning

There is no reason to rely on memory after a mistaken deletion.

Record the complete entry before removal so it can be recreated through:

QSYS2.ADD_SERVICE_TOOLS_SERVER_CONFIGURATION_ENTRY

if necessary.

A rollback plan should include the exact approved values and authority requirements.

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 workflow

1. Query the entry.
2. Verify the UUID against partition records.
3. Review storage replication and FlashCopy designs.
4. Review Remote Key Agent requirements.
5. Confirm no reverse-replication scenario needs it.
6. Capture the complete row.
7. Obtain approval.
8. Remove the entry.
9. Query the view to verify removal.
10. Update the recovery runbook and asset records.

Final takeaway

REMOVE_SERVICE_TOOLS_SERVER_CONFIGURATION_ENTRY is simple to call, but a stored STS configuration may exist for the exact moment when normal infrastructure is unavailable.

Remove stale entries deliberately, preserve the previous values, and make the decision from the recovery design—not from the fact that the configuration is quiet during normal operations.