btrfs-balance - Linux

Overview

btrfs-balance is a utility for balancing data across devices in a Btrfs file system. It distributes data evenly to optimize performance and enhance storage utilization.

Syntax

btrfs-balance [options] <device>+

Options/Flags

  • -d, –devices : Number of devices to balance data across. Ignored if --full is used.
  • -f, –force: Skip checking for active snapshots. Caution: May lead to data loss if used inappropriately.
  • -m, –mail-on-finish: Send email notification on completion. Specify an email address after this option.
  • -n, –dry-run: Print the actions that would be taken without actually performing them.
  • -o, –old-threshold : Threshold for moving data from old chunks. Default: 128k
  • -s, –size [k|m|g|t]: Target size for each chunk. Default: 32M
  • -w, –workers : Number of balancing workers to use. Default: 1
  • –full: Balance the entire file system rather than a specific number of devices.
  • –log-level : Set the logging level (debug, info, warning, error, fatal). Default: info
  • –metadata: Balance only metadata chunks.
  • –no-wait: Do not wait for the balance operation to finish, return immediately.
  • –quiet: Suppress all output except for errors.
  • –rebalance: Only rebalance existing chunks, do not create new chunks.
  • –threshold : Threshold for moving data from new chunks. Default: 16k
  • –version: Display version information.

Examples

Balance across all devices:

btrfs-balance --full /dev/sd{a,b,c}

Balance only metadata chunks:

btrfs-balance --metadata /dev/sde /dev/sdf

Dry run and send email notification on completion:

btrfs-balance -n -m user@example.com /dev/sde /dev/sdf

Common Issues

  • Aborting the balance operation: Press Ctrl+C to terminate the process. Data that has already been moved will be retained.
  • Excessive time taken: Balancing large file systems can take a long time. Consider using multiple workers (-w) or using the --full option to improve efficiency.

Integration

Combine with other commands:

# Create a RAID1 array and balance data across it
mdadm --create --level=1 --raid-devices=2 /dev/md1 /dev/sda /dev/sdb
btrfs-balance --full /dev/md1

Use with scripts:

#!/bin/bash
# Monitor the balance operation and send email when complete
btrfs-balance --full /dev/sd{a,b,c} | tee /tmp/btrfs-balance.log
mail -s "Btrfs balance complete" user@example.com < /tmp/btrfs-balance.log

Related Commands

  • btrfs: The main Btrfs file system utility.
  • btrfs-mkfs: Create a Btrfs file system.
  • btrfs-check: Check the integrity of a Btrfs file system.