btrfs-balance

Show the status of a running or paused balance operation

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

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

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

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

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

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

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

btrfs balance start [options] <path>
btrfs balance cancel <path>
btrfs balance status <path>
btrfs balance resume <path>

path
    The mount point of the Btrfs filesystem to balance.

-d <filters>
    Specifies filters for data chunks. Common filters include usage, devid, convert, limit, and soft.

-m <filters>
    Specifies filters for metadata chunks. Similar to data chunk filters.

-s <filters>
    Specifies filters for system chunks. Less frequently used.

-f
    Force a full balance, even if the filesystem is on a single device or already balanced.

-v
    Enable verbose output, showing progress and detailed information during the balance operation.

usage=
    A filter (used with -d, -m, -s) to balance chunks that are less than the specified percentage used.

devid=
    A filter (used with -d, -m, -s) to balance chunks residing on the device with the specified ID.

convert=
    A filter (used with -d, -m, -s) to convert chunk allocation profile to profile (e.g., raid1, single, dup).

limit=
    A filter (used with -d, -m, -s) to limit the number of chunks to balance to count.

soft
    A filter (used with -d, -m, -s) that performs a 'soft' balance, skipping chunks that are sufficiently filled, reducing I/O.

The btrfs balance command is a crucial utility for managing Btrfs filesystems, designed to rebalance and reorganize the allocation of data, metadata, and system chunks across all devices within a Btrfs volume. Its primary purpose is to redistribute chunks, ensuring optimal space utilization and performance, especially after significant filesystem changes like adding or removing devices, or after extensive file deletions. It can also be used to convert chunk profiles (e.g., from single to RAID1), reclaim fragmented free space, or evacuate data from a specific device.

The balance operation works by iterating through existing chunks and, based on specified filters, relocating them. This process involves reading data from its current location and writing it to a new, potentially better-suited location on the filesystem. Due to its I/O-intensive nature, a balance operation can be very time-consuming and impact system performance. It supports various filters to control which chunks are processed, such as usage (chunks with a certain percentage of free space), devid (chunks on specific devices), convert (change chunk profile), and limit (number of chunks to process).

btrfs balance can be extremely I/O-intensive and time-consuming, potentially impacting system performance significantly while running. It requires available free space to move data; if the filesystem is nearly full, the balance may fail. It primarily reclaims unused space within Btrfs-allocated chunks, not necessarily the free space reported by standard tools like df. A full balance on large or busy filesystems can take many hours or even days. While generally safe, it's advisable to run it during periods of low activity and ensure proper backups.

The btrfs balance utility operates with specific subcommands:
start: Initiates a balance operation with specified filters.
cancel: Immediately stops a running balance operation.
status: Displays the current status and progress of a balance operation.
resume: Resumes a previously cancelled or interrupted balance operation from where it left off.

The progress of a running balance can be monitored using the btrfs balance status <path> command, which provides real-time updates on chunks processed, estimated time, and any errors.

The btrfs balance command is an intrinsic and fundamental feature of the Btrfs filesystem, evolving alongside Btrfs development since its early stages. Its functionality, particularly the range of filters and performance optimizations, has been continuously refined over the years to address various use cases, from device management to space reclamation and profile conversion. It has always been a key tool for maintaining the health and efficiency of Btrfs volumes.

btrfs(8): The main Btrfs administration command., btrfs-device(8): Manages devices within a Btrfs filesystem., btrfs-filesystem(8): Provides filesystem-level utilities, including disk usage information., btrfs-replace(8): Replaces a device in a Btrfs filesystem.