btrfs-restore

Restore all files from a btrfs filesystem to a given directory

$ sudo btrfs restore [path/to/btrfs_device] [path/to/target_directory]

$ sudo btrfs restore [[-D|--dry-run]] [path/to/btrfs_device] [path/to/target_directory]

$ sudo btrfs restore --path-regex [regex] -c [path/to/btrfs_device] [path/to/target_directory]

$ sudo btrfs restore -t [bytenr] [path/to/btrfs_device] [path/to/target_directory]

$ sudo btrfs restore [[-m|--metadata]] [[-x|--xattr]] [[-S|--symlinks]] [[-o|--overwrite]] [path/to/btrfs_device] [path/to/target_directory]

btrfs restore [options] <device> <path>

-s <superblock_number>
    Specify which superblock to use (0, 1, or 2). Defaults to 0 if not specified.

-v
    Enable verbose output, showing details of the restoration process.

-i
    Do not overwrite existing files in the destination path.

-o
    Overwrite existing files in the destination path (default is to skip).

-c
    Only restore files whose checksums match their data, ensuring data integrity.

-m
    Do not restore file metadata (permissions, ownership, timestamps).

-u
    Do not restore user and group ownership information.

-t <YYYY-MM-DD[ HH:MM:SS]>
    Only restore files modified after the specified timestamp.

-x
    Restore extended attributes (xattrs) associated with files.

--raw
    Restore raw data (chunks) rather than files, useful for advanced recovery.

--path <path_in_fs>
    Specify a specific path within the btrfs filesystem to restore.

--sys-dev <device>
    For multi-device filesystems, specify a system device to scan for metadata.

--force-root <root_id>
    Force restoration from a specific tree root ID, useful in advanced corruption scenarios.

--log-level <level>
    Set the logging level (e.g., debug, info, warning, error).

btrfs-restore is a crucial utility within the btrfs filesystem toolset, designed specifically for data recovery from damaged or corrupted btrfs filesystems. Unlike other btrfs commands that might attempt to check or repair the filesystem, btrfs-restore operates strictly in a read-only mode, meaning it will not further modify or potentially worsen the state of the original filesystem. Its primary function is to scan the specified device or image for valid btrfs structures and extract user data (files and directories) to a different, specified location.

This makes it an invaluable last-resort tool when a btrfs filesystem becomes unmountable or severely corrupted. It can often recover files even if the filesystem's metadata is partially damaged, by intelligently searching for extent and inode information. It prioritizes extracting user data and aims to preserve file attributes like permissions, ownership, and timestamps when possible. It does not repair the filesystem itself, nor does it create a new btrfs filesystem; its sole purpose is to retrieve accessible data from a damaged one.

btrfs-restore is a data extraction tool, not a filesystem repair utility. It operates in a read-only mode, so it will not fix or modify the original damaged filesystem.

While highly capable, it may not be able to recover all data from severely corrupted filesystems. Success depends on the extent and type of corruption.

Restored files might exhibit sparsity, especially if the original file was sparse or if data blocks were unrecoverable. Ensure the destination filesystem has sufficient free space to accommodate the recovered data, as it can be substantial.

The primary use case for btrfs-restore is to recover user data from a btrfs filesystem that has become unmountable, severely corrupted, or otherwise inaccessible due to hardware failure or software bugs. It acts as a crucial first step in a disaster recovery scenario, allowing administrators to retrieve valuable files before attempting more destructive repair operations or reformatting.

It is highly recommended to always restore data to a different physical disk or partition than the one being recovered from, to prevent any accidental overwrites or further damage. btrfs-restore can also be used on a disk image of the corrupted filesystem, which is often a safer approach for recovery.

The btrfs-restore utility is an integral part of the btrfs-progs suite, which provides user-space tools for managing the btrfs filesystem. The btrfs filesystem itself began development around 2007, with a focus on advanced features like snapshots, checksums, and self-healing.

As btrfs matured and gained adoption, the need for robust data recovery mechanisms became apparent. While btrfs offers built-in resilience, severe corruption or hardware failures can still render a filesystem inaccessible. btrfs-restore was developed to address this critical need, providing a safe, read-only method to extract user data from damaged filesystems without risking further corruption. Its development paralleled the growth and stabilization of the btrfs project, becoming a vital tool for administrators dealing with filesystem emergencies.

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