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
------
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.
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.