Debian Codegraph @

upstream/mageia-cauldron/man8/btrfs-balance.8

raw
1 .\" Man page generated from reStructuredText.
2 .
3 .
4 .nr rst2man-indent-level 0
5 .
6 .de1 rstReportMargin
7 \\$1 \\n[an-margin]
8 level \\n[rst2man-indent-level]
9 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
10 -
11 \\n[rst2man-indent0]
12 \\n[rst2man-indent1]
13 \\n[rst2man-indent2]
14 ..
15 .de1 INDENT
16 .\" .rstReportMargin pre:
17 . RS \\$1
18 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
19 . nr rst2man-indent-level +1
20 .\" .rstReportMargin post:
21 ..
22 .de UNINDENT
23 . RE
24 .\" indent \\n[an-margin]
25 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
26 .nr rst2man-indent-level -1
27 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
28 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
29 ..
30 .TH "BTRFS-BALANCE" "8" "Mar 10, 2026" "6.19" "BTRFS"
31 .SH NAME
32 btrfs-balance \- balance block groups on a btrfs filesystem
33 .SH SYNOPSIS
34 .sp
35 \fBbtrfs balance\fP <subcommand> <args>
36 .SH DESCRIPTION
37 .sp
38 The primary purpose of the balance feature is to spread block groups across
39 all devices so they match constraints defined by the respective profiles. See
40 \fI\%mkfs.btrfs(8)\fP section \fI\%PROFILES\fP
41 for more details.
42 The scope of the balancing process can be further tuned by use of filters that
43 can select the block groups to process. Balance works only on a mounted
44 filesystem. Extent sharing is preserved and reflinks are not broken.
45 Files are not defragmented nor recompressed, file extents are preserved
46 but the physical location on devices will change.
47 .sp
48 The balance operation is cancellable by the user. The on\-disk state of the
49 filesystem is always consistent so an unexpected interruption (e.g. system crash,
50 reboot) does not corrupt the filesystem. The progress of the balance operation
51 is temporarily stored as an internal state and will be resumed upon mount,
52 unless the mount option \fIskip_balance\fP is specified.
53 .sp
54 \fBWARNING:\fP
55 .INDENT 0.0
56 .INDENT 3.5
57 Running balance without filters will take a lot of time as it basically move
58 data/metadata from the whole filesystem and needs to update all block
59 pointers.
60 .UNINDENT
61 .UNINDENT
62 .sp
63 The filters can be used to perform following actions:
64 .INDENT 0.0
65 .IP \(bu 2
66 convert block group profiles (filter \fIconvert\fP)
67 .IP \(bu 2
68 make block group usage more compact (filter \fIusage\fP)
69 .IP \(bu 2
70 perform actions only on a given device (filters \fIdevid\fP, \fIdrange\fP)
71 .UNINDENT
72 .sp
73 The filters can be applied to a combination of block group types (data,
74 metadata, system). Note that changing only the \fIsystem\fP type needs the force
75 option. Otherwise \fIsystem\fP gets automatically converted whenever \fImetadata\fP
76 profile is converted.
77 .sp
78 When metadata redundancy is reduced (e.g. from RAID1 to single) the force option
79 is also required and it is noted in system log.
80 .sp
81 \fBNOTE:\fP
82 .INDENT 0.0
83 .INDENT 3.5
84 The balance operation needs enough work space, i.e. space that is completely
85 unused in the filesystem, otherwise this may lead to ENOSPC reports. See
86 the section \fIENOSPC\fP for more details.
87 .UNINDENT
88 .UNINDENT
89 .SH COMPATIBILITY
90 .sp
91 \fBNOTE:\fP
92 .INDENT 0.0
93 .INDENT 3.5
94 The balance subcommand also exists under the \fBbtrfs filesystem\fP namespace.
95 This still works for backward compatibility but is deprecated and should not
96 be used any more.
97 .UNINDENT
98 .UNINDENT
99 .sp
100 \fBNOTE:\fP
101 .INDENT 0.0
102 .INDENT 3.5
103 A short syntax \fBbtrfs balance <path>\fP works due to backward compatibility
104 but is deprecated and should not be used any more. Use \fBbtrfs balance start\fP
105 command instead.
106 .UNINDENT
107 .UNINDENT
108 .SH PERFORMANCE IMPLICATIONS
109 .sp
110 Balancing operations are very IO intensive and can also be quite CPU intensive,
111 impacting other ongoing filesystem operations. Typically large amounts of data
112 are copied from one location to another, with corresponding metadata updates.
113 .sp
114 Depending upon the block group layout, it can also be seek heavy. Performance
115 on rotational devices is noticeably worse compared to SSDs or fast arrays.
116 .SH SUBCOMMAND
117 .INDENT 0.0
118 .TP
119 .B cancel <path>
120 cancels a running or paused balance, the command will block and wait until the
121 current block group being processed completes
122 .sp
123 Since kernel 5.7 the response time of the cancellation is significantly
124 improved, on older kernels it might take a long time until currently
125 processed chunk is completely finished.
126 .TP
127 .B pause <path>
128 pause running balance operation, this will store the state of the balance
129 progress and used filters to the filesystem
130 .TP
131 .B resume <path>
132 resume interrupted balance, the balance status must be stored on the filesystem
133 from previous run, e.g. after it was paused or forcibly interrupted and mounted
134 again with \fIskip_balance\fP
135 .TP
136 .B start [options] <path>
137 start the balance operation according to the specified filters, without any filters
138 the data and metadata from the whole filesystem are moved. The process runs in
139 the foreground.
140 .sp
141 \fBNOTE:\fP
142 .INDENT 7.0
143 .INDENT 3.5
144 The balance command without filters will basically move everything in the
145 filesystem to a new physical location on devices (i.e. it does not affect the
146 logical properties of file extents like offsets within files and extent
147 sharing). The run time is potentially very long, depending on the filesystem
148 size. To prevent starting a full balance by accident, the user is warned and
149 has a few seconds to cancel the operation before it starts. The warning and
150 delay can be skipped with \fI\-\-full\-balance\fP option.
151 .UNINDENT
152 .UNINDENT
153 .sp
154 Please note that the filters must be written together with the \fI\-d\fP, \fI\-m\fP and
155 \fI\-s\fP options, because they\(aqre optional and bare \fI\-d\fP and \fI\-m\fP also work and
156 mean no filters.
157 .sp
158 \fBNOTE:\fP
159 .INDENT 7.0
160 .INDENT 3.5
161 When the target profile for conversion filter is \fIraid5\fP or \fIraid6\fP,
162 there\(aqs a safety timeout of 10 seconds to warn users about the status of the feature
163 .UNINDENT
164 .UNINDENT
165 .sp
166 \fBOptions\fP
167 .INDENT 7.0
168 .TP
169 .B \-d[<filters>]
170 act on data block groups, see section \fI\%FILTERS\fP for details about \fIfilters\fP
171 .TP
172 .B \-m[<filters>]
173 act on metadata chunks, see \fI\%FILTERS\fP for details about \fIfilters\fP
174 .TP
175 .B \-s[<filters>]
176 act on system chunks (requires \fI\-f\fP), see \fI\%FILTERS\fP for details about \fIfilters\fP\&.
177 .UNINDENT
178 .INDENT 7.0
179 .TP
180 .B \-f
181 force a reduction of metadata integrity, e.g. when going from \fIraid1\fP to
182 \fIsingle\fP, or skip safety timeout when the target conversion profile is \fIraid5\fP
183 or \fIraid6\fP
184 .UNINDENT
185 .INDENT 7.0
186 .TP
187 .B \-\-background|\-\-bg
188 run the balance operation asynchronously in the background, uses \X'tty: link https://man7.org/linux/man-pages/man2/fork.2.html'\fI\%fork(2)\fP\X'tty: link' to
189 start the process that calls the kernel ioctl
190 .UNINDENT
191 .INDENT 7.0
192 .TP
193 .B \-\-enqueue
194 wait if there\(aqs another exclusive operation running, otherwise continue
195 .TP
196 .B \-v
197 (deprecated) alias for global \(aq\-v\(aq option
198 .UNINDENT
199 .TP
200 .B status [\-v] <path>
201 Show status of running or paused balance.
202 .sp
203 \fBOptions\fP
204 .INDENT 7.0
205 .TP
206 .B \-v
207 (deprecated) alias for global \fI\-v\fP option
208 .UNINDENT
209 .UNINDENT
210 .SH FILTERS
211 .sp
212 From kernel 3.3 onwards, BTRFS balance can limit its action to a subset of the
213 whole filesystem, and can be used to change the replication configuration (e.g.
214 convert data from \fBsingle\fP to \fBRAID1\fP).
215 .sp
216 Balance can be limited to a block group profile with the following options:
217 .INDENT 0.0
218 .IP \(bu 2
219 \fB\-d\fP for data block groups
220 .IP \(bu 2
221 \fB\-m\fP for metadata block groups (also implicitly applies to \fI\-s\fP)
222 .IP \(bu 2
223 \fB\-s\fP for system block groups
224 .UNINDENT
225 .sp
226 The options have an optional parameter which means that the parameter must start
227 right after the option without a space (this is mandatory getopt syntax), like
228 \fB\-dusage=10\fP\&. Options for all block group types can be specified in one command.
229 .sp
230 A filter has the following structure: \fBfilter[=params][,filter=...]\fP
231 .sp
232 To combine multiple filters use \fB,\fP, without spaces. Example: \fB\-dconvert=raid1,soft\fP
233 .sp
234 BTRFS can have different profiles on a single device or the same profile on
235 multiple device.
236 .sp
237 The main reason why you want to have different profiles for data and metadata
238 is to provide additional protection of the filesystem\(aqs metadata when devices fail,
239 since a single sector of unrecoverable metadata will break the filesystem,
240 while a single sector of lost data can be trivially recovered by deleting the broken file.
241 .sp
242 Before changing profiles, make sure there is enough unallocated space on
243 existing drives to create new metadata block groups (for filesystems
244 over 50GiB, this is \fB1GB * (number_of_devices + 2))\fP\&.
245 .sp
246 Default profiles on BTRFS are:
247 .INDENT 0.0
248 .IP \(bu 2
249 data: \fBsingle\fP
250 .IP \(bu 2
251 .INDENT 2.0
252 .TP
253 .B metadata:
254 .INDENT 7.0
255 .IP \(bu 2
256 single devices: \fBdup\fP
257 .IP \(bu 2
258 multiple devices: \fBraid1\fP
259 .UNINDENT
260 .UNINDENT
261 .UNINDENT
262 .sp
263 The available filter types are:
264 .SS Filter types
265 .INDENT 0.0
266 .TP
267 .B profiles=<profiles>
268 Balances only block groups with the given profiles. Parameters
269 are a list of profile names separated by \fB|\fP (pipe).
270 .TP
271 .B usage=<percent>, usage=<range>
272 Balances only block groups with usage under the given percentage. The
273 value of 0 is allowed and will clean up completely unused block groups, this
274 should not require any new work space allocated. You may want to use \fIusage=0\fP
275 in case balance is returning ENOSPC and your filesystem is not too full.
276 .sp
277 The argument may be a single value or a range. The single value \fBN\fP means \fIat
278 most N percent used\fP, equivalent to \fB\&..N\fP range syntax. Kernels prior to 4.4
279 accept only the single value format.
280 The minimum range boundary is inclusive, maximum is exclusive.
281 .TP
282 .B devid=<id>
283 Balances only block groups which have at least one chunk on the given
284 device. To list devices with ids use \fBbtrfs filesystem show\fP\&.
285 .TP
286 .B drange=<range>
287 Balance only block groups which overlap with the given byte range on any
288 device. Use in conjunction with \fBdevid\fP to filter on a specific device. The
289 parameter is a range specified as \fBstart..end\fP\&.
290 .TP
291 .B vrange=<range>
292 Balance only block groups which overlap with the given byte range in the
293 filesystem\(aqs internal virtual address space. This is the address space that
294 most reports from btrfs in the kernel log use. The parameter is a range
295 specified as \fBstart..end\fP\&.
296 .TP
297 .B convert=<profile>
298 Convert each selected block group to the given profile name identified by
299 parameters.
300 .sp
301 \fBNOTE:\fP
302 .INDENT 7.0
303 .INDENT 3.5
304 Starting with kernel 4.5, the \fBdata\fP chunks can be converted to/from the
305 \fBDUP\fP profile on a single device.
306 .sp
307 Starting with kernel 4.6, all profiles can be converted to/from \fBDUP\fP on
308 multi\-device filesystems.
309 .UNINDENT
310 .UNINDENT
311 .sp
312 \fBWARNING:\fP
313 .INDENT 7.0
314 .INDENT 3.5
315 Bad or missing device are not detected immediately during
316 runtime and this depends on some later event like failed write
317 or failed transaction commit. If there\(aqs a known failing
318 device, or a device deleted by \fB/sys/block/<dev>/device/delete\fP interface,
319 the device will be still accessed and written to.
320 .sp
321 In such case, one should not convert to a profile with lower
322 redundancy (e.g. from \fIRAID1\fP to \fISINGLE\fP),
323 as attempts to create new chunks on the new devices will cause
324 various problems.
325 .sp
326 The proper action is to use \fBbtrfs replace\fP or
327 \fBbtrfs device remove\fP to handle the failing/missing
328 device first. Then convert will work with all devices
329 correctly.
330 .UNINDENT
331 .UNINDENT
332 .TP
333 .B limit=<number>, limit=<range>
334 Process only given number of chunks, after all filters are applied. This can be
335 used to specifically target a chunk in connection with other filters (\fBdrange\fP,
336 \fBvrange\fP) or just simply limit the amount of work done by a single balance run.
337 .sp
338 The argument may be a single value or a range. The single value \fBN\fP means \fIat
339 most N chunks\fP, equivalent to \fB\&..N\fP range syntax. Kernels prior to 4.4 accept
340 only the single value format. The range minimum and maximum are inclusive.
341 .TP
342 .B stripes=<range>
343 Balance only block groups which have the given number of stripes. The parameter
344 is a range specified as \fBstart..end\fP\&. Makes sense for block group profiles that
345 utilize striping, i.e. RAID0/10/5/6. The range minimum and maximum are
346 inclusive.
347 .TP
348 .B soft
349 Takes no parameters. Only has meaning when converting between profiles, or
350 When doing convert from one profile to another and soft mode is on,
351 chunks that already have the target profile are left untouched.
352 This is useful e.g. when half of the filesystem was converted earlier but got
353 cancelled.
354 .sp
355 The soft mode switch is (like every other filter) per\-type.
356 For example, this means that we can convert metadata chunks the \(dqhard\(dq way
357 while converting data chunks selectively with soft switch.
358 .UNINDENT
359 .sp
360 Profile names, used in \fBprofiles\fP and \fBconvert\fP are one of:
361 .INDENT 0.0
362 .IP \(bu 2
363 \fBraid0\fP
364 .IP \(bu 2
365 \fBraid1\fP
366 .IP \(bu 2
367 \fBraid1c3\fP
368 .IP \(bu 2
369 \fBraid1c4\fP
370 .IP \(bu 2
371 \fBraid10\fP
372 .IP \(bu 2
373 \fBraid5\fP
374 .IP \(bu 2
375 \fBraid6\fP
376 .IP \(bu 2
377 \fBdup\fP
378 .IP \(bu 2
379 \fBsingle\fP
380 .UNINDENT
381 .sp
382 The mixed data/metadata profiles can be converted in the same way, but conversion
383 between mixed and non\-mixed is not implemented. For the constraints of the
384 profiles please refer to \fI\%mkfs.btrfs(8)\fP section
385 \fI\%PROFILES\fP\&.
386 .SH ENOSPC
387 .sp
388 The way balance operates, it usually needs to temporarily create a new block
389 group and move the old data there, before the old block group can be removed.
390 For that it needs the work space, otherwise it fails for ENOSPC reasons.
391 This is not the same ENOSPC as if the free space is exhausted. This refers to
392 the space on the level of block groups, which are bigger parts of the filesystem
393 that contain many file extents.
394 .sp
395 The free work space can be calculated from the output of the \fBbtrfs filesystem show\fP
396 command:
397 .INDENT 0.0
398 .INDENT 3.5
399 .sp
400 .EX
401 Label: \(aqBTRFS\(aq uuid: 8a9d72cd\-ead3\-469d\-b371\-9c7203276265
402 Total devices 2 FS bytes used 77.03GiB
403 devid 1 size 53.90GiB used 51.90GiB path /dev/sdc2
404 devid 2 size 53.90GiB used 51.90GiB path /dev/sde1
405 .EE
406 .UNINDENT
407 .UNINDENT
408 .sp
409 \fIsize\fP \- \fIused\fP = \fIfree work space\fP
410 .sp
411 \fI53.90GiB\fP \- \fI51.90GiB\fP = \fI2.00GiB\fP
412 .sp
413 An example of a filter that does not require workspace is \fIusage=0\fP\&. This will
414 scan through all unused block groups of a given type and will reclaim the
415 space. After that it might be possible to run other filters.
416 .sp
417 \fBCONVERSIONS ON MULTIPLE DEVICES\fP
418 .sp
419 Conversion to profiles based on striping (RAID0, RAID5/6) require the work
420 space on each device. An interrupted balance may leave partially filled block
421 groups that consume the work space.
422 .SH EXAMPLES
423 .sp
424 A more comprehensive example when going from one to multiple devices, and back,
425 can be found in section \fITYPICAL USECASES\fP of \fI\%btrfs\-device(8)\fP\&.
426 .SS MAKING BLOCK GROUP LAYOUT MORE COMPACT
427 .sp
428 The layout of block groups is not normally visible; most tools report only
429 summarized numbers of free or used space, but there are still some hints
430 provided.
431 .sp
432 Let\(aqs use the following real life example and start with the output:
433 .INDENT 0.0
434 .INDENT 3.5
435 .sp
436 .EX
437 $ btrfs filesystem df /path
438 Data, single: total=75.81GiB, used=64.44GiB
439 System, RAID1: total=32.00MiB, used=20.00KiB
440 Metadata, RAID1: total=15.87GiB, used=8.84GiB
441 GlobalReserve, single: total=512.00MiB, used=0.00B
442 .EE
443 .UNINDENT
444 .UNINDENT
445 .sp
446 Roughly calculating for data, \fI75G \- 64G = 11G\fP, the used/total ratio is
447 about \fI85%\fP\&. How can we can interpret that:
448 .INDENT 0.0
449 .IP \(bu 2
450 chunks are filled by 85% on average, i.e. the \fIusage\fP filter with anything
451 smaller than 85 will likely not affect anything
452 .IP \(bu 2
453 in a more realistic scenario, the space is distributed unevenly, we can
454 assume there are completely used chunks and the remaining are partially filled
455 .UNINDENT
456 .sp
457 Compacting the layout could be used on both. In the former case it would spread
458 data of a given chunk to the others and removing it. Here we can estimate that
459 roughly 850 MiB of data have to be moved (85% of a 1 GiB chunk).
460 .sp
461 In the latter case, targeting the partially used chunks will have to move less
462 data and thus will be faster. A typical filter command would look like:
463 .INDENT 0.0
464 .INDENT 3.5
465 .sp
466 .EX
467 # btrfs balance start \-dusage=50 /path
468 Done, had to relocate 2 out of 97 chunks
469
470 $ btrfs filesystem df /path
471 Data, single: total=74.03GiB, used=64.43GiB
472 System, RAID1: total=32.00MiB, used=20.00KiB
473 Metadata, RAID1: total=15.87GiB, used=8.84GiB
474 GlobalReserve, single: total=512.00MiB, used=0.00B
475 .EE
476 .UNINDENT
477 .UNINDENT
478 .sp
479 As you can see, the \fItotal\fP amount of data is decreased by just 1 GiB, which is
480 an expected result. Let\(aqs see what will happen when we increase the estimated
481 usage filter.
482 .INDENT 0.0
483 .INDENT 3.5
484 .sp
485 .EX
486 # btrfs balance start \-dusage=85 /path
487 Done, had to relocate 13 out of 95 chunks
488
489 $ btrfs filesystem df /path
490 Data, single: total=68.03GiB, used=64.43GiB
491 System, RAID1: total=32.00MiB, used=20.00KiB
492 Metadata, RAID1: total=15.87GiB, used=8.85GiB
493 GlobalReserve, single: total=512.00MiB, used=0.00B
494 .EE
495 .UNINDENT
496 .UNINDENT
497 .sp
498 Now the used/total ratio is about 94% and we moved about \fI74G \- 68G = 6G\fP of
499 data to the remaining block groups, i.e. the 6GiB are now free of filesystem
500 structures, and can be reused for new data or metadata block groups.
501 .sp
502 We can do a similar exercise with the metadata block groups, but this should
503 not typically be necessary, unless the used/total ratio is really off. Here
504 the ratio is roughly 50% but the difference as an absolute number is \(dqa few
505 gigabytes\(dq, which can be considered normal for a workload with snapshots or
506 reflinks updated frequently.
507 .INDENT 0.0
508 .INDENT 3.5
509 .sp
510 .EX
511 # btrfs balance start \-musage=50 /path
512 Done, had to relocate 4 out of 89 chunks
513
514 $ btrfs filesystem df /path
515 Data, single: total=68.03GiB, used=64.43GiB
516 System, RAID1: total=32.00MiB, used=20.00KiB
517 Metadata, RAID1: total=14.87GiB, used=8.85GiB
518 GlobalReserve, single: total=512.00MiB, used=0.00B
519 .EE
520 .UNINDENT
521 .UNINDENT
522 .sp
523 Just 1 GiB decrease, which possibly means there are block groups with good
524 utilization. Making the metadata layout more compact would in turn require
525 updating more metadata structures, i.e. lots of IO. As running out of metadata
526 space is a more severe problem, it\(aqs not necessary to keep the utilization
527 ratio too high. For the purpose of this example, let\(aqs see the effects of
528 further compaction:
529 .INDENT 0.0
530 .INDENT 3.5
531 .sp
532 .EX
533 # btrfs balance start \-musage=70 /path
534 Done, had to relocate 13 out of 88 chunks
535
536 $ btrfs filesystem df .
537 Data, single: total=68.03GiB, used=64.43GiB
538 System, RAID1: total=32.00MiB, used=20.00KiB
539 Metadata, RAID1: total=11.97GiB, used=8.83GiB
540 GlobalReserve, single: total=512.00MiB, used=0.00B
541 .EE
542 .UNINDENT
543 .UNINDENT
544 .SS GETTING RID OF COMPLETELY UNUSED BLOCK GROUPS
545 .sp
546 Normally the balance operation needs a work space, to temporarily move the
547 data before the old block groups gets removed. If there\(aqs no work space, it
548 ends with \fIno space left\fP\&.
549 .sp
550 There\(aqs a special case when the block groups are completely unused, possibly
551 left after removing lots of files or deleting snapshots. Removing empty block
552 groups is automatic since 3.18. The same can be achieved manually with a
553 notable exception that this operation does not require the work space. Thus it
554 can be used to reclaim unused block groups to make it available.
555 .INDENT 0.0
556 .INDENT 3.5
557 .sp
558 .EX
559 # btrfs balance start \-dusage=0 /path
560 .EE
561 .UNINDENT
562 .UNINDENT
563 .sp
564 This should lead to decrease in the \fItotal\fP numbers in the \fBbtrfs filesystem df\fP output.
565 .SH EXIT STATUS
566 .sp
567 Unless indicated otherwise below, all \fBbtrfs balance\fP subcommands
568 return a zero exit status if they succeed, and non zero in case of
569 failure.
570 .sp
571 The \fBpause\fP, \fBcancel\fP, and \fBresume\fP subcommands exit with a status of
572 \fB2\fP if they fail because a balance operation was not running.
573 .sp
574 The \fBstatus\fP subcommand exits with a status of \fB0\fP if a balance
575 operation is not running, \fB1\fP if the command\-line usage is incorrect
576 or a balance operation is still running, and \fB2\fP on other errors.
577 .SH AVAILABILITY
578 .sp
579 \fBbtrfs\fP is part of btrfs\-progs. Please refer to the documentation at
580 \X'tty: link https://btrfs.readthedocs.io'\fI\%https://btrfs.readthedocs.io\fP\X'tty: link'\&.
581 .SH SEE ALSO
582 .sp
583 \fI\%mkfs.btrfs(8)\fP,
584 \fI\%btrfs\-device(8)\fP
585 .\" Generated by docutils manpage writer.
586 .