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 action [options] device [device ...]

online
    Bring specified device(s) online

offline
    Take device(s) offline safely

register
    Register device(s) to a bcachefs filesystem

unregister
    Unregister device(s) from filesystem

replace
    Replace a failed device with a new one

remove-member
    Remove device(s) as filesystem members

evacuate
    Move all data off device(s)

start-writeback
    Enable writeback caching on device(s)

stop-writeback
    Disable writeback on device(s)

--force
    Force operation, bypassing safety checks

--fs=<dev|UUID|label>
    Specify target filesystem

--label=<LABEL>
    Set device label

--sb-nr=<NR>
    Select superblock replica number

--inconsistent
    Allow inconsistent device state

--writeback_sync
    Synchronous writeback mode

The bcachefs-device command is a utility for administering block devices associated with a bcachefs filesystem. Bcachefs is an advanced Linux copy-on-write filesystem supporting multi-device setups for replication, erasure coding, compression, and high performance. This tool enables dynamic management of devices without always requiring filesystem downtime.

It supports actions like registering new devices to expand capacity, bringing devices online/offline for maintenance, unregistering or replacing failed devices, evacuating data, and configuring modes such as read-only or writeback. Devices must first be formatted or registered to a specific filesystem identified by UUID, label, or superblock device. Root privileges are required, and operations interact directly with on-disk superblocks.

Common use cases include growing filesystems by adding drives, handling disk failures via replacement, or temporarily offlining devices for firmware updates. Misuse risks data corruption, so backups and verification with bcachefs device-list are recommended. Integrated with the broader bcachefs toolset for filesystem maintenance.

Dangerous operations like unregister or evacuate can cause data loss if devices hold unreplicated data. Always run bcachefs device-list first and ensure redundancy. Not for unformatted devices; use bcachefs format. Requires root.

Specify filesystem with --fs if ambiguous: bcachefs-device --fs=/dev/sda1 register /dev/sdb
View status: bcachefs device-list.

Part of bcachefs-tools, developed by Kent Overstreet since 2015. Device management features stabilized around 2022-2023 with bcachefs 1.0 release. Merged into Linux kernel 6.7 (Dec 2023) as stable filesystem.

bcachefs(8), mkfs.bcachefs(8), bcachefs-gc(8)