[PATCH] btrfs-progs: Documentation: Add filter section for btrfs-balance.

[PATCH] btrfs-progs: Documentation: Add filter section for btrfs-balance.

[Qu Wenruo]

Man page for 'btrfs-balance' mentioned <filters> but does not explain
them, which make end users hard to use '-d', '-m' or '-s options.

This patch will use the explanations from
https://btrfs.wiki.kernel.org/index.php/Balance_Filters to enrich the
man page.

Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com>
---
 Documentation/btrfs-balance.txt | 60 ++++++++++++++++++++++++++++++++++++++---
 1 file changed, 57 insertions(+), 3 deletions(-)

diff --git a/Documentation/btrfs-balance.txt b/Documentation/btrfs-balance.txt
index 37d8781..de93c92 100644
--- a/Documentation/btrfs-balance.txt
+++ b/Documentation/btrfs-balance.txt
@@ -37,11 +37,11 @@ given balance all chunks in a filesystem.
 `Options`
 +
 -d[<filters>]::::
-act on data chunks
+act on data chunks. See `FILTERS` section for details about <filters>.
 -m[<filters>]::::
-act on metadata chunks
+act on metadata chunks. See `FILTERS` section for details about <filters>.
 -s[<filters>]::::
-act on system chunks (only under -f)
+act on system chunks (only under -f). See `FILTERS` section for details about <filters>.
 -v::::
 be verbose
 -f::::
@@ -61,6 +61,60 @@ Show status of running or paused balance.
 +
 If '-v' option is given, output will be verbose.
 
+FILTERS
+-------
+From kernel 3.3 onwards, btrfs balance can limit its action to a subset of the
+full filesystem, and can be used to change the replication configuration (e.g.
+moving data from single to RAID-1). This functionality is accessed through the
+'-d', '-m' or '-s' options to btrfs balance start, which filter on data,
+metadata and system blocks respectively.
+
+A filter has the following stucture: ::
+'type'[='params'][,'type'=...]
+
+The available types are: ::
+*profiles*::::
+Balances only block groups with the given replication profiles. Parameters
+are a list of profile names separated by |.
+
+*usage*::::
+Balances only block groups with usage under the given percentage. The
+value of 0 is allowed and will clean up completely unused block groups, this
+should not require any new space allocated. You may want to use usage=0 in
+case balance is returnin ENOSPC and your filesystem is not too full.
+
+*devid*::::
+Balances only block groups which have at least one chunk on the given
+device (by btrfs device ID -- use btrfs fi show to list device IDs)
+
+*drange*::::
+Balances only block groups which overlap with the given byte range on any
+device. (Use in conjunction with "devid" to filter on a specific device). The
+parameter is a range specified as <start..end>.
+
+*vrange*::::
+Balances only block groups which overlap with the given byte range in the
+filesystem's internal virtual address space. This is the address space that
+most reports from btrfs in the kernel log use. The parameter is a range
+specified as <start..end>.
+
+*convert*::::
+Convert each selected block group to the given profile name identified by
+parameters.
+
+*soft*::::
+Takes no parameters. Only has meaning when converting between profiles.
+When doing convert from one profile to another and soft mode is on,
+restriper won't touch chunks that already have the target profile. This is
+useful if e.g. half of the FS was converted earlier.
++
+The soft mode switch is (like every other filter) per-type. This means
+that we can convert for example meta chunks the "hard" way while converting
+data chunks selectively with soft switch.
+
+Profile names, used in profiles and convert are one of: 'raid0', 'raid1',
+'raid10', 'raid5', 'raid6', 'dup', 'single'.
+
 EXIT STATUS
 -----------
 *btrfs balance* returns a zero exist status if it succeeds. Non zero is
-- 
1.9.3

Re: [PATCH] btrfs-progs: Documentation: Add filter section for btrfs-balance.

[Duncan]

Qu Wenruo posted on Tue, 03 Jun 2014 14:20:08 +0800 as excerpted:

> Man page for 'btrfs-balance' mentioned <filters> but does not explain
> them, which make end users hard to use '-d', '-m' or '-s options.
> 
> This patch will use the explanations from
> https://btrfs.wiki.kernel.org/index.php/Balance_Filters to enrich the
> man page.
> 
> Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com>

Thanks.  The wiki-only nature of the balance-filters documentation has 
been a bit of a complication.  This should fix that. =:^)

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