Debian Codegraph @

upstream/fedora-44/man8/btrfs-balance.8

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