summaryrefslogtreecommitdiff
path: root/Documentation/btrfs-balance.asciidoc
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/btrfs-balance.asciidoc')
-rw-r--r--Documentation/btrfs-balance.asciidoc223
1 files changed, 223 insertions, 0 deletions
diff --git a/Documentation/btrfs-balance.asciidoc b/Documentation/btrfs-balance.asciidoc
new file mode 100644
index 00000000..7df40b9c
--- /dev/null
+++ b/Documentation/btrfs-balance.asciidoc
@@ -0,0 +1,223 @@
+btrfs-balance(8)
+================
+
+NAME
+----
+btrfs-balance - balance block groups on a btrfs filesystem
+
+SYNOPSIS
+--------
+*btrfs balance* <subcommand> <args>
+
+DESCRIPTION
+-----------
+The primary purpose of the balance feature is to spread block groups across
+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.
+
+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 *btrfs filesystem*
+namespace. This still works for backward compatibility but is deprecated and
+should not be used anymore.
+
+NOTE: A short syntax *btrfs balance <path>* works due to backward compatibility
+but is deprecated and should not be used anymore. Use *btrfs balance start*
+command instead.
+
+SUBCOMMAND
+----------
+*cancel* <path>::
+cancel running or paused balance
+
+*pause* <path>::
+pause running balance operation, this will store the state of the balance
+progress and used filters to the filesystem
+
+*resume* <path>::
+resume interrupted balance
+
+*start* [options] <path>::
+start the balance operation according to the specified filters, no filters
+will rewrite the entire filesystem. The process runs in the foreground.
++
+NOTE: the balance command without filters will basically rewrite everything
+in the filesystem. The run time is potentially very long, depending on the
+filesystem size. To prevent starting a full balance by accident, the user is
+warned and has a few seconds to cancel the operation before it starts. The
+warning and delay can be skipped with '--full-balance' option.
++
+`Options`
++
+-d[<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'
+-s[<filters>]::::
+act on system chunks (requires '-f'), see `FILTERS` section for details about 'filters'.
+-v::::
+be verbose and print balance filter arguments
+-f::::
+force reducing of metadata integrity, eg. when going from 'raid1' to 'single'
+
+*status* [-v] <path>::
+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 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 structure: 'type'[='params'][,'type'=...]
+
+The available types are:
+
+*profiles=<profiles>*::
+Balances only block groups with the given profiles. Parameters
+are a list of profile names separated by "'|'" (pipe).
+
+*usage=<percent>*::
+*usage=<range>*::
+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 work space allocated. You may want to use 'usage=0'
+in case balance is returning ENOSPC and your filesystem is not too full.
++
+The argument may be a single value or a range. The single value 'N' means 'at
+most N percent used', equivalent to '..N' range syntax. Kernels prior to 4.4
+accept only the single value format.
+The minimum range boundary is inclusive, maximum is exclusive.
+
+*devid=<id>*::
+Balances only block groups which have at least one chunk on the given
+device. To list devices with ids use *btrfs fi show*.
+
+*drange=<range>*::
+Balance 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=<range>*::
+Balance 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=<profile>*::
+Convert each selected block group to the given profile name identified by
+parameters.
++
+NOTE: starting with kernel 4.5, the 'data' chunks can be converted to/from the
+'DUP' profile on a single device.
+
+*limit=<number>*::
+*limit=<range>*::
+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.
++
+The argument may be a single value or a range. The single value 'N' means 'at
+most N chunks', equivalent to '..N' range syntax. Kernels prior to 4.4 accept
+only the single value format. The range minimum and maximum are inclusive.
+
+*stripes=<range>*::
+Balance only block groups which have the given number of stripes. The parameter
+is a range specified as 'start..end'. Makes sense for block group profiles that
+utilize striping, ie. RAID0/10/5/6. The range minimum and maximum are
+inclusive.
+
+*soft*::
+Takes no parameters. Only has meaning when converting between profiles.
+When doing convert from one profile to another and soft mode is on,
+chunks that already have the target profile are left untouched.
+This is useful e.g. when half of the filesystem was converted earlier but got
+cancelled.
++
+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'. The mixed data/metadata profiles
+can be converted in the same way, but it's conversion between mixed and non-mixed
+is not implemented. For the constraints of the profiles please refer to `mkfs.btrfs`(8),
+section 'PROFILES'.
+
+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. After 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
+-----------
+*btrfs balance* returns a zero exit status if it succeeds. Non zero is
+returned in case of failure.
+
+AVAILABILITY
+------------
+*btrfs* is part of btrfs-progs.
+Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
+further details.
+
+SEE ALSO
+--------
+`mkfs.btrfs`(8),
+`btrfs-device`(8)