Docs: Add balance examples.

[Torstein-Eide]

Hi Dave
I have made a page with examples for balance of BTRFS, so it easier to understand how to use it.

[Zygo]

Could use soft here too. With soft, if the balance is interrupted, it can be restarted with the same command line.

There is an example down below with soft but I'm not sure why there's a separate example just for soft.

Converting without soft is useful for custom userspace balance tools, but for simple profile conversions a user almost never wants to run convert without it.

[Torstein-Eide]

It sound to me that soft should be the default for most user.

Do you have a example when not soft should be used?

[Zygo]

When you are doing something that requires moving the chunk and also specifying the target profile. e.g. if you need to make an unallocated hole so that you can add a new disk to a raid1c3, you might temporarily downgrade a few chunks to raid1:

# Make space on each existing device by lowering the redundancy.
# If the data is already in raid1 profile then we still want it moved.
btrfs balance start -ddevid=1,limit=10,convert=raid1 $MOUNT_PT
btrfs balance start -ddevid=2,limit=10,convert=raid1 $MOUNT_PT
btrfs balance start -ddevid=3,limit=10,convert=raid1 $MOUNT_PT
# Add device, 4 disks now
btrfs dev add $NEW_DEV $MOUNT_PT
# Rebalance entire filesystem across 4 disks instead of 3
btrfs balance start -dconvert=raid1c3 $MOUNT_PT

Here almost all of the data is already in raid1c3 profile, but in this case we want to redistribute all of the data across 4 drives, so we don't want soft here. We want the 30 chunks that happen to be raid1 to become raid1c3 as we go.

We could do something like this:

# Convert 30 raid1 chunks back to raid1c3
btrfs balance start -dconvert=raid1c3,soft $MOUNT_PT
# Redistribute everything across 4 devices
btrfs balance start -d $MOUNT_PT

but this will process the 30 temporary raid1 block groups twice (once to convert them back to raid1c3, and again to redistribute the filesystem across the 4 devices).

[Zygo]

The command only targets metadata chunks. Data chunks will not be balanced if only -m is specified.

Generally if a user is in this sort of situation, they will want to run both conversions to ensure their chosen profiles are selected and no others. This can be done in a single command:

btrfs balance start -mconvert=raid1,soft -dconvert=raid1,soft $BTRFS_MOUNT

or multiple commands if it's necessary to force the order (e.g. due to space constraints):

btrfs balance start -dconvert=raid1,soft $BTRFS_MOUNT
btrfs balance start -mconvert=raid1,soft $BTRFS_MOUNT

[Torstein-Eide]

Correct, and system.

Is the point about due to space constraints, valid for the example?
Or more fit to be in the ch-balance-filters.rst.

Before changing profiles, 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)).

[Zygo]

The space constraints always have to be observed. A filesystem with unequal disk sizes and raid1 profile can fill up with ordinary data writes if there isn't enough unallocated space.

The thing that makes balance different is that a new profile can be introduced, which changes the requirements for future allocations abruptly.

[Torstein-Eide]

I have squashed the commits, and add changes to ch-balance-filters.rst, to reflect the input from @Zygo .

[kdave]

Thanks for the PR and comments, merged to devel. I've updated formatting and wording.