How to use the command btrfs balance (with examples)

The btrfs balance command is used to balance block groups on a btrfs filesystem. It allows you to redistribute data across different devices and optimize the usage of storage space. This article will provide examples of various use cases for the btrfs balance command.

Use case 1: Show the status of a running or paused balance operation

Code:

sudo btrfs balance status path/to/btrfs_filesystem

Motivation:

You may want to check the progress and status of a running or paused balance operation on a btrfs filesystem.

Explanation:

• sudo: This command allows you to run the btrfs balance command with root privileges.
• btrfs balance status: This option is used to show the status of a running or paused balance operation.
• path/to/btrfs_filesystem: This specifies the path to the btrfs filesystem for which you want to check the balance operation status.

Example output:

Balance on '/path/to/btrfs_filesystem' is running

Use case 2: Balance all block groups

Code:

sudo btrfs balance start path/to/btrfs_filesystem

Motivation:

You may want to balance all block groups on a btrfs filesystem to ensure even distribution of data across devices and optimize storage usage.

Explanation:

• sudo: This command allows you to run the btrfs balance command with root privileges.
• btrfs balance start: This option starts the balance operation on the specified btrfs filesystem.
• path/to/btrfs_filesystem: This specifies the path to the btrfs filesystem for which you want to start the balance operation.

Example output:

Start balancing '/path/to/btrfs_filesystem'

Use case 3: Balance data block groups based on utilization

Code:

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

Motivation:

You may want to balance the data block groups on a btrfs filesystem that are less than 15% utilized. This helps to redistribute the data and optimize storage usage.

Explanation:

• sudo: This command allows you to run the btrfs balance command with root privileges.
• btrfs balance start: This option starts the balance operation on the specified btrfs filesystem.
• --bg: This flag runs the balance operation in the background.
• -dusage=15: This option specifies that only data block groups with less than 15% utilization should be balanced.
• path/to/btrfs_filesystem: This specifies the path to the btrfs filesystem for which you want to start the balance operation.

Example output:

Start balancing data block groups with utilization less than 15% on '/path/to/btrfs_filesystem'

Use case 4: Balance metadata chunks based on utilization and device ID

Code:

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

Motivation:

You may want to balance a maximum of 10 metadata chunks on a btrfs filesystem with less than 20% utilization. Additionally, you may want to ensure that at least 1 metadata chunk is present on a specific device.

Explanation:

• sudo: This command allows you to run the btrfs balance command with root privileges.
• btrfs balance start: This option starts the balance operation on the specified btrfs filesystem.
• -musage=20: This option specifies that only metadata chunks with less than 20% utilization should be balanced.
• limit=10: This option limits the balance operation to a maximum of 10 metadata chunks.
• devid=devid: This specifies the specific device ID (as shown in btrfs filesystem show) where at least 1 metadata chunk should be present.
• path/to/btrfs_filesystem: This specifies the path to the btrfs filesystem for which you want to start the balance operation.

Example output:

Start balancing metadata chunks with utilization less than 20% and devid=devid on '/path/to/btrfs_filesystem'

Use case 5: Convert data and metadata blocks to specific RAID levels

Code:

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

Motivation:

You may want to convert the data blocks to RAID 6 and the metadata blocks to RAID 1C3. This allows you to change the redundancy level of the data and metadata for improved data protection.

Explanation:

• sudo: This command allows you to run the btrfs balance command with root privileges.
• btrfs balance start: This option starts the balance operation on the specified btrfs filesystem.
• -dconvert=raid6: This option converts the data blocks to RAID 6, which provides two-disk failure tolerance.
• -mconvert=raid1c3: This option converts the metadata blocks to RAID 1C3, which provides three-disk copies for metadata.
• path/to/btrfs_filesystem: This specifies the path to the btrfs filesystem for which you want to start the balance operation.

Example output:

Start converting data blocks to RAID 6 and metadata blocks to RAID 1C3 on '/path/to/btrfs_filesystem'

Use case 6: Convert data blocks to RAID 1, skipping already converted chunks

Code:

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

Motivation:

You may want to convert the data blocks to RAID 1, but skip the chunks that have already been converted during a previous balance operation. This allows you to continue the conversion process without re-balancing the entire filesystem.

Explanation:

• sudo: This command allows you to run the btrfs balance command with root privileges.
• btrfs balance start: This option starts the balance operation on the specified btrfs filesystem.
• -dconvert=raid1,soft: This option converts the data blocks to RAID 1, but skips any chunks that have already been converted during a previous balance operation. The “soft” option ensures that only missing chunks are converted.
• path/to/btrfs_filesystem: This specifies the path to the btrfs filesystem for which you want to start the balance operation.

Example output:

Start converting data blocks to RAID 1 (soft) on '/path/to/btrfs_filesystem'

Use case 7: Cancel, pause, or resume a running or paused balance operation

Code:

sudo btrfs balance cancel|pause|resume path/to/btrfs_filesystem

Motivation:

You may want to cancel, pause, or resume a running or paused balance operation on a btrfs filesystem.

Explanation:

• sudo: This command allows you to run the btrfs balance command with root privileges.
• btrfs balance cancel: This option cancels the balance operation on the specified btrfs filesystem.
• btrfs balance pause: This option pauses the balance operation on the specified btrfs filesystem.
• btrfs balance resume: This option resumes the balance operation on the specified btrfs filesystem.
• path/to/btrfs_filesystem: This specifies the path to the btrfs filesystem for which you want to cancel, pause, or resume the balance operation.

Example output:

Cancel balance operation on '/path/to/btrfs_filesystem'

Conclusion:

The btrfs balance command provides a powerful set of options to balance and optimize the data distribution on a btrfs filesystem. By using these examples, you can effectively manage the storage space and data protection levels of your btrfs filesystems.