[PATCH v3 0/2] btrfs-progs: doc: update btrfs device remove

[PATCH v3 0/2] btrfs-progs: doc: update btrfs device remove

[Misono, Tomohiro]

This updates help/doc of "btrfs device remove".

First patch adds the explanation that delete is the alias of remove to help message.
Second patch adds the description of "remove missing", which is currently only
written in wikipage, and example of device removal.

v1->v2:
 split the patch and updates the messages
v2->v3
 withdrow "remove missing-all" feature
 
Tomohiro Misono (2):
	btrfs-progs: device: add description of alias to help message
	btrfs-progs: doc: add description of missing and example of device remove

 Documentation/btrfs-device.asciidoc | 20 +++++++++++++++++++-
 cmds-device.c                       | 9 +++++++++-
 2 files changed, 27 insertions(+), 2 deletions(-)

-- 
2.9.5

[PATCH v3 1/2] btrfs-progs: device: add description of alias to help message

[Misono, Tomohiro]

State the 'delete' is the alias of 'remove' as the man page says.

Signed-off-by: Tomohiro Misono <misono.tomohiro@jp.fujitsu.com>
Reviewed-by: Satoru Takeuchi <satoru.takeuchi@gmail.com>
---
 cmds-device.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/cmds-device.c b/cmds-device.c
index 4337eb2..3b6b985 100644
--- a/cmds-device.c
+++ b/cmds-device.c
@@ -237,7 +237,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",
+	"Remove a device from a filesystem (alias of \"btrfs device remove\")",
 	NULL
 };
 
-- 
2.9.5

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

[Misono, Tomohiro]

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"
+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
 };
 
-- 
2.9.5

Re: [PATCH v3 2/2] btrfs-progs: doc: add description of missing and example of device remove

[Nikolay Borisov]

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
>  };
>  
> 

Re: [PATCH v3 2/2] btrfs-progs: doc: add description of missing and example of device remove

[Misono, Tomohiro]

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

Re: [PATCH v3 2/2] btrfs-progs: doc: add description of missing and example of device remove

[Duncan]

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. =:^)

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman