SG_REM_REST_ELEM(8)

NAME
sg_rem_rest_elem - send SCSI remove or restore element command

SYNOPSIS
sg_rem_rest_elem [--capacity=RC] [--element=EID] [--help] [--modify] [--quick] [--remove] [--restore] [--timeout=SE] [--verbose] [--version] DEVICE

DESCRIPTION
Sends a SCSI REMOVE ELEMENT AND TRUNCATE [REAT], SCSI REMOVE ELEMENT AND MODIFY ZONES [REAMZ] or RESTORE ELEMENTS AND REBUILD [RESAR] command to the DEVICE. Since these commands have a potentially huge impact on the DEVICE (similar to the FORMAT UNIT command: destroying data and taking a long time to complete fully), they first give the user the chance to reconsider (3 times within 15 seconds) before taking action.

Unlike the FORMAT UNIT command, these commands seem designed to work in the background. So they will return quickly (although sbc5r01.pdf does not state that) and the disk will be placed in a reduced functionality state where only a specified number of commands will be executed (e.g. INQUIRY and REPORT LUNS) until the operation is complete. Other commands will receive sense data with a sense key of NOT READY and an additional sense code of 'Depopulation in progress' (for REAT and REAMZ) or 'Depopulation restoration in progress' (for RESAR). See the NOTES section below for more information.

The REMOVE ELEMENT AND TRUNCATE [REAT] and the RESTORE ELEMENTS AND REBUILD [RESAR] commands are defined in SBC-4 and later (i.e. SCSI Block Command standard) while REMOVE ELEMENT AND MODIFY ZONES [REAMZ] is defined in ZBC-2 and later (i.e. Zoned Block Command standard). Note that the REAMZ command can be issued by this utility (with the --modify option) or the sg_zone utility (with the --remove option); the resulting action should be the same.
The difference between REAT and REAMZ is that the former "changes the association between LBAs and physical blocks" and the latter does not change that association. Zones affected by the REAMZ command are placed into the zone condition: "Offline".

OPTIONS
Arguments to long options are mandatory for short options as well.

-c, --capacity=RC
    RC stands for Requested Capacity and is the number of logical blocks the DEVICE should have after the element is removed with the REAT command. The default value is 0 which allows the DEVICE to decide what the reduced capacity will be after the element removal. The RESAR command ignores this value.

-e, --element=EID
    where EID is an element identifier which is a 32 bit unsigned integer starting at one. This field is used by the REAT command and ignored otherwise. The default value is zero (which is invalid). So the user needs to supply a valid element identifier when --remove is used.

-h, --help
    output the usage message then exit.

-m, --modify
    causes the REMOVE ELEMENT AND MODIFY ZONES command [REAMZ] to be sent to the DEVICE. In practice, --element=EID needs to be also given.

-q, --quick
    the default action (i.e. when this option is not given) is to give the user 15 seconds to reconsider doing a remove or restore element operation on the DEVICE. When this option is given that step (i.e. the 15 second warning period) is bypassed.

-r, --remove
    causes the REMOVE ELEMENT AND TRUNCATE command to be sent to the DEVICE. In practice, --element=EID needs to be also given.

-R, --restore
    causes the RESTORE ELEMENTS AND REBUILD command to be sent to the DEVICE.

-t, --timeout=SE
    where SE is the command timeout in seconds. The default is 60 seconds and if 0 is given, it is mapped to 60. An alternate long form is --tmo=SE.

-v, --verbose
    increase the level of verbosity, (i.e. debug output).

-V, --version
    print the version string and then exit.

NOTES
Once an element is removed successfully it is termed as "depopulated". Depopulated elements that have the 'Restoration Allowed' (RALWD) bit set (see sg_get_elem_status) are candidates for future restoration.

A (storage) element of a rotating hard disk is one side of a platter typically associated with one head. Such hard disks typically have multiple platters with two heads per platter (i.e. one head each side of the platter).

Only one element can be depopulated at a time. It seems that user data is striped across various platters (manufacturers pointedly don't describe how that is done) so depopulation can take a very long time irrespective of which element (e.g. the last element) is depopulated. The DEPOPULATION TIME field in the Block Device Characteristics VPD page gives an indication of how long the depopulation of one element will take. The unit of that field is seconds and for reference, there are 86,400 seconds in a day. Once a --remove or --restore based command has successfully returned, the disk goes into what can be considered as "depopulation" mode. While a disk is in "depopulation" mode, all media access commands (and some others) are rejected with a NOT READY sense code and additional sense code of 0x4,0x24 or 0x4,0x25 (the latter one is for "depopulation restoration in progress").

While this facility is described by reference to hard (spinning) disks, the commands are defined in general terms so that they might also apply to solid state disks (SSDs) that are implemented using multiple ICs (die_s). Depopulation may be useful if one of those ICs becomes faulty.

At time of writing, OS and HBA support for depopulating hard disks is incomplete. For example Linux as of lk 6.5.7 does not properly handle the situation when a hard disk is in "depopulation" mode. Also at least one SAS-4 HBA has trouble booting when one of its attached hard disks is in "depopulation" mode. Suggestion: depopulating a head on a hard disk (or restoring it) should be done on a non-production system that is not used for any other purpose during the depopulation.

When a hard disk is in "depopulation" mode a REQUEST SENSE command can be sent to obtain "progress" information. This can be done with the 'sg_requests' or 'sg_requests --progress' utility.

In summary, "head" depopulation on a hard disk can be viewed as a type of format operation that takes a failed or failing disk with media errors all on one side of a platter, and produces a properly functioning disk with (slightly) reduced capacity. Finally the T10 specifications do not say that depopulation on a disk will lead to all data will be lost, but it is a safe assumption that all data will indeed be lost. So the normal warnings about taking backups before attempting depopulation apply.

EXIT STATUS
The exit status of sg_rem_rest_elem is 0 when it is successful. Otherwise see the sg3_utils(8) man page.

AUTHORS
Written by Douglas Gilbert.

REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

COPYRIGHT
Copyright © 2022-2023 Douglas Gilbert
This software is distributed under a BSD-2-Clause license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

SEE ALSO
sg_get_elem_status,sg_requests,sg_zone(sg3_utils)