6.4. Integrated Volume Management of Multiple Devices
A btrfs file system can be created on top of many devices, and more devices can be added after the file system has been created. By default, metadata will be mirrored across two devices and data will be striped across all devices present, however if only one device is present, metadata will be duplicated on that device.
6.4.1. Creating a File System with Multiple Devices
The
mkfs.btrfs command, as detailed in Section 6.1, “Creating a btrfs File System”, accepts the options -d for data, and -m for metadata. Valid specifications are:
raid0raid1raid10dupsingle
The
-m single option instructs that no duplication of metadata is done. This may be desired when using hardware raid.
Note
RAID 10 requires at least four devices to run correctly.
Example 6.1. Creating a RAID 10 btrfs File System
Create a file system across four devices (metadata mirrored, data striped).
# mkfs.btrfs /dev/device1 /dev/device2 /dev/device3 /dev/device4
Stripe the metadata without mirroring.
# mkfs.btrfs -m raid0 /dev/device1 /dev/device2
Use raid10 for both data and metadata.
# mkfs.btrfs -m raid10 -d raid10 /dev/device1 /dev/device2 /dev/device3 /dev/device4
Do not duplicate metadata on a single drive.
# mkfs.btrfs -m single /dev/device
Use the
single option to use the full capacity of each drive when the drives are different sizes.
# mkfs.btrfs -d single /dev/device1 /dev/device2 /dev/device3
To add a new device to an already created multi-device file system, use the following command:
# btrfs device add /dev/device1 /mount-point
After rebooting or reloading the btrfs module, use the
btrfs device scan command to discover all multi-device file systems. See Section 6.4.2, “Scanning for btrfs Devices” for more information.
6.4.2. Scanning for btrfs Devices
Use
btrfs device scan to scan all block devices under /dev and probe for btrfs volumes. This must be performed after loading the btrfs module if running with more than one device in a file system.
To scan all devices, use the following command:
# btrfs device scan
To scan a single device, use the following command:
# btrfs device scan /dev/device
6.4.3. Adding New Devices to a btrfs File System
Use the
btrfs filesystem show command to list all the btrfs file systems and which devices they include.
The
btrfs device add command is used to add new devices to a mounted file system.
The
btrfs filesystem balance command balances (restripes) the allocated extents across all existing devices.
An example of all these commands together to add a new device is as follows:
Example 6.2. Add a New Device to a btrfs File System
First, create and mount a btrfs file system. Refer to Section 6.1, “Creating a btrfs File System” for more information on how to create a btrfs file system, and to Section 6.2, “Mounting a btrfs file system” for more information on how to mount a btrfs file system.
# mkfs.btrfs /dev/device1 # mount /dev/device1
Next, add a second device to the mounted btrfs file system.
# btrfs device add /dev/device2 /mount-point
The metadata and data on these devices are still stored only on
/dev/device1. It must now be balanced to spread across all devices.
# btrfs filesystem balance /mount-point
Balancing a file system will take some time as it reads all of the file system's data and metadata and rewrites it across the new device.
6.4.4. Converting a btrfs File System
To convert a non-raid file system to a raid, add a device and run a balance filter that changes the chunk allocation profile.
Example 6.3. Converting a btrfs File System
To convert an existing single device system,
/dev/sdb1 in this case, into a two device, raid1 system in order to protect against a single disk failure, use the following commands:
# mount /dev/sdb1 /mnt # btrfs device add /dev/sdc1 /mnt # btrfs balance start -dconvert=raid1 -mconvert=raid1 /mnt
Important
If the metadata is not converted from the single-device default, it remains as DUP. This does not guarantee that copies of the block are on separate devices. If data is not converted it does not have any redundant copies at all.
6.4.5. Removing btrfs Devices
Use the
btrfs device delete command to remove an online device. It redistributes any extents in use to other devices in the file system in order to be safely removed.
Example 6.4. Removing a Device on a btrfs File System
First create and mount a few btrfs file systems.
# mkfs.btrfs /dev/sdb /dev/sdc /dev/sdd /dev/sde # mount /dev/sdb /mnt
Add some data to the file system.
Finally, remove the required device.
# btrfs device delete /dev/sdc /mnt
6.4.6. Replacing Failed Devices on a btrfs File System
Section 6.4.5, “Removing btrfs Devices” can be used to remove a failed device provided the super block can still be read. However, if a device is missing or the super block corrupted, the file system will need to be mounted in a degraded mode:
# mkfs.btrfs -m raid1 /dev/sdb /dev/sdc /dev/sdd /dev/sde ssd is destroyed or removed, use -o degraded to force the mount to ignore missing devices # mount -o degraded /dev/sdb /mnt 'missing' is a special device name # btrfs device delete missing /mnt
The command
btrfs device delete missing removes the first device that is described by the file system metadata but not present when the file system was mounted.
Important
It is impossible to go below the minimum number of devices required for the specific raid layout, even including the missing one. It may be required to add a new device in order to remove the failed one.
For example, for a raid1 layout with two devices, if a device fails it is required to:
- mount in degraded mode,
- add a new device,
- and, remove the missing device.
6.4.7. Registering a btrfs File System in /etc/fstab
If you do not have an
initrd or it does not perform a btrfs device scan, it is possible to mount a multi-volume btrfs file system by passing all the devices in the file system explicitly to the mount command.
Example 6.5. Example /etc/fstab Entry
An example of a suitable
/etc/fstab entry would be:
/dev/sdb /mnt btrfs device=/dev/sdb,device=/dev/sdc,device=/dev/sdd,device=/dev/sde 0
Note that using universally unique identifiers (UUIDs) also works and is more stable than using device paths.
