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 <subcommand> [options] [<arguments>]

Common subcommands and their basic syntax:
btrfs device add [options] <device> [...] <path>
btrfs device delete [options] <device> [...] <path>
btrfs device replace [options] <src_device> <target_device> <path>
btrfs device usage [options] <path>|<device>
btrfs device show [options] [<path>|<device>]

add
    Adds one or more devices to an existing Btrfs filesystem. This expands the total storage capacity and can improve redundancy if appropriate RAID profiles are used. Requires a subsequent balance operation to fully utilize the new space for existing data.

delete
    Removes one or more devices from a Btrfs filesystem. All data from the removed device(s) must be migrated to the remaining devices before the operation completes. This can shrink the filesystem or reduce its redundancy.

replace
    Replaces an existing device with a new one in a Btrfs filesystem. This is commonly used for migrating data from a failing drive to a healthy one, or upgrading to a larger capacity drive. Data is copied block-by-block from the source to the target.

usage
    Shows the used and free space information for each device within a Btrfs filesystem, or for a specific device. Provides details on allocated chunks, metadata, and data usage.

show
    Displays information about all devices associated with a given Btrfs filesystem path, or for a specific device. This includes device IDs, paths, sizes, and allocation status.

stats
    Reports I/O error statistics for devices in a Btrfs filesystem. Useful for monitoring device health and identifying potential hardware issues. Counters can be reset using an option.

scan
    Scans all available block devices on the system for Btrfs filesystems. This can help the kernel discover Btrfs volumes that might not be mounted or otherwise known.

ready
    Waits until all devices of a given Btrfs filesystem are available. Useful in scripts to ensure a multi-device filesystem is fully assembled before proceeding with other operations.

The btrfs device command is a crucial subcommand of the main btrfs utility, designed for managing and interacting with storage devices that constitute a Btrfs filesystem. Btrfs inherently supports spanning a filesystem across multiple block devices, and this command provides the necessary tools to add new devices, remove existing ones, replace failed or undersized devices, and query device-specific information.

It enables administrators to dynamically expand or or shrink a Btrfs filesystem by modifying its underlying device pool without unmounting, although performance may be affected during such operations. Key functionalities include ensuring data redundancy across devices, monitoring device health, and optimizing data distribution through rebalancing after device changes. This flexibility is a core strength of Btrfs, making btrfs device an indispensable tool for maintaining highly available and scalable storage solutions.

Caveats:
Root Privileges: All btrfs device operations require superuser (root) privileges.
Data Migration: Operations like delete and replace involve significant data movement. This can be time-consuming and I/O intensive. Ensure adequate time and system resources.
Data Integrity: While Btrfs is robust, improper use or power loss during critical operations can lead to data loss or filesystem corruption. Always ensure backups before performing significant device changes.
Balancing: Adding or deleting devices often necessitates a btrfs balance operation to redistribute data evenly across the new device configuration. This is not always automatic and might be required to fully utilize new space or reclaim old space.
Device Paths: Prefer using stable device paths (e.g., /dev/disk/by-id/, /dev/disk/by-uuid/, /dev/disk/by-path/) instead of volatile /dev/sdX names, especially in multi-device setups or across reboots, to prevent issues from device name changes.

When a device is added or removed using btrfs device, the filesystem's metadata and data are not automatically redistributed to fully utilize the new configuration. For instance, after adding a device, new data will prefer the empty space, but existing data remains on older devices. To fully rebalance the data chunks across all devices, the btrfs balance command must be explicitly run. Similarly, after deleting a device, all its data is moved, but the overall filesystem balance might still need optimization, particularly for optimal performance and redundancy levels.

Btrfs internally tracks devices by a unique ID (e.g., 'devid 1' as shown by btrfs device show). While you typically use the device's path (e.g., /dev/sdb) for commands, it's important to understand that Btrfs associates a stable internal ID with each device. In some complex scenarios, or when troubleshooting (especially if device paths change), referring to devices by their internal ID can be more reliable than transient /dev/sdX paths. The btrfs device replace command, for example, allows specifying the source device by its ID.

Btrfs (B-tree File System) was initially developed by Oracle in 2007 with a strong focus on advanced features like copy-on-write (CoW), snapshots, checksums, and integrated volume management. The btrfs device subcommand is fundamental to Btrfs's design philosophy, allowing for flexible storage management where filesystems can dynamically grow or shrink by adding or removing physical devices. Its development has been driven by the need for a modern, scalable filesystem that can handle large storage arrays and provide enterprise-grade features natively, without relying on external volume managers, making device management a core aspect from its inception.

btrfs(8), btrfs-filesystem(8), btrfs-balance(8), mkfs.btrfs(8), mount(8), df(1), lsblk(8)