btrfs-convert - Linux

Overview

btrfs-convert is a powerful tool for converting filesystems between different formats, primarily designed for the Btrfs filesystem. It allows administrators and users to transform their existing filesystems to Btrfs, enabling them to take advantage of its advanced features for data integrity, RAID support, and snapshots.

Syntax

btrfs-convert [options] <source_device> <destination_device>

Options/Flags

  • –backup-convert: Create a backup of the source device before proceeding with the conversion.
  • –create-snapshot: Generate a snapshot of the source device to preserve the original state.
  • –dry-run: Simulate the conversion process without actually modifying the devices.
  • –force: Proceed with the conversion even if the destination device is not empty.
  • –no-check-source: Disable the integrity check of the source device.
  • –no-interrupt: Prevent the conversion process from being interrupted by user input.
  • –no-progress: Suppress the progress bar and output verbose information.
  • –no-repair: Do not attempt to repair any detected errors on the source device.

Examples

Simple Conversion: Convert a device named /dev/sda1 to Btrfs:

btrfs-convert /dev/sda1 /dev/sdb1

Conversion with Snapshot: Create a snapshot before converting /dev/sda2 to Btrfs, then mount the snapshot at /mnt/snapshot:

btrfs-convert --create-snapshot /dev/sda2 /dev/sdb2
mount /dev/sda2-snap /mnt/snapshot

Silent Conversion: Perform the conversion quietly, without any on-screen output:

btrfs-convert --no-progress /dev/sda3 /dev/sdb3

Common Issues

Insufficient Space on Destination: Ensure the destination device has enough free space to accommodate the converted data from the source device.

Device Busy or Locked: Close any open files or applications that might be using the source or destination device before attempting the conversion.

Filesystem Not Clean: If the source filesystem is corrupted or has pending writes, the conversion may fail. Run fsck on the source filesystem to detect and resolve any issues.

Integration

LVM Integration: Convert a logical volume (LV) to Btrfs while preserving LVM metadata and its configuration:

lvconvert -f --yes /dev/VG0/LV0 --btrfs

SystemD Service: Create a service that automatically mounts and checks newly converted Btrfs devices:

[Unit]
Description=Btrfs Auto Mount and Check Service
After=local-fs.target

[Service]
Type=oneshot
ExecStart=/usr/sbin/btrfs-convert --check-source /dev/new-device

[Install]
WantedBy=multi-user.target

Related Commands

  • btrfs-check: Verify the integrity of a Btrfs filesystem.
  • btrfs-filesystem: Create or delete a Btrfs filesystem on a device.
  • btrfs-mkfs: Format a device with a Btrfs filesystem.