SG_REM_REST_ELEM(8)

📦
version 1.49 · 3 versions
, in arch rolling, nixpkgs unstable

💅 SG_REM_REST_ELEM(8) — the sg_rem_rest_elem page, bestie edition 🎀

okay so this is the manual page for sg_rem_rest_elem, part of the sg3_utils crew (that's the sg3_utils manual section 8 situation, iykyk). Buckle up because this utility is lowkey terrifying and highkey iconic 💀✨

🌸 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 💖

So what this does is it sends one of three SCSI commands to the DEVICE:

  • REMOVE ELEMENT AND TRUNCATE — [REAT]
  • REMOVE ELEMENT AND MODIFY ZONES — [REAMZ]
  • RESTORE ELEMENTS AND REBUILD — [RESAR]

Now listen, because these commands are a lot. They have a potentially huge impact on the DEVICE — think FORMAT UNIT energy: destroying data, taking a long time to complete fully. So the utility is like "bestie, are you sure?" and gives the user the chance to reconsider 3 times within 15 seconds before taking action. Considerate queen 👑.

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). The NOTES section down below has more deets 👇.

The REMOVE ELEMENT AND TRUNCATE [REAT] and the RESTORE ELEMENTS AND REBUILD [RESAR] commands are defined in SBC-4 and later (that's the SCSI Block Command standard, tyvm) while REMOVE ELEMENT AND MODIFY ZONES [REAMZ] is defined in ZBC-2 and later (the Zoned Block Command standard, also tyvm). 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. fr fr, same vibe, same outcome 🦋.

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". Not me casually putting zones offline 🙈.

✨ OPTIONS ✨

Heads up: arguments to long options are mandatory for short options as well. Periodt.

  • -c, --capacity=RC — RC stands for Requested Capacity and it's the number of logical blocks the DEVICE should have after the element is removed with the REAT command. The default value is 0 which lets the DEVICE decide what the reduced capacity will be after the element removal. The RESAR command ignores this value entirely, like it didn't even see it 💅.
  • -e, --element=EID — where EID is an element identifier, a 32 bit unsigned integer starting at one. This field is used by the REAT command and ignored otherwise. The default value is 0 (which is invalid, oops). So the user needs to supply a valid element identifier when --remove is used. No skipping this step bestie 🎀.
  • -h, --help — output the usage message then exit. Classic, iconic, we love a helpful 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. Don't forget it 😭.
  • -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. So like… no takebacks, no thinking time, straight to chaos 🔥.
  • -r, --remove — causes the REMOVE ELEMENT AND TRUNCATE command to be sent to the DEVICE. In practice, --element=EID needs to be also given. Again. Please. 🙏
  • -R, --restore — causes the RESTORE ELEMENTS AND REBUILD command to be sent to the DEVICE. The comeback arc 🌈.
  • -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. Two names, one slay ⭐.
  • -v, --verbose — increase the level of verbosity, (i.e. debug output). Spill the tea, debug-style 🍓.
  • -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). Anatomy lesson, free of charge 💜.

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. Yeah. 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"). Noted. Memorized. Tattooed 💀.

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. SSD girlies, this one's for you too 🫶.

⚠️ 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. Like, please don't do this on the work server 🙈.

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. Progress bar era ✨.

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. BACK UP YOUR STUFF. That's the whole mood 👑.

💀 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. Legend behavior, honestly.

🎀 REPORTING BUGS 🎀

Report bugs to <dgilbert at interlog dot com>.

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)

and that's the whole page bestie!! this one's from sg3_utils-1.49, dated 2026-07-01 — go forth and maybe don't depopulate anything on prod 💖✨🦋

📦 where this page comes from