btrfs-progs: doc: add description of missing and example, of device remove

[platform/upstream/btrfs-progs.git] / Documentation / btrfs-device.asciidoc

diff --git a/Documentation/btrfs-device.asciidoc b/Documentation/btrfs-device.asciidoc
index 9784357..ee42ed3 100644 (file)
--- a/Documentation/btrfs-device.asciidoc
+++ b/Documentation/btrfs-device.asciidoc
@@ -43,7 +43,7 @@ See the section *TYPICAL USECASES* for some examples.
 
 SUBCOMMAND
 ----------
-*add* [-Kf] <dev> [<dev>...] <path>::
+*add* [-Kf] <device> [<device>...] <path>::
 Add device(s) to the filesystem identified by <path>.
 +
 If applicable, a whole device discard (TRIM) operation is performed prior to
@@ -62,26 +62,39 @@ do not perform discard (TRIM) by default
 -f|--force::::
 force overwrite of existing filesystem on the given disk(s)
 
-*remove* <dev>|<devid> [<dev>|<devid>...] <path>::
+*remove* <device>|<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.
 +
 It is possible to delete the device that was used to mount the filesystem. The
-device entry in mount table will be replaced by another device name with the
-lowest device id.
+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* <device>|<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.
@@ -203,6 +216,19 @@ data or the block groups occupy the whole first device.
 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
 ------------