btrfs-balance

Re-balance data across a Btrfs filesystem

TLDR

Show the status of a running or paused balance operation

$ sudo btrfs balance status [path/to/btrfs_filesystem]

Balance all block groups (slow; rewrites all blocks in filesystem)

$ sudo btrfs balance start [path/to/btrfs_filesystem]

Balance data block groups which are less than 15% utilized, running the operation in the background

$ sudo btrfs balance start --bg -dusage=[15] [path/to/btrfs_filesystem]

Balance a max of 10 metadata chunks with less than 20% utilization and at least 1 chunk on a given device devid (see btrfs filesystem show)

$ sudo btrfs balance start -musage=[20],limit=[10],devid=[devid] [path/to/btrfs_filesystem]

Convert data blocks to the raid6 and metadata to raid1c3 (see mkfs.btrfs(8) for profiles)

$ sudo btrfs balance start -dconvert=[raid6] -mconvert=[raid1c3] [path/to/btrfs_filesystem]

Convert data blocks to raid1, skipping already converted chunks (e.g. after a previous cancelled conversion operation)

$ sudo btrfs balance start -dconvert=[raid1],soft [path/to/btrfs_filesystem]

Cancel, pause, or resume a running or paused balance operation

$ sudo btrfs balance [cancel|pause|resume] [path/to/btrfs_filesystem]

-d|--data filters
    Apply filters to data chunks.

-m|--metadata filters
    Apply filters to metadata chunks.

-s|--system filters
    Apply filters to system chunks.

-f|--force
    Force operation. Overrides sanity checks, use with caution.

-v|--verbose
    Increase verbosity.

-n|--dry-run
    Dry-run mode. Shows what the balance operation would do without actually making any changes.

-ro
    Read-only mode. Balance will not perform any writes.

-start chunk_offset
    Start balance from a specific offset.

-cancel
    Cancel running balance.

-pause
    Pause running balance.

-resume
    Resume paused balance.

path
    Path to the Btrfs filesystem.

DESCRIPTION

The `btrfs balance` command is a crucial tool for managing space and performance in Btrfs filesystems.

Its primary function is to redistribute data and metadata chunks across the devices within the Btrfs pool. This is particularly useful after adding or removing devices, experiencing uneven space utilization across devices, or changing data/metadata profiles. Rebalancing can optimize performance by ensuring data is spread evenly, reducing the likelihood of bottlenecks due to a single device being overloaded. It's also essential after shrinking a filesystem to reclaim unused space from the underlying devices. The command reads and writes data based on filters and configurations specified by the user. Balance operation can also fix some situations where the file system will report near-full status even though there is free space. Balance operation can be a lengthy process, especially on large filesystems, as it involves copying large amounts of data. It's advisable to run it during off-peak hours. Interrupting a balance operation is generally safe, as Btrfs is designed to handle such interruptions, but it is not recommended if possible, to avoid filesystem inconsistencies and delays.

CAVEATS

Running a balance on a near-full filesystem can be risky and may lead to out-of-space errors. Always ensure sufficient free space before initiating a balance operation. Interrupting a balance operation is generally safe, but a full power loss during the process may lead to inconsistencies that require a scrub. Use the `--force` option with extreme caution, as it bypasses safety checks that prevent potentially destructive actions.

FILTERS

Filters allow you to specify criteria for chunks that will be rebalanced.
Common filters include: usage=percent (rebalance chunks with usage below a percentage), devid=device_id (rebalance chunks on a specific device), profile=profile_name (rebalance chunks with a specific profile, like RAID0, RAID1).

PRACTICAL EXAMPLES

Rebalance all data: btrfs balance start -dusage=0 /mnt/btrfs
Rebalance metadata on device ID 1: btrfs balance start -mdevid=1 /mnt/btrfs
Cancel an ongoing balance: btrfs balance cancel /mnt/btrfs

HISTORY

The `btrfs balance` command has been part of the Btrfs filesystem since its early development. It's been refined over time to improve its efficiency and reliability, adding features like filtering to target specific data and metadata chunks. The command's role has always been critical for maintaining a healthy and performant Btrfs filesystem, particularly in multi-device configurations. Development continues in response to changing storage technologies and user needs.