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.