| btrfs-balance(8) |
| ================ |
| |
| NAME |
| ---- |
| btrfs-balance - balance btrfs filesystem |
| |
| SYNOPSIS |
| -------- |
| *btrfs balance* <subcommand> <args> |
| |
| DESCRIPTION |
| ----------- |
| *btrfs balance* is used to balance chunks in a btrfs filesystem across |
| multiple or even single device. |
| |
| See `btrfs-device`(8) for more details about the effect on device management. |
| |
| NOTE: The balance subcommand also exists under the *filesystem* namespace. This |
| still works for backward compatibility but is deprecated and should not be |
| used anymore. |
| |
| 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* |
| command instead. |
| |
| SUBCOMMAND |
| ---------- |
| *cancel* <path>:: |
| Cancel running or paused balance. |
| |
| *pause* <path>:: |
| Pause running balance. |
| |
| *resume* <path>:: |
| Resume interrupted balance. |
| |
| *start* [options] <path>:: |
| Balance chunks across the devices *online*. |
| + |
| Balance and/or convert (change allocation profile of) chunks that |
| passed all filters in a comma-separated list of filters for a |
| particular chunk type. |
| If filter list is not given balance all chunks of that type. |
| In case none of the -d, -m or -s options is |
| given balance all chunks in a filesystem. |
| + |
| `Options` |
| + |
| -d[<filters>]:::: |
| act on data chunks. See `FILTERS` section for details about <filters>. |
| -m[<filters>]:::: |
| act on metadata chunks. See `FILTERS` section for details about <filters>. |
| -s[<filters>]:::: |
| act on system chunks (only under -f). See `FILTERS` section for details about <filters>. |
| -v:::: |
| be verbose |
| -f:::: |
| force reducing of metadata integrity |
| |
| *status* [-v] <path>:: |
| Show status of running or paused balance. |
| + |
| If '-v' option is given, output will be verbose. |
| |
| FILTERS |
| ------- |
| From kernel 3.3 onwards, btrfs balance can limit its action to a subset of the |
| full filesystem, and can be used to change the replication configuration (e.g. |
| moving data from single to RAID-1). This functionality is accessed through the |
| '-d', '-m' or '-s' options to btrfs balance start, which filter on data, |
| metadata and system blocks respectively. |
| |
| A filter has the following stucture: :: |
| 'type'[='params'][,'type'=...] |
| |
| The available types are: |
| |
| *profiles*:: |
| Balances only block groups with the given replication profiles. Parameters |
| are a list of profile names separated by |. |
| |
| *usage*:: |
| Balances only block groups with usage under the given percentage. The |
| value of 0 is allowed and will clean up completely unused block groups, this |
| should not require any new space allocated. You may want to use usage=0 in |
| case balance is returnin ENOSPC and your filesystem is not too full. |
| |
| *devid*:: |
| Balances only block groups which have at least one chunk on the given |
| device (by btrfs device ID -- use btrfs fi show to list device IDs) |
| |
| *drange*:: |
| Balances 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>. |
| |
| *vrange*:: |
| Balances 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>. |
| |
| *convert*:: |
| Convert each selected block group to the given profile name identified by |
| parameters. |
| |
| *limit*:: |
| Process only given number of chunks, after all filters apply. 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. |
| |
| *soft*:: |
| Takes no parameters. Only has meaning when converting between profiles. |
| When doing convert from one profile to another and soft mode is on, |
| restriper won't touch chunks that already have the target profile. This is |
| useful if e.g. half of the FS was converted earlier. |
| + |
| The soft mode switch is (like every other filter) per-type. This means |
| that we can convert for example meta chunks the "hard" way while converting |
| data chunks selectively with soft switch. |
| |
| Profile names, used in profiles and convert are one of: 'raid0', 'raid1', |
| 'raid10', 'raid5', 'raid6', 'dup', 'single'. |
| |
| EXIT STATUS |
| ----------- |
| *btrfs balance* returns a zero exit status if it succeeds. Non zero is |
| returned in case of failure. |
| |
| AVAILABILITY |
| ------------ |
| *btrfs* is part of btrfs-progs. |
| Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for |
| further details. |
| |
| SEE ALSO |
| -------- |
| `mkfs.btrfs`(8), |
| `btrfs-device`(8) |