policies. There's some similarity with traditional RAID levels, but this could
be confusing to users familiar with the traditional meaning. Due to the
similarity, the RAID terminology is widely used in the documentation. See
-`mkfs.btrfs`(9) for more details and the exact profile capabilities and
+`mkfs.btrfs`(8) for more details and the exact profile capabilities and
constraints.
The device management works on a mounted filesystem. Devices can be added,
-removed or replaced, by commands profided by *btrfs device* and *btrfs replace*.
+removed or replaced, by commands provided by *btrfs device* and *btrfs replace*.
The profiles can be also changed, provided there's enough workspace to do the
conversion, using the *btrfs balance* command and namely the filter 'convert'.
Profile::
A profile describes an allocation policy based on the redundancy/replication
-constrants in connection with the number of devices. The profile applies to
+constraints in connection with the number of devices. The profile applies to
data and metadata block groups separately.
RAID level::
SUBCOMMAND
----------
-*add* [-Kf] <dev
> [<dev>...] <path>::
+*add* [-Kf] <dev
ice> [<device>...] <path>::
Add device(s) to the filesystem identified by <path>.
+
If applicable, a whole device discard (TRIM) operation is performed prior to
-f|--force::::
force overwrite of existing filesystem on the given disk(s)
-*remove* <dev
>|<devid> [<dev>|<devid>...] <path>::
+*remove* <dev
ice>|<devid> [<device>|<devid>...] <path>::
Remove device(s) from a filesystem identified by <path>
+
Device removal must satisfy the profile constraints, otherwise the command
fails. The filesystem must be converted to profile(s) that would allow the
removal. This can typically happen when going down from 2 devices to 1 and
-using the RAID1 profile. See the example section below.
+using the RAID1 profile. See the *TYPICAL USECASES* section below.
+
The operation can take long as it needs to move all data from the device.
+
-NOTE: It is not possible to delete the device that was used to mount the
-filesystem. This is a limitation given by the VFS.
+It is possible to delete the device that was used to mount the filesystem. The
+device entry in the mount table will be replaced by another device name with
+the lowest device id.
++
+If the filesystem is mounted in degraded mode (-o degraded), special term
+'missing' can be used for 'device'. In that case, the first device that is
+described by the filesystem metadata, but not present at the mount time will be
+removed.
++
+NOTE: In most cases, there is only one missing device in degraded mode,
+otherwise mount fails. If there are two or more devices missing (e.g. possible
+in RAID6), you need specify 'missing' as many times as the number of missing
+devices to remove all of them.
-*delete* <dev
>|<devid> [<dev>|<devid>...] <path>::
+*delete* <dev
ice>|<devid> [<device>|<devid>...] <path>::
Alias of remove kept for backward compatibility
*ready* <device>::
-Wait until all devices of a multiple-device filesystem are scanned and registered
-within the kernel module.
+Wait until all devices of a multiple-device filesystem are scanned and
+registered within the kernel module. This is to provide a way for automatic
+filesystem mounting tools to wait before the mount can start. The device scan
+is only one of the preconditions and the mount can fail for other reasons.
+Normal users usually do not need this command and may safely ignore it.
*scan* [(--all-devices|-d)|<device> [<device>...]]::
Scan devices for a btrfs filesystem and register them with the kernel module.
an alternative way of mounting multiple-device filesystem without the need for
prior scanning. See the mount option 'device'.
-*stats* [
-zs] <path>|<device>::
+*stats* [
options] <path>|<device>::
Read and print the device IO error statistics for all devices of the given
filesystem identified by <path> or for a single <device>. The filesystem must
be mounted. See section *DEVICE STATS* for more information about the reported
-z|--reset::::
Print the stats and reset the values to zero afterwards.
--s::::
-Set bit 6 of the return-code if any error statistics are non-zero.
+-c|--check::::
+Check if the stats are all zeros and return 0 it this is so. Set bit 6 of the
+return code if any of the statistics is no-zero. The error values is 65 if
+reading stats from at least one device failed, otherwise it's 64.
*usage* [options] <path> [<path>...]::
Show detailed information about internal allocations in devices.
$ btrfs balance start -mconvert=raid1 /mnt
-This operation can take a while as the metadata have to be moved and all block
-pointers updated. Depending on the physical locations of the old and new
+This operation can take a while, because al metadata have to be moved and all
+block pointers updated. Depending on the physical locations of the old and new
blocks, the disk seeking is the key factor affecting performance.
You'll note that the system block group has been also converted to RAID1, this
normally happens as the system block group also holds metadata (the physical to
-logial mappings).
+logical mappings).
What changed:
-* available data space decreased by 3GiB, usable rougly (50 - 3) + (100 - 3) = 144 GiB
+* available data space decreased by 3GiB, usable roughly (50 - 3) + (100 - 3) = 144 GiB
* metadata redundancy increased
IOW, the unequal device sizes allow for combined space for data yet improved
The device size of '/dev/sdb' as seen by the filesystem remains unchanged, but
the logical space from 50-100GiB will be unused.
+==== REMOVE DEVICE ====
+
+Device removal must satisfy the profile constraints, otherwise the command
+fails. For example:
+
+ $ btrfs device remove /dev/sda /mnt
+ ERROR: error removing device '/dev/sda': unable to go below two devices on raid1
+
+In order to remove a device, you need to convert the profile in this case:
+
+ $ btrfs balance start -mconvert=dup -dconvert=single /mnt
+ $ btrfs device remove /dev/sda /mnt
+
DEVICE STATS
------------
projects / platform / upstream / btrfs-progs.git / blobdiff