1BTRFS-BALANCE-LEAST-USBEtDr(f1s)Balance Least Used BlockBGTrRoFuSp-sBALANCE-LEAST-USED(1)
2
3
4

NAME

6       btrfs-balance-least-used - Feed least used data block groups to btrfs
7       balance first.
8
9

SYNOPSIS

11       btrfs-balance-least-used [args] mountpoint
12
13

DESCRIPTION

15       The btrfs-balance-least-used program is an example of a user space
16       defined way to implement btrfs balance filters. It looks at the data
17       block groups present in the file system and asks btrfs to empty them in
18       order of actual usage, lowest usage first.
19
20       In most cases (when not being in the process of conversion between
21       block group profiles) this will result in the most optimal and quickest
22       way to reclaim physical disk space because data will be rewritten into
23       empty space into already existing block groups.
24
25       What btrfs balance effectively does is just taking the data and feeding
26       it back to the allocator of the filesystem as new writes, blacklisting
27       their current location. Implementing user space balance filters can
28       result in a higly optimized workflow to reclaim physical space, or to
29       minimize the amount of data that has to be rewritten to rebalance
30       complex filesystems with multiple devices.
31
32       Usage of btrfs-balance-least-used can replace repeated invocations of
33       btrfs balance with increased usage values. Additionally, the program
34       will show live progress of the balance operation.
35
36       Because the needed information is retrieved using the btrfs kernel API,
37       and because btrfs balance is a privileged operation, it has to be run
38       as root.
39
40       Example output:
41
42           -# balance_least_used.py -u 40 /
43           Loading block group objects with used_pct <= 40 ... found 20
44           Balance block group vaddr 603497431040 used_pct 19 ... duration 2
45       sec total 212
46           Balance block group vaddr 488607055872 used_pct 21 ... duration 2
47       sec total 211
48           Balance block group vaddr 576653885440 used_pct 21 ... duration 3
49       sec total 210
50           [...]
51           Postponing block group vaddr 659332005888 used_pct changed 24 -> 36
52           Balance block group vaddr 560547758080 used_pct 25 ... duration 3
53       sec total 206
54           [...]
55           Ignoring block group vaddr 606718656512 used_pct changed 34 -> 63
56           Balance block group vaddr 714126393344 used_pct 35 ... duration 3
57       sec total 196
58
59       This clearly shows that balance packs data into existing other block
60       groups, since the total amount of block groups is going down all the
61       time.
62
63       Also, along the way we see that usage of block groups we found when
64       starting has gone up, so if they're still in the usage range, we just
65       postpone them again, throwing them back into the work queue. If their
66       usage has gone up above the usage limit, ignore them.
67
68       When there's nothing to do, the output reports the lowest used_pct
69       found:
70
71           -# balance_least_used.py -u 10 /
72           Loading block group objects with used_pct <= 10 ... found 0
73           Nothing to do, least used block group has used_pct 12
74
75

OPTIONS

77       -h, --help
78              Show the built-in help message and exit.
79
80       -u, --usage USAGE
81              Only consider block groups with usage less than or equal to this
82              percentage.
83
84

SEE ALSO

86       This program is an example of what can be done using the python-btrfs
87       library.
88
89       Source and documentation on github: https://github.com/knorrie/python-
90       btrfs
91
92
93
94                                     2017          BTRFS-BALANCE-LEAST-USED(1)
Impressum