[v3,2/2] btrfs-progs: doc: add description of missing and example of device remove
diff mbox

Message ID d5e0465d-9606-1881-84a7-86c0d43e0033@jp.fujitsu.com
State New
Headers show

Commit Message

Misono Tomohiro Oct. 16, 2017, 4:56 a.m. UTC
This patch updates help/document of "btrfs device remove" in two points:

1. Add explanation of 'missing' for 'device remove'. This is only
written in wikipage currently.
(https://btrfs.wiki.kernel.org/index.php/Using_Btrfs_with_Multiple_Devices)

2. Add example of device removal in the man document. This is because
that explanation of "remove" says "See the example section below", but
there is no example of removal currently.

Signed-off-by: Tomohiro Misono <misono.tomohiro@jp.fujitsu.com>
Reviewed-by: Satoru Takeuchi <satoru.takeuchi@gmail.com>
---
 Documentation/btrfs-device.asciidoc | 19 ++++++++++++++++++-
 cmds-device.c                       |  8 ++++++++
 2 files changed, 26 insertions(+), 1 deletion(-)

Comments

Nikolay Borisov Oct. 16, 2017, 9:22 a.m. UTC | #1
On 16.10.2017 07:56, Misono, Tomohiro wrote:
> This patch updates help/document of "btrfs device remove" in two points:
> 
> 1. Add explanation of 'missing' for 'device remove'. This is only
> written in wikipage currently.
> (https://btrfs.wiki.kernel.org/index.php/Using_Btrfs_with_Multiple_Devices)
> 
> 2. Add example of device removal in the man document. This is because
> that explanation of "remove" says "See the example section below", but
> there is no example of removal currently.
> 
> Signed-off-by: Tomohiro Misono <misono.tomohiro@jp.fujitsu.com>
> Reviewed-by: Satoru Takeuchi <satoru.takeuchi@gmail.com>
> ---
>  Documentation/btrfs-device.asciidoc | 19 ++++++++++++++++++-
>  cmds-device.c                       |  8 ++++++++
>  2 files changed, 26 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/btrfs-device.asciidoc b/Documentation/btrfs-device.asciidoc
> index 88822ec..dd60415 100644
> --- a/Documentation/btrfs-device.asciidoc
> +++ b/Documentation/btrfs-device.asciidoc
> @@ -68,13 +68,17 @@ 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.
> ++
> +If device is mounted as degraded mode (-o degraded), special term "missing"
	^ filesystem	^ in
> +can be used for <device>. In that case, the first device that is described by> +the filesystem metadata, but not preseted at the mount time will be
removed.
					^ present

Also, what happens if there are 2 or more devices missing, will those be
deleted as well or just the first device? If all missing devices are
handled then this needs to be reflected in the documentation.

>  
>  *delete* <device>|<devid> [<device>|<devid>...] <path>::
>  Alias of remove kept for backward compatibility
> @@ -206,6 +210,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
>  ------------
>  
> diff --git a/cmds-device.c b/cmds-device.c
> index 3b6b985..d28ed0f 100644
> --- a/cmds-device.c
> +++ b/cmds-device.c
> @@ -224,9 +224,16 @@ static int _cmd_device_remove(int argc, char **argv,
>  	return !!ret;
>  }
>  
> +#define COMMON_USAGE_REMOVE_DELETE \
> +	"", \
> +	"If 'missing' is specified for <device>, the first device that is", \
> +	"described by the filesystem metadata, but not presented at the", \
> +	"mount time will be removed."
> +
>  static const char * const cmd_device_remove_usage[] = {
>  	"btrfs device remove <device>|<devid> [<device>|<devid>...] <path>",
>  	"Remove a device from a filesystem",
> +	COMMON_USAGE_REMOVE_DELETE,
>  	NULL
>  };
>  
> @@ -238,6 +245,7 @@ static int cmd_device_remove(int argc, char **argv)
>  static const char * const cmd_device_delete_usage[] = {
>  	"btrfs device delete <device>|<devid> [<device>|<devid>...] <path>",
>  	"Remove a device from a filesystem (alias of \"btrfs device remove\")",
> +	COMMON_USAGE_REMOVE_DELETE,
>  	NULL
>  };
>  
> 
--
To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Misono Tomohiro Oct. 17, 2017, 1:45 a.m. UTC | #2
On 2017/10/16 18:22, Nikolay Borisov wrote:
> 
> 
> On 16.10.2017 07:56, Misono, Tomohiro wrote:
>> This patch updates help/document of "btrfs device remove" in two points:
>>
>> 1. Add explanation of 'missing' for 'device remove'. This is only
>> written in wikipage currently.
>> (https://btrfs.wiki.kernel.org/index.php/Using_Btrfs_with_Multiple_Devices)
>>
>> 2. Add example of device removal in the man document. This is because
>> that explanation of "remove" says "See the example section below", but
>> there is no example of removal currently.
>>
>> Signed-off-by: Tomohiro Misono <misono.tomohiro@jp.fujitsu.com>
>> Reviewed-by: Satoru Takeuchi <satoru.takeuchi@gmail.com>
>> ---
>>  Documentation/btrfs-device.asciidoc | 19 ++++++++++++++++++-
>>  cmds-device.c                       |  8 ++++++++
>>  2 files changed, 26 insertions(+), 1 deletion(-)
>>
>> diff --git a/Documentation/btrfs-device.asciidoc b/Documentation/btrfs-device.asciidoc
>> index 88822ec..dd60415 100644
>> --- a/Documentation/btrfs-device.asciidoc
>> +++ b/Documentation/btrfs-device.asciidoc
>> @@ -68,13 +68,17 @@ 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.
>> ++
>> +If device is mounted as degraded mode (-o degraded), special term "missing"
> 	^ filesystem	^ in
>> +can be used for <device>. In that case, the first device that is described by> +the filesystem metadata, but not preseted at the mount time will be
> removed.
> 					^ present
> 
> Also, what happens if there are 2 or more devices missing, will those be
> deleted as well or just the first device? If all missing devices are
> handled then this needs to be reflected in the documentation.
> 

If there are 2 or more devices missing, only one device will be removed.
However, that case is rare. Previous discussion is in this thread: 
https://www.mail-archive.com/linux-btrfs@vger.kernel.org/msg68734.html

I copied these lines from wiki[1], but it seems this needs more explanations.
How about adding a note in the end?:
===
 If 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 RAID 6),
 you need specify "missing" as many times as the number of missing devices to 
 remove all of them.
===

Please let me know if there is more appropriate explanation.

Thanks,
Tomohiro

[1] https://btrfs.wiki.kernel.org/index.php/Using_Btrfs_with_Multiple_Devices

--
To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Duncan Oct. 17, 2017, 3:50 a.m. UTC | #3
Misono, Tomohiro posted on Tue, 17 Oct 2017 10:45:58 +0900 as excerpted:

> On 2017/10/16 18:22, Nikolay Borisov wrote:
>> 
>> 
>> On 16.10.2017 07:56, Misono, Tomohiro wrote:
>>>
>>> 1. Add explanation of 'missing' for 'device remove'. This is only
>>> written in wikipage currently.

>>> +++ b/Documentation/btrfs-device.asciidoc

>> Also, what happens if there are 2 or more devices missing, will those
>> be deleted as well or just the first device? If all missing devices are
>> handled then this needs to be reflected in the documentation.

> How about adding a note in the end?:
> ===
>  If 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 RAID 6), you need specify "missing" as many times as the
>  number of missing devices to remove all of them.
> ===

LGTM. =:^)

