btrfs-rescue

Rebuild the filesystem metadata tree (very slow)

$ sudo btrfs rescue chunk-recover [path/to/partition]

$ sudo btrfs rescue fix-device-size [path/to/partition]

$ sudo btrfs rescue super-recover [path/to/partition]

$ sudo btrfs rescue zero-log [path/to/partition]

$ sudo btrfs rescue create-control-device

btrfs-rescue <subcommand> [<options>] <device>

chunk-recover
    Attempts to recover and re-scan the chunk tree from a Btrfs filesystem, often the first step when the filesystem fails to mount due to chunk tree corruption.

fix-chunk-tree
    Scans the device for chunk tree blocks and rebuilds the chunk tree based on the found blocks, addressing severe chunk tree corruption.

super-recover
    Scans for and attempts to recover superblocks from the device. Btrfs stores multiple superblock copies; this command helps find a usable one.

zero-log
    Zeros out the transaction log (journal) of the Btrfs filesystem. This can resolve mounting issues caused by a corrupted log, but carries a risk of data loss and should be used with extreme caution.

tree-mod-log
    Dumps the tree modification log, providing insight into recent metadata changes for debugging and analysis.

dump-super
    Dumps detailed, raw information from all available superblocks on the device, primarily used for diagnostic purposes.

-f, --force
    Force the operation, overriding certain warnings and safety checks. Use with extreme caution as it can lead to further data loss.

-v, --verbose
    Increase verbosity of output, providing more detailed information during the operation.

btrfs-rescue is a crucial command-line utility within the Btrfs filesystem tools, designed for advanced recovery and diagnostic operations on severely damaged Btrfs filesystems. Unlike general-purpose commands like btrfs check or btrfs restore, btrfs-rescue provides lower-level functionalities to manipulate and analyze the filesystem's metadata structures directly on the device. It is typically employed when standard recovery methods have failed or are insufficient, offering specific subcommands to address issues such as corrupted chunk trees, unreadable superblocks, or problematic logs. Its powerful capabilities make it an invaluable tool for experienced administrators attempting to salvage data from critically impaired Btrfs volumes, but its direct interaction with raw device data necessitates extreme caution and prior backups to prevent further data loss. Common uses include rebuilding metadata trees, zeroing out transaction logs, and inspecting superblock contents for diagnostic purposes.

btrfs-rescue operates directly on the raw device and can cause irreversible data loss if misused.
Always create a full backup or disk image of the filesystem before attempting any rescue operations.
Most operations require the target Btrfs filesystem to be unmounted to prevent further corruption.
It is a low-level tool that requires a deep understanding of Btrfs internals and should only be used as a last resort by experienced administrators.

Due to its powerful and potentially destructive nature, btrfs-rescue should be approached with extreme caution. It is always recommended to test any rescue strategy on a duplicate or disk image of the problematic filesystem first, if possible, to avoid exacerbating the damage.

For most btrfs-rescue subcommands, the Btrfs filesystem must be in an unmounted state on the specified <device>. Attempting to run rescue operations on a mounted filesystem can lead to further data corruption or undefined behavior.

btrfs-rescue is an integral part of the btrfs-progs utility suite, which has evolved alongside the Btrfs filesystem itself since its inception around 2007. While there isn't a distinct historical narrative for the command in isolation, its continuous development reflects the ongoing efforts to enhance Btrfs's resilience and recovery capabilities. It has consistently served as the low-level recovery tool for situations where standard filesystem checks and repairs fall short.

btrfs(8), btrfs-check(8), btrfs-restore(8), mount(8)