Diffstat (limited to 'Documentation/btrfs-balance.asciidoc')
1 files changed, 223 insertions, 0 deletions
diff --git a/Documentation/btrfs-balance.asciidoc b/Documentation/btrfs-balance.asciidoc
new file mode 100644
@@ -0,0 +1,223 @@
+btrfs-balance - balance block groups on a btrfs filesystem
+*btrfs balance* <subcommand> <args>
+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
+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.
+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*
+cancel running or paused balance
+pause running balance operation, this will store the state of the balance
+progress and used filters to the filesystem
+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.
+act on data block groups, see `FILTERS` section for details about 'filters'
+act on metadata chunks, see `FILTERS` section for details about 'filters'
+act on system chunks (requires '-f'), see `FILTERS` section for details about 'filters'.
+be verbose and print balance filter arguments
+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.
+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:
+Balances only block groups with the given profiles. Parameters
+are a list of profile names separated by "'|'" (pipe).
+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.
+Balances only block groups which have at least one chunk on the given
+device. To list devices with ids use *btrfs fi show*.
+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'.
+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 each selected block group to the given profile name identified by
+NOTE: starting with kernel 4.5, the 'data' chunks can be converted to/from the
+'DUP' profile on a single device.
+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.
+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
+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
+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),
+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*
+ 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.
+*btrfs balance* returns a zero exit status if it succeeds. Non zero is
+returned in case of failure.
+*btrfs* is part of btrfs-progs.
+Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for