Add, Inspect and Remove Btrfs Devices Safely

Growing a Btrfs filesystem with btrfs device add is easy; removing one without breaking your redundancy is not. This covers inspecting a mounted filesystem, adding a device, checking persistent error counters, and the conditions that let you remove a device at all. The examples match btrfs-progs 6.6.3, the installed version used here. Allow 20 to 30 minutes for inspection; adding or removing storage can take longer and should be planned separately.

• You need a mounted Btrfs filesystem, an unused block device for an add operation, and root privileges for most device-management commands.
• Substitute your own paths. Swap in your mount point for /mnt/btrfs and your device for /dev/sdb, never a guessed path: check it with lsblk first.

1. Confirm the command and the target filesystem

Start with read-only checks. These do not need elevated privileges unless your system restricts access to device information.

$ btrfs --version
btrfs-progs v6.6.3
$ findmnt -t btrfs
TARGET   SOURCE    FSTYPE OPTIONS
/mnt/btrfs /dev/sda btrfs  rw,relatime
$ lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINTS

The findmnt result is host-specific. Confirm that the path you will pass to btrfs device is the mounted filesystem itself, not a directory inside it: device management in this command group works on a mounted filesystem.

2. Inspect allocation before changing anything

Use usage to see device size, slack, allocated data and metadata profiles, and unallocated space.

$ sudo btrfs device usage /mnt/btrfs
/dev/sda, ID: 1
   Device size:           100.00GiB
   Device slack:              0.00B
   Data,single:            18.00GiB
   Metadata,single:         2.00GiB
   System,single:          32.00MiB
   Unallocated:            80.00GiB

• Device size is the size Btrfs sees, which may differ from the physical device size.
• Device slack is space made available by an earlier shrink.
• Unallocated is space available for new block groups. A normal user may see a warning that per-device usage needs root, so use sudo when the breakdown matters.

Profiles are independent for data, metadata and system block groups. A line such as Data,RAID1 describes Btrfs allocation policy, not necessarily a hardware RAID controller: treat RAID names as Btrfs profiles and check device count and sizes before predicting usable capacity.

3. Add an unused device

Adding a device changes filesystem metadata immediately, so this is an elevated and persistent operation. It does not copy existing data onto the new device; Btrfs uses the additional space as new block groups become available.

Check the exact device first.

$ lsblk -o NAME,MODEL,SERIAL,SIZE,FSTYPE,MOUNTPOINTS /dev/sdb
NAME MODEL  SERIAL SIZE FSTYPE MOUNTPOINTS
sdb  Example 1234  100G

If FSTYPE or MOUNTPOINTS shows anything unexpected, do not continue.

$ sudo btrfs device add /dev/sdb /mnt/btrfs
$ sudo btrfs device usage /mnt/btrfs

On this version, adding may perform a whole-device discard before the device is added. Use --nodiscard if that default is unsuitable. Warning: use --force only when you have deliberately confirmed that overwriting an existing filesystem signature is safe; it is destructive to the signature on the supplied device, not a general repair option.

4. Check persistent IO error counters

Run device statistics against the mounted filesystem or one of its devices.

$ sudo btrfs device stats /mnt/btrfs
[/dev/sda].write_io_errs   0
[/dev/sda].read_io_errs    0
[/dev/sda].flush_io_errs   0
[/dev/sda].corruption_errs 0
[/dev/sda].generation_errs 0

These counters record classes of IO and integrity errors and persist with the filesystem's device information. Non-zero values deserve investigation of the kernel log, cables, controller and device health before you treat the filesystem as healthy. A zero result is not a substitute for backups or a scrub.

For a monitoring check, --check returns zero when all counters are zero. On btrfs-progs 6.6.3, a non-zero counter adds 64 to the command's exit status, while 64 and 65 also identify statistics-reading failures described by the installed manual. Capture the status immediately.

$ sudo btrfs device stats --check /mnt/btrfs
$ printf 'stats exit status: %s\n' "$?"
stats exit status: 0

$ sudo btrfs device stats --reset /mnt/btrfs

5. Remove a device only after checking profiles

Removal is a data-moving operation and can take a long time. It also cannot violate the active profile constraints: removing one member from a two-device RAID1 filesystem fails, because the remaining filesystem would no longer meet the profile's two-device requirement.

• Do not convert profiles merely to remove a failing device. A balance may write new chunks onto the failing device.
• Use btrfs replace for a failing member instead.
• Plan ahead for a healthy device you intentionally want to retire: check the profile change, available workspace and redundancy impact first.

After those checks, the ordinary removal command is:

$ sudo btrfs device remove /dev/sdb /mnt/btrfs
$ sudo btrfs device usage /mnt/btrfs

Btrfs moves the device's data before completing the operation. Keep the filesystem mounted and do not treat a returned prompt as proof the device has disappeared: verify with the usage output. If several devices are listed, removal happens one at a time. The installed command has a safety timeout for this case; --force skips that timeout but does not override profile constraints, so do not use it casually.

For a filesystem mounted in degraded mode, the special device name missing can remove a device recorded in the metadata but absent at mount time. Use it only when you understand the degraded mount and the missing-device count; in RAID6, more than one missing device may require repeating missing.

6. Handle discovery and startup scans

Multi-device filesystems sometimes need their devices registered before an automated mount. Scan specific devices when you know which members are present.

$ sudo btrfs device scan /dev/sda /dev/sdb
$ sudo btrfs device ready /dev/sda

With no device arguments, scan uses blkid to find devices reporting Btrfs; --all-devices is the fallback when blkid is unavailable. Repeating a scan is safe for already registered devices. ready waits for the group to be registered, but does not guarantee the eventual mount will succeed.

--forget unregisters a device or stale devices. The relevant filesystem must be unmounted, so treat it as maintenance work and check mounts first.

$ findmnt -t btrfs
$ sudo btrfs device scan --forget /dev/sdb

If the device is still part of a mounted filesystem, the command should fail rather than unregister it. Do not turn that failure into a reason to stop the filesystem or remove a device without a recovery plan.