Patch
diff mbox

diff --git a/Documentation/btrfs-device.asciidoc b/Documentation/btrfs-device.asciidoc
index 88822ec..dd60415 100644
--- a/Documentation/btrfs-device.asciidoc
+++ b/Documentation/btrfs-device.asciidoc
@@ -68,13 +68,17 @@  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.
++
+If device is mounted as 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 preseted at the mount time will be removed.
 
 *delete* <device>|<devid> [<device>|<devid>...] <path>::
 Alias of remove kept for backward compatibility
@@ -206,6 +210,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
 ------------
 
diff --git a/cmds-device.c b/cmds-device.c
index 3b6b985..d28ed0f 100644
--- a/cmds-device.c
+++ b/cmds-device.c
@@ -224,9 +224,16 @@  static int _cmd_device_remove(int argc, char **argv,
 	return !!ret;
 }
 
+#define COMMON_USAGE_REMOVE_DELETE \
+	"", \
+	"If 'missing' is specified for <device>, the first device that is", \
+	"described by the filesystem metadata, but not presented at the", \
+	"mount time will be removed."
+
 static const char * const cmd_device_remove_usage[] = {
 	"btrfs device remove <device>|<devid> [<device>|<devid>...] <path>",
 	"Remove a device from a filesystem",
+	COMMON_USAGE_REMOVE_DELETE,
 	NULL
 };
 
@@ -238,6 +245,7 @@  static int cmd_device_remove(int argc, char **argv)
 static const char * const cmd_device_delete_usage[] = {
 	"btrfs device delete <device>|<devid> [<device>|<devid>...] <path>",
 	"Remove a device from a filesystem (alias of \"btrfs device remove\")",
+	COMMON_USAGE_REMOVE_DELETE,
 	NULL
 };