How to use the command 'btrfs restore' (with examples)

The ‘btrfs restore’ command is used to salvage files from a damaged btrfs filesystem. It allows users to restore files from a corrupted filesystem to a specified directory. This command is particularly useful when attempting to recover important data from a damaged btrfs filesystem.

Use case 1: Restore all files from a btrfs filesystem to a given directory

Code:

sudo btrfs restore path/to/btrfs_device path/to/target_directory

Motivation: The motivation behind using this command is to recover all files from a damaged btrfs filesystem and restore them to a specific directory. This can be useful for recovering data from a corrupted filesystem or when migrating data to a different storage medium.

Explanation:

• sudo: The ‘sudo’ command is used to execute the ‘btrfs restore’ command with administrative privileges.
• btrfs restore: This is the main command that performs the file restoration operation.
• path/to/btrfs_device: Specifies the path to the damaged btrfs filesystem from which files will be restored.
• path/to/target_directory: Specifies the directory where the restored files will be saved.

Example output: The ‘btrfs restore’ command will restore all files from the specified btrfs filesystem to the target directory.

Use case 2: List (don’t write) files to be restored from a btrfs filesystem

Code:

sudo btrfs restore --dry-run path/to/btrfs_device path/to/target_directory

Motivation: The motivation behind using this command is to list the files that would be restored from a btrfs filesystem without actually performing the restoration. This can be useful for previewing the files that can be recovered before proceeding with the restoration process.

Explanation:

• --dry-run: This option tells the ‘btrfs restore’ command to simulate the file restoration process without actually writing any files.
• Other arguments are the same as in the previous use case.

Example output: The ‘btrfs restore –dry-run’ command will list the files that would be restored from the specified btrfs filesystem, without actually restoring them.

Use case 3: Restore files matching a given regex (case-insensitive) from a btrfs filesystem

Code:

sudo btrfs restore --path-regex regex -c path/to/btrfs_device path/to/target_directory

Motivation: This command can be used to restore only specific files based on a given regular expression. This allows users to selectively restore files that match a certain pattern, which can be useful for recovering specific types of files from a damaged btrfs filesystem.

Explanation:

• --path-regex regex: This option specifies a regular expression that will be used to match the paths of the files to be restored. Only files that match the provided regex will be restored.
• -c: This option makes the regular expression case-insensitive.
• Other arguments are the same as in the previous use case.

Example output: The ‘btrfs restore –path-regex regex -c’ command will restore only the files matching the given regular expression from the specified btrfs filesystem to the target directory.

Use case 4: Restore files from a btrfs filesystem using a specific root tree ‘bytenr’

Code:

sudo btrfs restore -t bytenr path/to/btrfs_device path/to/target_directory

Motivation: This command can be used to restore files from a specific root tree by providing its bytenr. This can be useful when multiple root trees exist in the btrfs filesystem, and the user wants to restore files from a specific root tree.

Explanation:

• -t bytenr: This option specifies the root tree by providing its bytenr. Bytenr is a unique identifier of each root tree in the btrfs filesystem.
• Other arguments are the same as in the previous use case.

Example output: The ‘btrfs restore -t bytenr’ command will restore files from the specified root tree (identified by its bytenr) of the btrfs filesystem to the target directory.

Use case 5: Restore files from a btrfs filesystem, overwriting files in the target

Code:

sudo btrfs restore --metadata --xattr --symlinks --overwrite path/to/btrfs_device path/to/target_directory

Motivation: The motivation behind using this command is to restore files from a btrfs filesystem while overwriting any existing files in the target directory. This can be useful when performing a complete restoration of the filesystem and ensuring that the target directory reflects the latest state of the restored files.

Explanation:

• --metadata: This option tells the ‘btrfs restore’ command to restore metadata along with the files. Metadata includes information such as file permissions, timestamps, and ownership.
• --xattr: This option restores extended attributes of the files. Extended attributes are additional metadata associated with a file, such as security labels.
• --symlinks: This option restores symbolic links in addition to regular files.
• --overwrite: This option specifies that existing files in the target directory should be overwritten if they have the same name as the restored files.
• Other arguments are the same as in the previous use case.

Example output: The ‘btrfs restore –metadata –xattr –symlinks –overwrite’ command will restore files from the specified btrfs filesystem to the target directory, overwriting any existing files with the same name. The restored files will include metadata, extended attributes, and symbolic links.