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.
+is temporarily stored as an internal state 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.
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.
+should not be used any more.
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*
+but is deprecated and should not be used any more. Use *btrfs balance start*
command instead.
PERFORMANCE IMPLICATIONS
------------------------
-Balance operation is intense namely in the IO respect, but can be also CPU
-intense. It affects other actions on the filesystem. There are typically lots
-of data being copied from one location to another, and lots of metadata get
-updated.
+Balancing operations are very IO intensive and can also be quite CPU intensive,
+impacting other ongoing filesystem operations. Typically large amounts of data
+are copied from one location to another, with corresponding metadata updates.
-Depending on the actual block group layout, it can be also seek-heavy. The
-performance on rotational devices is noticeably worse than on SSDs or fast
-arrays.
+Depending upon the block group layout, it can also be seek heavy. Performance
+on rotational devices is noticeably worse compared to SSDs or fast arrays.
SUBCOMMAND
----------
*cancel* <path>::
-cancel running or paused balance, the command will block and wait until the
-actually processed blockgroup is finished
+cancels a running or paused balance, the command will block and wait until the
+current blockgroup being processed completes
*pause* <path>::
pause running balance operation, this will store the state of the balance
warning and delay can be skipped with '--full-balance' option.
+
Please note that the filters must be written together with the '-d', '-m' and
-'-s' options, because they're optional and bare '-d' etc alwo work and mean no
+'-s' options, because they're optional and bare '-d' etc also work and mean no
filters.
+
`Options`
*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*.
+device. To list devices with ids use *btrfs filesystem show*.
*drange=<range>*::
Balance only block groups which overlap with the given byte range on any
------
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.
+group and move the old data there, before the old block group can be removed.
+For that it needs the 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 space on the level of block groups, which are bigger parts of the filesystem
+that contain many file extents.
The free work space can be calculated from the output of the *btrfs filesystem show*
command:
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.
+groups that consume the work space.
EXAMPLES
--------
MAKING BLOCK GROUP LAYOUT MORE COMPACT
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The layout of block groups is not normally visible, most tools report only
+The layout of block groups is not normally visible; most tools report only
summarized numbers of free or used space, but there are still some hints
provided.
Let's use the following real life example and start with the output:
--------------------
-$ btrfs fi df /path
+$ btrfs filesystem df /path
Data, single: total=75.81GiB, used=64.44GiB
System, RAID1: total=32.00MiB, used=20.00KiB
Metadata, RAID1: total=15.87GiB, used=8.84GiB
# btrfs balance start -dusage=50 /path
Done, had to relocate 2 out of 97 chunks
-$ btrfs fi df /path
+$ btrfs filesystem df /path
Data, single: total=74.03GiB, used=64.43GiB
System, RAID1: total=32.00MiB, used=20.00KiB
Metadata, RAID1: total=15.87GiB, used=8.84GiB
# btrfs balance start -dusage=85 /path
Done, had to relocate 13 out of 95 chunks
-$ btrfs fi df /path
+$ btrfs filesystem df /path
Data, single: total=68.03GiB, used=64.43GiB
System, RAID1: total=32.00MiB, used=20.00KiB
Metadata, RAID1: total=15.87GiB, used=8.85GiB
structures, and can be reused for new data or metadata block groups.
We can do a similar exercise with the metadata block groups, but this should
-not be typically necessary, unless the used/total ration is really off. Here
+not typically be necessary, unless the used/total ratio is really off. Here
the ratio is roughly 50% but the difference as an absolute number is "a few
gigabytes", which can be considered normal for a workload with snapshots or
reflinks updated frequently.
# btrfs balance start -musage=50 /path
Done, had to relocate 4 out of 89 chunks
-$ btrfs fi df /path
+$ btrfs filesystem df /path
Data, single: total=68.03GiB, used=64.43GiB
System, RAID1: total=32.00MiB, used=20.00KiB
Metadata, RAID1: total=14.87GiB, used=8.85GiB
# btrfs balance start -musage=70 /path
Done, had to relocate 13 out of 88 chunks
-$ btrfs fi df .
+$ btrfs filesystem df .
Data, single: total=68.03GiB, used=64.43GiB
System, RAID1: total=32.00MiB, used=20.00KiB
Metadata, RAID1: total=11.97GiB, used=8.83GiB
# btrfs balance start -dusage=0 /path
--------------------
-This should lead to decrease in the 'total' numbers in the *btrfs fi df* output.
+This should lead to decrease in the 'total' numbers in the *btrfs filesystem df* output.
EXIT STATUS
-----------
projects / platform / upstream / btrfs-progs.git / blobdiff