Change SCSI multipath access safely with sg_stpg

You will use sg_stpg to send a SCSI SET TARGET PORT GROUPS command, change a target port group to a chosen asymmetric access state, and check the result with a separate report command. Allow 15 minutes for a prepared test device. This is storage control, not a harmless query: changing access can interrupt I/O or make a path unavailable.

You need the sg3-utils package, a SCSI generic device such as /dev/sg3, and permission to send SCSI commands. The installed package here is sg3-utils 1.46-3ubuntu4; the installed utility reports version 1.19 20180628. The local manual is labelled sg3_utils 1.38, so use the installed command's help output as a quick compatibility check.

1. Identify the device and its support

Replace the placeholder with the generic SCSI device for the storage target. Confirm the path and inspect standard inquiry data before changing anything:

$ DEVICE=/dev/sg3
$ test -c "$DEVICE" && printf '%s\n' "$DEVICE is a character device"
$ sg_inq "$DEVICE"

The TPGS value in the standard inquiry response indicates whether target port group support is present. The sg_stpg manual says the command should be supported when TPGS is 2 or 3. If the device does not advertise that support, stop here. Do not try to force a state with guessed identifiers.

Checkpoint: confirm the device path, record the current access state with sg_rtpg "$DEVICE" if that utility is installed, and note which target port group or relative target port you intend to affect. Reading inquiry and report data does not change the device.

2. Confirm the command syntax without touching storage

Run the local help and version checks as your ordinary user:

$ sg_stpg --help
$ sg_stpg --version
Version: 1.19 20180628

The command requires one DEVICE. Its state options are active/non-optimized (--active), active/optimized (--optimized), standby (--standby), unavailable (--unavailable), and offline (--offline). If no explicit state or --tp option is given, active/optimized is the documented default, but make the state explicit in operational commands.

3. Use automatic discovery for the device's primary port group

Without --tp, sg_stpg first reads device identification, then reports target port groups, checks whether the requested transition is supported, and finally sends SET TARGET PORT GROUPS. For a target that you have already identified and approved for a path change, an explicit state command is:

$ sudo sg_stpg --optimized "$DEVICE"

Root is not inherently required by the program, but many installations restrict SCSI generic devices to root or a storage group. Use sudo only when the device permissions require it. A successful exit status is 0; otherwise consult the command's error and the sg3-utils documentation.

Warning: this can change which paths accept normal I/O. Coordinate with the multipath or storage owner first. Do not run the example against a production LUN merely to see what it does.

4. Name target port groups explicitly

Use --tp when you have verified the target port group identifiers and want to build the command parameter list yourself. Non-offline states use target port group identifiers. State names accepted by --state are ao (active/optimized), an (active/non-optimized), s (standby), u (unavailable), and o (offline). Numeric values are also accepted: 0, 1, 2, 3 and 14 respectively.

$ sudo sg_stpg --tp=0x12 --state=ao "$DEVICE"

Identifiers are decimal unless prefixed with 0x or given a trailing h. For several groups, give matching list lengths:

$ sudo sg_stpg --tp=0x12,0x13 --state=ao,an "$DEVICE"

A single state is repeated when several target ports are listed, so this is also valid:

$ sudo sg_stpg --tp=18,19 --state=ao "$DEVICE"

That repetition is easy to miss in a review. Prefer one state per identifier when a mixed change is intended.

5. Treat offline as a different operation

--offline is for a target port that is about to be removed. It takes a relative target port identifier, not a target port group identifier. The short option is -l or -O, despite the long option being --offline:

$ sudo sg_stpg --tp=7 --offline "$DEVICE"

Do not copy a group identifier from a report into this command without checking that it is the relative target port identifier. Offline is service-disrupting and can be the wrong choice for ordinary path preference. Removing a path is a separate hardware and multipath procedure; this command does not undo that work.

6. Verify the transition and recover deliberately

After a successful change, query the target port groups again:

$ sg_rtpg "$DEVICE"
$ printf 'sg_stpg status: %s\n' "$?"

Look for the intended target port group, its asymmetric access state, and any transition or support flags in the report. sg_stpg itself does not print a success summary, so its exit status and a fresh report are the useful checkpoints.

There is no universal undo command. To recover, use the identifier and state recorded before the change, after confirming that the storage array still permits the transition. For example, if the previous state was active/non-optimized:

$ sudo sg_stpg --tp=0x12 --state=an "$DEVICE"
$ sg_rtpg "$DEVICE"

If the device rejects the transition, stop retrying blindly. Check array documentation, multipath status, recent kernel messages, and whether another host owns the target. A failed command may leave the device unchanged, but treat the actual report as authoritative.

Common traps

• Do not confuse active/optimized with active/non-optimized. They are different states: ao is 0 and an is 1.
• Do not use a target port group identifier with --offline; offline acts on one relative target port.
• Do not assume a successful exit means every path is healthy. Verify with sg_rtpg and the host's multipath tooling.
• Use --hex or --raw only when you specifically need the REPORT TARGET PORT GROUPS response for analysis. They output report data and are not state changes.
• Keep the original state and identifiers in your change record. Repeating a command without that record can make recovery harder.