Manage SCSI Zones Safely with sg_zone

sg_zone selects a zone and sends one SCSI zone-management command, such as opening, closing or finishing it. The examples below show the command shape without touching a real device. Allow about 15 minutes for a first run, plus time to confirm the device documentation and its maintenance window.

Before you start

• Install sg3-utils and identify the SCSI generic device that represents the intended target, such as /dev/sg3. Do not guess this path. Confirm it with your storage inventory, lsscsi -g if available, or the device documentation. A block path and a SCSI generic path are not interchangeable assumptions.
• Versions here. The local package is sg3-utils 1.46-3ubuntu4. The installed binary reports sg_zone version 1.15 20210122. The local manual page is marked sg3_utils-1.43, so use the binary's help output as the final check when packaging differs from the manual page.
• Expect privileges. Most operations need elevation because they send a SCSI command directly to hardware. Use sudo only for the final operation, after checking every value. The command changes device state and can affect host I/O, mounted filesystems and other users.

1. Check the installed interface

Run the harmless probes first:

sg_zone --help
sg_zone --version

Expected output includes a usage line ending in DEVICE and a version line similar to:

version: 1.15 20210122

The utility accepts exactly one action from --open, --close, --finish, --remove or --sequentialize. It does not provide a general read-only preview of the command that would be sent.

Checkpoint: Stop here if the help output does not show the action you need, or if the version is not the one approved for your host.

2. Choose the zone and action

The --zone=ID value is a zone start logical block address, not an ordinal zone number. It defaults to 0. Decimal is assumed; prefix hexadecimal with 0x or append h. Obtain the zone start LBA from a trusted report for the same device, rather than converting a human-facing zone number yourself.

• --open sends OPEN ZONE.
• --close sends CLOSE ZONE.
• --finish sends FINISH ZONE.
• --sequentialize sends SEQUENTIALIZE ZONE.
• --remove sends REMOVE ELEMENT AND MODIFY ZONES and normally needs --element=EID.

--all sets the command's ALL field. Treat it as a separate scope decision: it can make an operation apply beyond the single zone identified by --zone, depending on the device and command. Do not add it because it appears in an example.

Warning: Finishing, removing or otherwise changing zones may be irreversible at the device level. Check the SCSI device's ZBC behaviour, current write activity, reservations and backup position before sending anything. Stop applications or unmount filesystems only according to your storage procedure; sg_zone does not make those changes safe for you.

3. Build a reviewed command

Replace both placeholders with values you have independently verified. These commands are templates and deliberately use a non-existent device name, so they do not send a command when copied unchanged:

sg_zone --open --zone=ZONE_START_LBA /dev/sgX
sg_zone --close --zone=ZONE_START_LBA /dev/sgX
sg_zone --finish --zone=ZONE_START_LBA /dev/sgX
sg_zone --sequentialize --zone=ZONE_START_LBA /dev/sgX
sg_zone --remove --element=ELEMENT_ID --zone=ZONE_START_LBA /dev/sgX

The optional --count=ZC places a zone count in the command. The accepted range is 0 through 65535. Its meaning is defined by the SCSI command and target, so do not use it as a substitute for a zone identifier. For a remove operation, the element identifier is an unsigned 32-bit value starting at one; the utility's default of zero is invalid.

Keep the action, zone, element and device visible in your change record. Avoid combining several actions in a shell script until one manually reviewed command has succeeded.

4. Send one command during the change window

After a second person or your change procedure has checked the values, run the chosen command with the required privilege. For example:

sudo sg_zone --close --zone=0xZONE_START_LBA /dev/sgX

The command prints diagnostic information only when the device or utility has something to report. A successful exit status is 0. Capture the exit status immediately:

status=$?
printf 'sg_zone exit status: %s\n' "$status"

A non-zero status means the operation did not complete successfully. Preserve the complete terminal output and check the device's sense data and storage logs. Do not respond to an error by trying every action in turn.

5. Verify the device state

sg_zone is a modifying command, not a reporting command. Verify the result with a suitable read-only zone report such as sg_rep_zones, using the same device path and the reporting options appropriate to your target.

sudo sg_rep_zones /dev/sgX

Compare the reported zone state and start LBA with the state you intended. The exact report format is target-dependent, so do not treat an absent or unfamiliar line as proof of success. If the command failed, or the report disagrees with the change record, stop I/O as required by the storage procedure and escalate with the saved output. There is no universal undo command: closing a zone is not a general reversal for finishing or removing one.

Common traps

• Using a zone number instead of its start LBA. --zone names the LBA.
• Forgetting that decimal is the default. Use an explicit 0x prefix when copying hexadecimal values.
• Combining two action flags. Choose exactly one.
• Using --remove without a valid non-zero element identifier.
• Assuming --all means "all zones I intended". Confirm the command semantics for the device.
• Expecting a dry-run. The utility has help and version probes, but no documented no-send mode.

Done means

• Version recorded. The installed version and target SCSI generic path were recorded.
• Command checked. One action, the zone start LBA and any element or count values were independently checked.
• Timing approved. The operation ran in an approved maintenance window with the necessary privilege.
• Output saved. The exit status and complete output were saved.
• State confirmed. A read-only zone report confirms the resulting state, or the failed operation has been escalated without speculative retries.