btrfs-device

Add one or more devices to a btrfs filesystem

$ sudo btrfs device add [path/to/block_device1] [[path/to/block_device2]] [path/to/btrfs_filesystem]

$ sudo btrfs device remove [path/to/device|device_id] [[...]]

$ sudo btrfs device stats [path/to/btrfs_filesystem]

$ sudo btrfs device scan --all-devices

$ sudo btrfs device usage [path/to/btrfs_filesystem]

btrfs device [options]

add [...]
    Add one or more devices to the filesystem. is a mount point of the filesystem.

delete [...]
    Remove one or more devices from the filesystem. is a mount point of the filesystem. The filesystem will migrate the data from that device to others before the device is removed. This can take a considerable amount of time.

ready [...]
    Mark one or more devices as ready after they have been added to the filesystem but were temporarily unavailable. is a mount point of the filesystem.

scan
    Scan all block devices and try to register them into the btrfs filesystem.

usage []
    Show usage information for each device in the filesystem. If is omitted, all mounted btrfs filesystems are displayed.

stats
    Show I/O error statistics per device.

global stats []
    Show global I/O error statistics across all devices. If is omitted, all mounted btrfs filesystems are displayed.

show []
    Show detailed information about the devices in the filesystem. If is omitted, all mounted btrfs filesystems are displayed.

balance
    Perform a balance operation to redistribute data and metadata across all devices.

The `btrfs device` command family in Linux provides tools for managing devices that are part of a Btrfs filesystem. Btrfs is a modern copy-on-write filesystem designed for advanced features such as snapshots, checksumming, and pooling multiple physical devices into a single logical filesystem. This command family facilitates adding, removing, showing, and even balancing data across devices. This is critical for maintaining the integrity, performance, and capacity of a Btrfs filesystem.
These operations often require careful consideration, especially when removing or replacing devices, as data loss can occur if not performed correctly. Balancing data can redistribute data across the remaining devices which might take a long time depending on the overall size.
It's crucial to understand the implications of each subcommand and to back up data before performing any potentially destructive actions.

Removing a device without sufficient space on the remaining devices can lead to data loss. Always check device space before removing. Consider using `btrfs filesystem df` before removing devices.

Devices are identified by their UUID, path, or device ID. The device ID is an internal identifier assigned by the filesystem.

Balancing can take a very long time. Use the `-d` and `-m` options of `btrfs balance` to fine-tune which data and metadata should be balanced.

Btrfs was designed to address limitations in older Linux filesystems. `btrfs device` commands have evolved alongside Btrfs itself, with new features and improvements added over time to enhance device management capabilities. Initial commit happened at 2007, and first stable kernel happened at 2014. It has been used to create large and robust file systems since then.

btrfs(8), btrfs-filesystem(8), btrfs-check(8), mkfs.btrfs(8)