btrfs-device

Add one or more devices to a btrfs filesystem

$ sudo btrfs [[d|device]] [[a|add]] [path/to/block_device1 path/to/block_device2 ...] [path/to/btrfs_filesystem]

$ sudo btrfs [[d|device]] [[rem|remove]] [path/to/device1|device_id1 path/to/device2|device_id2 ...]

$ sudo btrfs [[d|device]] [[st|stats]] [path/to/btrfs_filesystem]

$ sudo btrfs [[d|device]] [[sc|scan]] [[-d|--all-devices]]

$ sudo btrfs [[d|device]] [[u|usage]] [path/to/btrfs_filesystem]

btrfs device add [-f] [-K] <device>... <path> | delete|remove <device>... <path> | scan | stats [-c] [-z] [-p <period>] <path> | usage [-h] <path>

-f, --force
    Force overwrite of existing filesystem on device (add)

-K, --keep-nocow
    Disable copy-on-write for new data on added device

-z, --reset
    Reset statistics counters (stats)

-c
    List per-device statistics (stats)

-p period
    Set statistics sampling period in seconds (stats)

-h
    Human-readable output format (usage)

The btrfs device subcommands manage multi-device configurations in BTRFS filesystems, supporting RAID-like setups for redundancy, performance, and capacity expansion. BTRFS treats devices as members of a volume, allowing dynamic addition or removal without downtime.

add incorporates new devices, automatically balancing data across them based on the filesystem's profile (e.g., single, RAID1, RAID10). Data is relocated as needed.

delete or remove safely removes devices after migrating data to remaining ones, preserving integrity. scan detects BTRFS superblocks on devices, useful at boot. stats monitors I/O activity per device, aiding performance tuning. usage reports detailed space allocation, unallocated areas, and device roles.

These tools require kernel support and btrfs-progs package. Most operations need a mounted filesystem (except scan), and changes can be time-intensive on large volumes. Ideal for servers needing flexible storage.

Most subcommands require mounted filesystem; ensure free space > relocation needs before delete/remove. Operations block on data balancing. Avoid on degraded volumes without backups. Scan ignores mount status.

Devices specified by path (/dev/sdX) or id (MINOR(mmc)/MAJOR(dev)). Use btrfs fi show to list ids.

Introduced in btrfs-progs v0.19 (2009-2010) with kernel 2.6.29 multi-device support. Evolved with RAID5/6 (kernel 3.9, later deprecated), zoned storage, and reliability fixes in progs v5+ (2020s).

btrfs(8), mkfs.btrfs(8), btrfs-balance(8), btrfs-scrub(8)