btrfs-image - Linux
Overview
btrfs-image is a versatile command that allows for the creation and manipulation of Btrfs filesystem images. These images are commonly used for backups or storing snapshots of a Btrfs filesystem. The command offers a range of options for creating, examining, and extracting from these images.
Syntax
btrfs-image COMMAND [OPTIONS] IMAGE
Where COMMAND can be:
convert - Convert an existing block device or file to a Btrfs image
create - Create a new file-based Btrfs image
diff - Compare two Btrfs images
dump - Dump the contents of a Btrfs image
extract - Extract files or subvolumes from a Btrfs image
fill - Fill a device or file with random data
find - Search for files or subvolumes in a Btrfs image
info - Show information about a Btrfs image
list - List files or subvolumes in a Btrfs image
overlay - Overlay a Btrfs image onto a device
probe - Probe a device or file to determine if it contains a Btrfs image
replace - Replace a subvolume in a Btrfs image
snapshot - Create a snapshot of a Btrfs image
verify - Verify the integrity of a Btrfs image
Options/Flags
convert:
-f
,--force
: Force conversion, even if the input is not a valid block device or file.-s
,--size
: Specify the size of the output image in bytes.
create:
-f
,--force
: Force creation, even if the output file already exists.-s
,--size
: Specify the size of the image to create in bytes.
diff:
-p
,--patch
: Generate a patch file describing the differences between the two images.
dump:
-d
,--dump-tree
: Dump the tree structure of the image.-e
,--export-tree
: Export the tree structure of the image to a file.
extract:
-f
,--file
: Specify a file within the image to extract.-s
,--subvolume
: Specify a subvolume within the image to extract.-d
,--directory
: Specify a directory to extract the files to.
fill:
-f
,--force
: Force filling, even if the output device or file already exists.-s
,--size
: Specify the size of the device or file to fill in bytes.
find:
-f
,--file
: Search for a specific file in the image.-s
,--subvolume
: Search for a specific subvolume in the image.
info:
-v
,--verbose
: Display more detailed information about the image.
list:
-f
,--file
: List files within the image.-s
,--subvolume
: List subvolumes within the image.
overlay:
-f
,--force
: Force overlay, even if the target device is already in use.-d
,--device
: Specify the target device to overlay the image onto.
probe:
-v
,--verbose
: Display more detailed information about the probed device or file.
replace:
-f
,--file
: Specify the file to replace within the image.-s
,--subvolume
: Specify the subvolume to replace within the image.-d
,--data
: Specify the data to replace the existing data with.
snapshot:
-f
,--force
: Force snapshot creation, even if the output file already exists.-s
,--size
: Specify the size of the snapshot in bytes.
verify:
-v
,--verbose
: Display more detailed information about the verification process.
Examples
Create a new Btrfs image file:
btrfs-image create --size 1GB image-file.img
Dump the contents of a Btrfs image to a file:
btrfs-image dump --dump-tree image-file.img output-tree.txt
Extract a file from a Btrfs image:
btrfs-image extract --file /path/to/file.txt image-file.img extract-dir
Search for a file within a Btrfs image:
btrfs-image find --file "file-pattern" image-file.img
Common Issues
Error: The image is too large for the output device:
This error occurs when you are trying to convert or overlay an image that is larger than the target device. Resize the device or use a larger image file.
Error: The device already contains a Btrfs filesystem:
This error occurs when you are trying to convert or overlay an image onto a device that already has a Btrfs filesystem. Use the --force
option to override the existing filesystem.
Integration
Use btrfs-image with btrfs-progs to create a bootable USB drive:
btrfs-image create --size 1GB usb-image.img
btrfs-progs mkfs.btrfs -d /dev/sda1 usb-image.img
Related Commands
btrfs
: Manage Btrfs filesystems.btrfs-subvolume
: Manage subvolumes within a Btrfs filesystem.dd
: Copy data from one file or device to another.