mirror of
https://github.com/kdave/btrfs-progs
synced 2025-03-25 04:16:32 +00:00
btrfs-progs: docs: enhance manual page for balance
Signed-off-by: David Sterba <dsterba@suse.com>
This commit is contained in:
David Sterba
parent
b44e84a650
commit
bfb2659d12
@ -3,7 +3,7 @@ btrfs-balance(8)
|
||||
|
||||
NAME
|
||||
----
|
||||
btrfs-balance - balance btrfs filesystem
|
||||
btrfs-balance - balance block groups on a btrfs filesystem
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
@ -11,10 +11,37 @@ SYNOPSIS
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
*btrfs balance* is used to balance chunks in a btrfs filesystem across
|
||||
multiple or even single device.
|
||||
The primary purpose of the balance feature is to spread block groups accross
|
||||
all devices so they match constraints defined by the respective profiles. See
|
||||
`mkfs.btrfs`(8) section 'PROFILES' for more details.
|
||||
The scope of the balancing process can be further tuned by use of filters that
|
||||
can select the block groups to process. Balance works only on a mounted
|
||||
filesystem.
|
||||
|
||||
See `btrfs-device`(8) for more details about the effect on device management.
|
||||
The balance operation is cancellable by the user. The on-disk state of the
|
||||
filesystem is always consistent so an unexpected interruption (eg. system crash,
|
||||
reboot) does not corrupt the filesystem. The progress of the balance operation
|
||||
is temporarily stored and will be resumed upon mount, unless the mount option
|
||||
'skip_balance' is specified.
|
||||
|
||||
WARNING: running balance without filters will take a lot of time as it basically
|
||||
rewrites the entire filesystem and needs to update all block pointers.
|
||||
|
||||
The filters can be used to perform following actions:
|
||||
|
||||
- convert block group profiles (filter 'convert')
|
||||
- make block group usage more compact (filter 'usage')
|
||||
- perform actions only on a given device (filters 'devid', 'drange')
|
||||
|
||||
The filters can be applied to a combination of block group types (data,
|
||||
metadata, system). Note that changing 'system' needs the force option.
|
||||
|
||||
NOTE: the balance operation needs enough work space, ie. space that is
|
||||
completely unused in the filesystem, otherwise this may lead to ENOSPC reports.
|
||||
See the section 'ENOSPC' for more details.
|
||||
|
||||
COMPATIBILITY
|
||||
-------------
|
||||
|
||||
NOTE: The balance subcommand also exists under the *filesystem* namespace. This
|
||||
still works for backward compatibility but is deprecated and should not be
|
||||
@ -27,36 +54,31 @@ command instead.
|
||||
SUBCOMMAND
|
||||
----------
|
||||
*cancel* <path>::
|
||||
Cancel running or paused balance.
|
||||
cancel running or paused balance
|
||||
|
||||
*pause* <path>::
|
||||
Pause running balance.
|
||||
pause running balance operation, this will store the state of the balance
|
||||
progress and used filters to the filesystem
|
||||
|
||||
*resume* <path>::
|
||||
Resume interrupted balance.
|
||||
resume interrupted balance
|
||||
|
||||
*start* [options] <path>::
|
||||
Balance chunks across the devices *online*.
|
||||
+
|
||||
Balance and/or convert (change allocation profile of) chunks that
|
||||
passed all filters in a comma-separated list of filters for a
|
||||
particular chunk type.
|
||||
If filter list is not given balance all chunks of that type.
|
||||
In case none of the -d, -m or -s options is
|
||||
given balance all chunks in a filesystem.
|
||||
start the balance operation according to the specified filters, no filters
|
||||
will rewrite the entire filesystem. The process runs in the foreground.
|
||||
+
|
||||
`Options`
|
||||
+
|
||||
-d[<filters>]::::
|
||||
act on data chunks. See `FILTERS` section for details about <filters>.
|
||||
act on data block groups, see `FILTERS` section for details about 'filters'
|
||||
-m[<filters>]::::
|
||||
act on metadata chunks. See `FILTERS` section for details about <filters>.
|
||||
act on metadata chunks, see `FILTERS` section for details about 'filters'
|
||||
-s[<filters>]::::
|
||||
act on system chunks (only under -f). See `FILTERS` section for details about <filters>.
|
||||
act on system chunks (requires '-f'), see `FILTERS` section for details about 'filters'.
|
||||
-v::::
|
||||
be verbose
|
||||
be verbose and print balance filter arguments
|
||||
-f::::
|
||||
force reducing of metadata integrity
|
||||
force reducing of metadata integrity, eg. when going from 'raid1' to 'single'
|
||||
|
||||
*status* [-v] <path>::
|
||||
Show status of running or paused balance.
|
||||
@ -67,61 +89,92 @@ 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
|
||||
moving data from single to RAID1). 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'=...]
|
||||
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 |.
|
||||
*profiles=<profiles>*::
|
||||
Balances only block groups with the given profiles. Parameters
|
||||
are a list of profile names separated by "'|'" (pipe).
|
||||
|
||||
*usage*::
|
||||
*usage=<percent>*::
|
||||
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
|
||||
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*::
|
||||
*devid=<id>*::
|
||||
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)
|
||||
device. To list devices with ids use 'btrfs fi show'.
|
||||
|
||||
*drange*::
|
||||
*drange=<range>*::
|
||||
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>.
|
||||
device.(Use in conjunction with 'devid' to filter on a specific device. The
|
||||
parameter is a range specified as 'start..end'.
|
||||
|
||||
*vrange*::
|
||||
*vrange=<range>*::
|
||||
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>.
|
||||
specified as 'start..end'.
|
||||
|
||||
*convert*::
|
||||
*convert=<profile>*::
|
||||
Convert each selected block group to the given profile name identified by
|
||||
parameters.
|
||||
|
||||
*limit*::
|
||||
Process only given number of chunks, after all filters apply. This can be used
|
||||
to specifically target a chunk in connection with other filters (drange,
|
||||
*limit=<number>*::
|
||||
Process only given number of chunks, after all filters are applied. This can be
|
||||
used to specifically target a chunk in connection with other filters (drange,
|
||||
vrange) or just simply limit the amount of work done by a single balance run.
|
||||
|
||||
*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.
|
||||
chunks that alread yave the target profile are left untouched
|
||||
This is useful if e.g. half of the filesystem 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.
|
||||
The soft mode switch is (like every other filter) per-type.
|
||||
For example, this means that we can convert metadata 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'.
|
||||
'raid10', 'raid5', 'raid6', 'dup', 'single'. The mixed data/metadata profiles
|
||||
can be converted in the same bay, but it's conversion between mixed and non-mixed
|
||||
is not implemented.
|
||||
|
||||
ENOSPC
|
||||
------
|
||||
|
||||
The way balance operates, it usually needs to temporarily create a new block
|
||||
group and move the old data there. For that it needs work space, otherwise
|
||||
it fails for ENOSPC reasons.
|
||||
This is not the same ENOSPC as if the free space is exhausted. This refers to
|
||||
the space on the level of block groups.
|
||||
|
||||
The free work space can be calculated from the output of the 'btrfs filesystem show'
|
||||
command:
|
||||
|
||||
Label: 'BTRFS' uuid: 8a9d72cd-ead3-469d-b371-9c7203276265
|
||||
Total devices 2 FS bytes used 77.03GiB
|
||||
devid 1 size 53.90GiB used 51.90GiB path /dev/sdc2
|
||||
devid 2 size 53.90GiB used 51.90GiB path /dev/sde1
|
||||
|
||||
'size' - 'used' = 'free work space' +
|
||||
'53.90GiB' - '51.90GiB' = '2.00GiB'
|
||||
|
||||
An example of a filter that does not require workspace is 'usage=0'. This will
|
||||
scan through all unused block groups of a given type and will reclaim the
|
||||
space. Ater that it might be possible to run other filters.
|
||||
|
||||
**CONVERSIONS ON MULTIPLE DEVICES**
|
||||
|
||||
Conversion to profiles based on striping (RAID0, RAID5/6) require the work
|
||||
space on each device. An interrupted balance may leave partially filled block
|
||||
groups that might consume the work space.
|
||||
|
||||
EXIT STATUS
|
||||
-----------
|
||||
|
||||
Loading…
Reference in New Issue
Block a user