btrfs-balance
Re-balance data across a Btrfs filesystem
TLDR
Show the status of a running or paused balance operation
Balance all block groups (slow; rewrites all blocks in filesystem)
Balance data block groups which are less than 15% utilized, running the operation in the background
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)
Convert data blocks to the raid6 and metadata to raid1c3 (see mkfs.btrfs(8) for profiles)
Convert data blocks to raid1, skipping already converted chunks (e.g. after a previous cancelled conversion operation)
Cancel, pause, or resume a running or paused balance operation
SYNOPSIS
btrfs balance options path
PARAMETERS
-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.
SEE ALSO
btrfs(8), btrfs-filesystem(8), btrfs-scrub(8), btrfs-device(8)