bcachefs-device

Format and add a new device to an existing filesystem.

$ sudo bcachefs device add --label=[group].[name] [path/to/mountpoint] [path/to/device]

$ bcachefs device evacuate [path/to/device]

$ bcachefs device remove [path/to/device]

bcachefs-device <subcommand> [options] <device-path|uuid|id> [...other_arguments]
bcachefs-device list [options] [device-path|uuid|id...]
bcachefs-device rescan

add
    Adds a new block device to an existing bcachefs filesystem. This typically involves specifying the path to the unformatted device.

remove
    Removes a device from the filesystem. Data on the removed device is migrated to other devices if necessary, unless --discard-data is used.

set =...
    Modifies specific properties or options for an existing device within the filesystem, such as its writeback status or allocation groups.

list [device...]
    Displays detailed information about all or specified devices within bcachefs filesystems, including their UUIDs, sizes, and states.

clear
    Erases all bcachefs metadata from a specified block device, preparing it for reuse outside of bcachefs or for re-addition.

uuid
    Prints the bcachefs UUID of a specified device.

rescan
    Scans for new or changed bcachefs devices across the system.

--force
    Used with some subcommands (e.g., remove, clear) to override safety checks and proceed with the operation.

--background
    Used with operations like remove to perform the data migration in the background, allowing the command to return immediately.

--discard-data
    Used with remove to quickly remove a device without migrating its data, resulting in data loss for data exclusively on that device.

The bcachefs-device command is a crucial utility within the bcachefs filesystem suite, designed for managing the physical storage devices that comprise a bcachefs filesystem. Bcachefs is a modern, high-performance Linux filesystem known for its advanced features like snapshots, data integrity, and caching capabilities, often built upon multiple underlying devices. This command allows administrators to add new storage devices to an existing bcachefs filesystem, expand its capacity, or remove devices as needed. It also facilitates querying detailed information about currently integrated devices, clearing bcachefs metadata from a device, or modifying device-specific properties. Effective use of bcachefs-device is essential for dynamically managing the storage layout and ensuring the health and scalability of bcachefs deployments. It typically operates on block devices such as disks or partitions, identified by their path (e.g., /dev/sdb), UUID, or internal bcachefs device ID.

Incorrect usage of bcachefs-device, especially subcommands like remove or clear, can lead to severe data loss. Always ensure you have a current backup before performing device-level modifications on a live filesystem. The command often requires root privileges for execution. As bcachefs is a relatively new filesystem to be mainline, its tools and functionalities are still evolving, and users should be aware of potential changes or edge cases. Performance implications should also be considered when adding or removing devices from an active filesystem.

Devices managed by bcachefs-device can be referred to by their kernel path (e.g., /dev/sdb), their bcachefs-specific UUID, or an internal device ID. Using UUIDs or internal IDs is often preferred for scripting and stability, as kernel paths can change upon reboot or device reordering.

When a device is removed from a bcachefs filesystem using bcachefs-device remove, the data stored on that device is typically migrated to other available devices in the filesystem. This process can be time-consuming depending on the amount of data and device speed. The --discard-data option can bypass this migration, but it will result in data loss for data exclusively on the removed device.

The bcachefs-device command is an integral part of the bcachefs filesystem utilities, developed primarily by Kent Overstreet. Bcachefs itself evolved from the `bcache` project, aiming to create a robust, feature-rich, and high-performance copy-on-write filesystem for Linux. Development has been ongoing for over a decade, with bcachefs-device appearing as part of the `bcachefs-tools` userspace package necessary to manage the filesystem. Bcachefs achieved mainline Linux kernel inclusion with version 6.7 in late 2023 / early 2024, bringing its advanced storage management capabilities, including device manipulation via commands like bcachefs-device, to a wider audience.

bcachefs(8), mkfs.bcachefs(8)