btrfs-progs: docs: add balance filter examples
Add more examples and explanations how the filters can be used. Pull-request: #486 Author: Eideen Signed-off-by: David Sterba <dsterba@suse.com>
This commit is contained in:
Eideen
David Sterba
parent
9362803539
commit
1e18750288
|
|
@ -7,3 +7,8 @@ Filters
|
|||
-------
|
||||
|
||||
.. include:: ch-balance-filters.rst
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
.. include:: ch-balance-examples.rst
|
||||
|
|
|
|||
104
Documentation/ch-balance-examples.rst
Normal file
104
Documentation/ch-balance-examples.rst
Normal file
|
|
@ -0,0 +1,104 @@
|
|||
Adding new device
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
The unallocated space requirements depend on the selected storage
|
||||
profiles. The requirements for the storage profile must be met for the
|
||||
selected for both data and metadata (e.g. if you have single data and
|
||||
RAID1 metadata, the stricter RAID1 requirements must be met or the
|
||||
filesystem may run out of metadata space and go read-only).
|
||||
|
||||
Before adding a drive, make sure there is enough unallocated space on
|
||||
existing drives to create new metadata block groups (for filesystems
|
||||
over 50GB, this is `1GB * (number_of_devices + 2))`.
|
||||
|
||||
If using a striped profile (`raid0`, `raid10`, `raid5`, or `raid6`), then do a
|
||||
full data balance of all data after adding a drive. If adding multiple
|
||||
drives at once, do a full data balance after adding the last one.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
btrfs balance start -v --full-balance mnt/
|
||||
|
||||
If the balance is interrupted, it can be restarted using the *stripes*
|
||||
filter (i.e. `-dstripes=1..N` where *N* is the previous size of the array
|
||||
before the new device was added) as long as all devices are the same size.
|
||||
If the device sizes are different, a specialized userspace balance tool
|
||||
is required. The data balance must be completed before adding any new
|
||||
devices or increasing the size of existing ones.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# For going from 4 disk to 5 disks, in Raid 5
|
||||
btrfs balance start -v -dstripes=1..4 mnt/
|
||||
|
||||
If you are not using a striped profile now, but intend to convert to a
|
||||
striped profile in the future, always perform a full data balance after
|
||||
adding drives or replacing existing drives with larger ones. The stock
|
||||
*btrfs balance* tool cannot cope with special cases on filesystems with
|
||||
striped raid profiles, and will paint itself into a corner that will
|
||||
require custom userspace balancing tools to recover if you try.
|
||||
|
||||
To watch one can use the following:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
watch "btrfs filesystem usage -T mnt/; btrfs balance status mnt/"
|
||||
|
||||
Convert RAID1 after mkfs with defaults
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If you forgot to set the block group profile when creating the volume, run the
|
||||
following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
btrfs balance start -v convert=raid1,soft mnt/
|
||||
|
||||
This will convert all remaining profiles that are not yet *raid1*.
|
||||
|
||||
Convert data to RAID10 with RAID1C4 for metadata
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If you a have multi device setup, or you'd like to have different profiles on a
|
||||
single disk, e.g. *RAID10* for data and *RAID1C4* for metadata and system:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
btrfs balance start -v -mconvert=raid1C4,soft -dconvert=raid10,soft mnt/
|
||||
|
||||
Compact under used chunks
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If the data chunks are not balanced and used only partially, the *usage* filter
|
||||
can be used to make them more compact:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
btrfs balance start -v -dusage=10 mnt/
|
||||
|
||||
If the percent starts from a small number, like 5 or 10, the chunks will be
|
||||
processed relatively quickly and will make more space available. Increasing the
|
||||
percentage can then make more chunks compact by relocating the data.
|
||||
|
||||
Chunks utilized up to 50% can be relocated to other chunks while still freeing
|
||||
the space. With utilization higher than 50% the chunks will be basically only
|
||||
moved on the devices. The actual chunk layout may help to coalesce the free
|
||||
space but this is a secondary effect.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
for USAGE in {10..50..10} do
|
||||
btrfs balance start -v -dusage=$USAGE mnt/
|
||||
done
|
||||
|
||||
Fix incomplete balance
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If the balance is interrupted (due to reboot or cancelled) during conversion to
|
||||
RAID1. The following command will skip all RAID1 chunks that have been already
|
||||
converted and continue with what's left to convert. Note that an interrupted
|
||||
conversion may leave the last chunk under utilized.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
btrfs balance start convert=raid1,soft mnt/
|
||||
|
|
@ -1,16 +1,49 @@
|
|||
From kernel 3.3 onwards, btrfs balance can limit its action to a subset of the
|
||||
From kernel 3.3 onwards, BTRFS balance can limit its action to a subset of the
|
||||
whole 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.
|
||||
convert data from ``single`` to ``RAID1``).
|
||||
|
||||
A filter has the following structure: *type[=params][,type=...]*
|
||||
Balance can be limited to a block group profile with the following options:
|
||||
|
||||
The available types are:
|
||||
* ``-d`` for data block groups
|
||||
* ``-m`` for metadata block groups (also implicitly applies to *-s*)
|
||||
* ``-s`` for system block groups
|
||||
|
||||
The options have an optional parameter which means that the parameter must start
|
||||
right after the option without a space (this is mandatory getopt syntax), like
|
||||
``-dusage=10``. Options for all block group types can be specified in one command.
|
||||
|
||||
A filter has the following structure: ``filter[=params][,filter=...]``
|
||||
|
||||
To combine multiple filters use ``,``, without spaces. Example: ``-dconvert=raid1,soft``
|
||||
|
||||
BTRFS can have different profiles on a single device or the same profile on
|
||||
multiple device.
|
||||
|
||||
The main reason why you want to have different profiles for data and metadata
|
||||
is to provide additional protection of the filesystem's metadata when devices fail,
|
||||
since a single sector of unrecoverable metadata will break the filesystem,
|
||||
while a single sector of lost data can be trivially recovered by deleting the broken file.
|
||||
|
||||
Before changing profiles, make sure there is enough unallocated space on
|
||||
existing drives to create new metadata block groups (for filesystems
|
||||
over 50GiB, this is ``1GB * (number_of_devices + 2))``.
|
||||
|
||||
Default profiles on BTRFS are:
|
||||
|
||||
* data: ``single``
|
||||
* metadata:
|
||||
* single devices: ``dup``
|
||||
* multiple devices: ``raid1``
|
||||
|
||||
|
||||
The available filter types are:
|
||||
|
||||
Filter types
|
||||
^^^^^^^^^^^^
|
||||
|
||||
profiles=<profiles>
|
||||
Balances only block groups with the given profiles. Parameters
|
||||
are a list of profile names separated by "*|*" (pipe).
|
||||
are a list of profile names separated by ``|`` (pipe).
|
||||
|
||||
usage=<percent>, usage=<range>
|
||||
Balances only block groups with usage under the given percentage. The
|
||||
|
|
@ -18,8 +51,8 @@ usage=<percent>, usage=<range>
|
|||
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
|
||||
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.
|
||||
|
||||
|
|
@ -29,44 +62,44 @@ devid=<id>
|
|||
|
||||
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*.
|
||||
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*.
|
||||
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.
|
||||
Starting with kernel 4.5, the ``data`` chunks can be converted to/from the
|
||||
``DUP`` profile on a single device.
|
||||
|
||||
.. note::
|
||||
Starting with kernel 4.6, all profiles can be converted to/from *DUP* on
|
||||
Starting with kernel 4.6, all profiles can be converted to/from ``DUP`` on
|
||||
multi-device filesystems.
|
||||
|
||||
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.
|
||||
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
|
||||
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
|
||||
is a range specified as ``start..end``. Makes sense for block group profiles that
|
||||
utilize striping, i.e. RAID0/10/5/6. The range minimum and maximum are
|
||||
inclusive.
|
||||
|
||||
soft
|
||||
Takes no parameters. Only has meaning when converting between profiles.
|
||||
Takes no parameters. Only has meaning when converting between profiles, or
|
||||
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
|
||||
|
|
@ -76,9 +109,19 @@ soft
|
|||
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*,
|
||||
*raid1c3*, *raid1c4*, *raid10*, *raid5*, *raid6*, *dup*, *single*. The mixed
|
||||
data/metadata profiles can be converted in the same way, but it's conversion
|
||||
Profile names, used in ``profiles`` and ``convert`` are one of:
|
||||
|
||||
* ``raid0``
|
||||
* ``raid1``
|
||||
* ``raid1c3``
|
||||
* ``raid1c4``
|
||||
* ``raid10``
|
||||
* ``raid5``
|
||||
* ``raid6``
|
||||
* ``dup``
|
||||
* ``single``
|
||||
|
||||
The mixed data/metadata profiles can be converted in the same way, but conversion
|
||||
between mixed and non-mixed is not implemented. For the constraints of the
|
||||
profiles please refer to :doc:`mkfs.btrfs(8)<mkfs.btrfs>` section
|
||||
:ref:`PROFILES<man-mkfs-profiles>`.
|
||||
|
|
|
|||
Loading…
Reference in a new issue