570d1c3cae
Use the new docref and duplabel syntax to fix build warnings and fix the link targets in the pages. [ci skip] Signed-off-by: David Sterba <dsterba@suse.com>
119 lines
4.5 KiB
ReStructuredText
119 lines
4.5 KiB
ReStructuredText
BTRFS filesystem can be created on top of single or multiple block devices.
|
|
Devices can be then added, removed or replaced on demand. Data and metadata are
|
|
organized in allocation profiles with various redundancy policies. There's some
|
|
similarity with traditional RAID levels, but this could be confusing to users
|
|
familiar with the traditional meaning. Due to the similarity, the RAID
|
|
terminology is widely used in the documentation. See :doc:`mkfs.btrfs` for more
|
|
details and the exact profile capabilities and constraints.
|
|
|
|
The device management works on a mounted filesystem. Devices can be added,
|
|
removed or replaced, by commands provided by :command:`btrfs device` and :command:`btrfs replace`.
|
|
|
|
The profiles can be also changed, provided there's enough workspace to do the
|
|
conversion, using the :command:`btrfs balance` command and namely the filter *convert*.
|
|
|
|
Type
|
|
The block group profile type is the main distinction of the information stored
|
|
on the block device. User data are called *Data*, the internal data structures
|
|
managed by filesystem are *Metadata* and *System*.
|
|
|
|
Profile
|
|
A profile describes an allocation policy based on the redundancy/replication
|
|
constraints in connection with the number of devices. The profile applies to
|
|
data and metadata block groups separately. E.g. *single*, *RAID1*.
|
|
|
|
RAID level
|
|
Where applicable, the level refers to a profile that matches constraints of the
|
|
standard RAID levels. At the moment the supported ones are: RAID0, RAID1,
|
|
RAID10, RAID5 and RAID6.
|
|
|
|
.. duplabel:: man-device-typical-use-cases
|
|
|
|
Typical use cases
|
|
-----------------
|
|
|
|
Starting with a single-device filesystem
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Assume we've created a filesystem on a block device :file:`/dev/sda` with profile
|
|
*single/single* (data/metadata), the device size is 50GiB and we've used the
|
|
whole device for the filesystem. The mount point is :file:`/mnt`.
|
|
|
|
The amount of data stored is 16GiB, metadata have allocated 2GiB.
|
|
|
|
Add new device
|
|
""""""""""""""
|
|
|
|
We want to increase the total size of the filesystem and keep the profiles. The
|
|
size of the new device :file:`/dev/sdb` is 100GiB.
|
|
|
|
.. code-block:: bash
|
|
|
|
$ btrfs device add /dev/sdb /mnt
|
|
|
|
The amount of free data space increases by less than 100GiB, some space is
|
|
allocated for metadata.
|
|
|
|
Convert to RAID1
|
|
""""""""""""""""
|
|
|
|
Now we want to increase the redundancy level of both data and metadata, but
|
|
we'll do that in steps. Note, that the device sizes are not equal and we'll use
|
|
that to show the capabilities of split data/metadata and independent profiles.
|
|
|
|
The constraint for RAID1 gives us at most 50GiB of usable space and exactly 2
|
|
copies will be stored on the devices.
|
|
|
|
First we'll convert the metadata. As the metadata occupy less than 50GiB and
|
|
there's enough workspace for the conversion process, we can do:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ btrfs balance start -mconvert=raid1 /mnt
|
|
|
|
This operation can take a while, because all metadata have to be moved and all
|
|
block pointers updated. Depending on the physical locations of the old and new
|
|
blocks, the disk seeking is the key factor affecting performance.
|
|
|
|
You'll note that the system block group has been also converted to RAID1, this
|
|
normally happens as the system block group also holds metadata (the physical to
|
|
logical mappings).
|
|
|
|
What changed:
|
|
|
|
* available data space decreased by 3GiB, usable roughly (50 - 3) + (100 - 3) = 144 GiB
|
|
* metadata redundancy increased
|
|
|
|
IOW, the unequal device sizes allow for combined space for data yet improved
|
|
redundancy for metadata. If we decide to increase redundancy of data as well,
|
|
we're going to lose 50GiB of the second device for obvious reasons.
|
|
|
|
.. code-block:: bash
|
|
|
|
$ btrfs balance start -dconvert=raid1 /mnt
|
|
|
|
The balance process needs some workspace (i.e. a free device space without any
|
|
data or metadata block groups) so the command could fail if there's too much
|
|
data or the block groups occupy the whole first device.
|
|
|
|
The device size of :file:`/dev/sdb` as seen by the filesystem remains unchanged, but
|
|
the logical space from 50-100GiB will be unused.
|
|
|
|
Remove device
|
|
"""""""""""""
|
|
|
|
Device removal must satisfy the profile constraints, otherwise the command
|
|
fails. For example:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ btrfs device remove /dev/sda /mnt
|
|
ERROR: error removing device '/dev/sda': unable to go below two devices on raid1
|
|
|
|
In order to remove a device, you need to convert the profile in this case:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ btrfs balance start -mconvert=dup -dconvert=single /mnt
|
|
$ btrfs device remove /dev/sda /mnt
|