IBM i: The SQL Way · #16

Change an IBM i Service Tools Server Configuration Entry with SQL

Use QSYS2.CHANGE_SERVICE_TOOLS_SERVER_CONFIGURATION_ENTRY to update a stored partition-specific STS LAN recovery configuration without changing the currently active server.

Recovery hardware, network design, or a Service Tools Server resource can change after a partition-specific entry has been stored. IBM i 7.6 provides an SQL procedure for updating that entry by partition UUID.

The procedure is:

QSYS2.CHANGE_SERVICE_TOOLS_SERVER_CONFIGURATION_ENTRY

What it does not change

The procedure updates a stored configuration entry.

It does not immediately alter the active Service Tools Server configuration.

For the current server configuration, IBM provides:

QSYS2.CHANGE_SERVICE_TOOLS_SERVER

The two procedures solve different problems.

Review the current stored 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';

Capture the existing values before making a change.

Change an IPv4 address and gateway

CALL QSYS2.CHANGE_SERVICE_TOOLS_SERVER_CONFIGURATION_ENTRY
(
    PARTITION_UUID  =>
        BX'52C417A870DD4487986B33F74CE9FE47',
    IPV4_ADDRESS    => '192.0.2.56',
    GATEWAY_ADDRESS => '192.0.2.1',
    SUBNET_MASK     => '255.255.255.0'
);

When IPV4_ADDRESS is supplied, provide the required IPv4 companion values according to the documented procedure requirements.

Change the communication resource

CALL QSYS2.CHANGE_SERVICE_TOOLS_SERVER_CONFIGURATION_ENTRY
(
    PARTITION_UUID =>
        BX'52C417A870DD4487986B33F74CE9FE47',
    RESOURCE_NAME  => 'CMN02'
);

Omitted parameters are not changed.

That makes named-parameter calls safer and clearer than positional calls.

Change the VLAN

CALL QSYS2.CHANGE_SERVICE_TOOLS_SERVER_CONFIGURATION_ENTRY
(
    PARTITION_UUID =>
        BX'52C417A870DD4487986B33F74CE9FE47',
    VIRTUAL_LAN_ID => 220
);

Confirm the VLAN with the network and Power infrastructure design before changing the entry.

Change IPv6 information

The procedure supports:

IPV6_ADDRESS
INTERFACE_ID

The interface ID is an eight-byte value.

When IPv6 is specified, the interface ID is required by the procedure.

Use values collected from the actual intended environment, not a fabricated example.

Verify the result

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

Compare every column with the approved change record.

Why a change may be required

Common reasons include:

• recovery LPAR rebuilt with a new UUID
• communication resource changed
• recovery network moved to a new subnet
• gateway changed
• VLAN design changed
• IPv6 enabled
• Remote Key Agent topology changed
• old test configuration replaced by production values

If the partition UUID changed, changing the old row may not be appropriate because the UUID is the key.

In that case:

Add the new UUID entry
Verify it
Then remove the obsolete UUID entry

Authority

The caller must:

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

This operation should be executed under controlled administrative authority.

Change-control evidence

Before and after the call, capture:

SELECT
    CURRENT TIMESTAMP AS CAPTURE_TIMESTAMP,
    *
FROM QSYS2.SERVICE_TOOLS_SERVER_CONFIGURATION_ENTRY_INFO;

Store the approved values in a secured change record.

Do not publish service-network addresses or partition UUIDs in public documentation.

Test after the change

A successful procedure call proves that IBM i accepted and stored the entry.

It does not verify end-to-end recovery.

Testing should include, where applicable:

• STS LAN resource availability
• service-tools network routing
• certificate configuration
• Remote Key Agent verification
• replicated or FlashCopy load source
• documented IPL recovery sequence
• return-to-production direction

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. Capture the current stored entry.
2. Confirm the target partition UUID.
3. Validate the new resource and network values.
4. Obtain change approval.
5. Call the procedure using named parameters.
6. Query the row again.
7. Compare every stored value.
8. Update the recovery runbook.
9. Test the complete recovery path.
10. Retain evidence of the test.

Final takeaway

CHANGE_SERVICE_TOOLS_SERVER_CONFIGURATION_ENTRY makes a recovery-specific STS configuration maintainable through SQL.

The omitted-parameter behavior supports targeted updates, but every change should still be treated as a privileged infrastructure modification whose real success is proven only through recovery testing.