btrfs-rescue
Recover data from a damaged Btrfs filesystem
TLDR
Rebuild the filesystem metadata tree (very slow)
Fix device size alignment related problems (e.g. unable to mount the filesystem with super total bytes mismatch)
Recover a corrupted superblock from correct copies (recover the root of filesystem tree)
Recover from an interrupted transactions (fixes log replay problems)
Create a /dev/btrfs-control control device when mknod is not installed
SYNOPSIS
btrfs-rescue <subcommand> [<options>] <device>
PARAMETERS
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.
DESCRIPTION
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.
CAVEATS
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.
USAGE PRUDENCE
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.
FILESYSTEM STATE REQUIREMENT
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.
HISTORY
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.
SEE ALSO
btrfs(8), btrfs-check(8), btrfs-restore(8), mount(8)