1BTRFS-FILESYSTEM(8) BTRFS BTRFS-FILESYSTEM(8)
2
6 btrfs-filesystem - command group that primarily does work on the whole
7 filesystems
8
10 btrfs filesystem <subcommand> <args>
11
13 btrfs filesystem is used to perform several whole filesystem level
14 tasks, including all the regular filesystem operations like resizing,
15 space stats, label setting/getting, and defragmentation. There are
16 other whole filesystem tasks like scrub or balance that are grouped in
17 separate commands.
18
20 df [options] <path>
21 Show a terse summary information about allocation of block group
22 types of a given mount point. The original purpose of this com‐
23 mand was a debugging helper. The output needs to be further in‐
24 terpreted and is not suitable for quick overview.
25 An example with description:
27 • device size: 1.9TiB, one device, no RAID
29 • filesystem size: 1.9TiB
31 • created with: mkfs.btrfs -d single -m single
33 $ btrfs filesystem df /path
35 Data, single: total=1.15TiB, used=1.13TiB
36 System, single: total=32.00MiB, used=144.00KiB
37 Metadata, single: total=12.00GiB, used=6.45GiB
38 GlobalReserve, single: total=512.00MiB, used=0.00B
39 • Data, System and Metadata are separate block group types.
41 GlobalReserve is an artificial and internal emergency space,
42 see below.
43 • single -- the allocation profile, defined at mkfs time
45 • total -- sum of space reserved for all allocation profiles of
47 the given type, i.e. all Data/single. Note that it's not total
48 size of filesystem.
49 • used -- sum of used space of the above, i.e. file extents,
51 metadata blocks
52 GlobalReserve is an artificial and internal emergency space. It
54 is used e.g. when the filesystem is full. Its total size is dy‐
55 namic based on the filesystem size, usually not larger than
56 512MiB, used may fluctuate.
57 The GlobalReserve is a portion of Metadata. In case the filesys‐
59 tem metadata is exhausted, GlobalReserve/total + Metadata/used =
60 Metadata/total. Otherwise there appears to be some unused space
61 of Metadata.
62 Options
64 -b|--raw
66 raw numbers in bytes, without the B suffix
67 -h|--human-readable
69 print human friendly numbers, base 1024, this is the de‐
70 fault
71 -H print human friendly numbers, base 1000
73 --iec select the 1024 base for the following options, according
75 to the IEC standard
76 --si select the 1000 base for the following options, according
78 to the SI standard
79 -k|--kbytes
81 show sizes in KiB, or kB with --si
82 -m|--mbytes
84 show sizes in MiB, or MB with --si
85 -g|--gbytes
87 show sizes in GiB, or GB with --si
88 -t|--tbytes
90 show sizes in TiB, or TB with --si
91 If conflicting options are passed, the last one takes prece‐
93 dence.
94 defragment [options] <file>|<dir> [<file>|<dir>...]
96 Defragment file data on a mounted filesystem. Requires kernel
97 2.6.33 and newer.
98 If -r is passed, files in dir will be defragmented recursively
100 (not descending to subvolumes, mount points and directory sym‐
101 links). The start position and the number of bytes to defrag‐
102 ment can be specified by start and length using -s and -l op‐
103 tions below. Extents bigger than value given by -t will be
104 skipped, otherwise this value is used as a target extent size,
105 but is only advisory and may not be reached if the free space is
106 too fragmented. Use 0 to take the kernel default, which is
107 256KiB but may change in the future. You can also turn on com‐
108 pression in defragment operations.
109 WARNING:
111 Defragmenting with Linux kernel versions < 3.9 or ≥ 3.14-rc2
112 as well as with Linux stable kernel versions ≥ 3.10.31, ≥
113 3.12.12 or ≥ 3.13.4 will break up the reflinks of COW data
114 (for example files copied with cp --reflink, snapshots or
115 de-duplicated data). This may cause considerable increase of
116 space usage depending on the broken up reflinks.
117 NOTE:
119 Directory arguments without -r do not defragment files recur‐
120 sively but will defragment certain internal trees (extent
121 tree and the subvolume tree). This has been confusing and
122 could be removed in the future.
123 For start, len, size it is possible to append units designator:
125 K, M, G, T, P, or E, which represent KiB, MiB, GiB, TiB, PiB, or
126 EiB, respectively (case does not matter).
127 Options
129 -c[<algo>]
131 compress file contents while defragmenting. Optional ar‐
132 gument selects the compression algorithm, zlib (default),
133 lzo or zstd. Currently it's not possible to select no
134 compression. See also section EXAMPLES.
135 -r defragment files recursively in given directories, does
137 not descend to subvolumes or mount points
138 -f flush data for each file before going to the next file.
140 This will limit the amount of dirty data to current file,
142 otherwise the amount accumulates from several files and
143 will increase system load. This can also lead to ENOSPC
144 if there's too much dirty data to write and it's not pos‐
145 sible to make the reservations for the new data (i.e. how
146 the COW design works).
147 -s <start>[kKmMgGtTpPeE]
149 defragmentation will start from the given offset, default
150 is beginning of a file
151 -l <len>[kKmMgGtTpPeE]
153 defragment only up to len bytes, default is the file size
154 -t <size>[kKmMgGtTpPeE]
156 target extent size, do not touch extents bigger than
157 size, default: 32MiB
158 The value is only advisory and the final size of the ex‐
160 tents may differ, depending on the state of the free
161 space and fragmentation or other internal logic. Reason‐
162 able values are from tens to hundreds of megabytes.
163 --step SIZE
165 Perform defragmention in the range in SIZE steps and
166 flush (-f) after each one. The range is default (the
167 whole file) or given by -s and -l, split into the steps
168 or done in one go if the step is larger. Minimum range
169 size is 256KiB.
170 -v (deprecated) alias for global -v option
172 du [options] <path> [<path>..]
174 Calculate disk usage of the target files using FIEMAP. For indi‐
175 vidual files, it will report a count of total bytes, and exclu‐
176 sive (not shared) bytes. We also calculate a 'set shared' value
177 which is described below.
178 Each argument to btrfs filesystem du will have a set shared
180 value calculated for it. We define each set as those files found
181 by a recursive search of an argument (recursion descends to sub‐
182 volumes but not mount points). The set shared value then is a
183 sum of all shared space referenced by the set.
184 set shared takes into account overlapping shared extents, hence
186 it isn't as simple as adding up shared extents.
187 Options
189 -s|--summarize
191 display only a total for each argument
192 --raw raw numbers in bytes, without the B suffix.
194 --human-readable
196 print human friendly numbers, base 1024, this is the de‐
197 fault
198 --iec select the 1024 base for the following options, according
200 to the IEC standard.
201 --si select the 1000 base for the following options, according
203 to the SI standard.
204 --kbytes
206 show sizes in KiB, or kB with --si.
207 --mbytes
209 show sizes in MiB, or MB with --si.
210 --gbytes
212 show sizes in GiB, or GB with --si.
213 --tbytes
215 show sizes in TiB, or TB with --si.
216 label [<device>|<mountpoint>] [<newlabel>]
218 Show or update the label of a filesystem. This works on a
219 mounted filesystem or a filesystem image.
220 The newlabel argument is optional. Current label is printed if
222 the argument is omitted.
223 NOTE:
225 The maximum allowable length shall be less than 256 chars and
226 must not contain a newline. The trailing newline is stripped
227 automatically.
228 mkswapfile [-s size] file
230 Create a new file that's suitable and formatted as a swapfile.
231 Default size is 2GiB, fixed page size 4KiB, minimum size is
232 40KiB.
233 A swapfile must be created in a specific way: NOCOW and preallo‐
235 cated. Subvolume containing a swapfile cannot be snapshotted
236 and blocks of an activated swapfile cannot be balanced.
237 Swapfile creation can be achieved by standalone commands too.
239 Activation needs to be done by command swapon(8). See also com‐
240 mand btrfs inspect-internal map-swapfile and the Swapfile fea‐
241 ture description.
242 NOTE:
244 The command is a simplified version of 'mkswap', if you want
245 to set label, page size, or other parameters please use 'mk‐
246 swap' proper.
247 Options
249 -s|--size SIZE
251 Create swapfile of a given size SIZE (accepting k/m/g/e/p
252 suffix).
253 -U|--uuid UUID
255 specify UUID to use, or a special value: clear (all ze‐
256 ros), random, time (time-based random)
257 resize [options] [<devid>:][+/-]<size>[kKmMgGtTpPeE]|[<devid>:]max
259 <path>
260 Resize a mounted filesystem identified by path. A particular de‐
261 vice can be resized by specifying a devid.
262 WARNING:
264 If path is a file containing a BTRFS image then resize does
265 not work as expected and does not resize the image. This
266 would resize the underlying filesystem instead.
267 The devid can be found in the output of btrfs filesystem show
269 and defaults to 1 if not specified. The size parameter speci‐
270 fies the new size of the filesystem. If the prefix + or - is
271 present the size is increased or decreased by the quantity size.
272 If no units are specified, bytes are assumed for size. Option‐
273 ally, the size parameter may be suffixed by one of the following
274 unit designators: K, M, G, T, P, or E, which represent KiB, MiB,
275 GiB, TiB, PiB, or EiB, respectively (case does not matter).
276 If max is passed, the filesystem will occupy all available space
278 on the device respecting devid (remember, devid 1 by default).
279 The resize command does not manipulate the size of underlying
281 partition. If you wish to enlarge/reduce a filesystem, you must
282 make sure you can expand the partition before enlarging the
283 filesystem and shrink the partition after reducing the size of
284 the filesystem. This can done using fdisk(8) or parted(8) to
285 delete the existing partition and recreate it with the new de‐
286 sired size. When recreating the partition make sure to use the
287 same starting partition offset as before.
288 Growing is usually instant as it only updates the size. However,
290 shrinking could take a long time if there are data in the device
291 area that's beyond the new end. Relocation of the data takes
292 time.
293 See also section EXAMPLES.
295 Options
297 --enqueue
299 wait if there's another exclusive operation running, oth‐
300 erwise continue
301 show [options] [<path>|<uuid>|<device>|<label>]
303 Show the btrfs filesystem with some additional info about de‐
304 vices and space allocation.
305 If no option none of path/uuid/device/label is passed, informa‐
307 tion about all the BTRFS filesystems is shown, both mounted and
308 unmounted.
309 Options
311 -m|--mounted
313 probe kernel for mounted BTRFS filesystems
314 -d|--all-devices
316 scan all devices under /dev, otherwise the devices list
317 is extracted from the /proc/partitions file. This is a
318 fallback option if there's no device node manager (like
319 udev) available in the system.
320 --raw raw numbers in bytes, without the B suffix
322 --human-readable
324 print human friendly numbers, base 1024, this is the de‐
325 fault
326 --iec select the 1024 base for the following options, according
328 to the IEC standard
329 --si select the 1000 base for the following options, according
331 to the SI standard
332 --kbytes
334 show sizes in KiB, or kB with --si
335 --mbytes
337 show sizes in MiB, or MB with --si
338 --gbytes
340 show sizes in GiB, or GB with --si
341 --tbytes
343 show sizes in TiB, or TB with --si
344 sync <path>
346 Force a sync of the filesystem at path, similar to the sync(1)
347 command. In addition, it starts cleaning of deleted subvolumes.
348 To wait for the subvolume deletion to complete use the btrfs
349 subvolume sync command.
350 usage [options] <path> [<path>...]
352 Show detailed information about internal filesystem usage. This
353 is supposed to replace the btrfs filesystem df command in the
354 long run.
355 The level of detail can differ if the command is run under a
357 regular or the root user (due to use of restricted ioctl). For
358 both there's a summary section with information about space us‐
359 age:
360 $ btrfs filesystem usage /path
362 WARNING: cannot read detailed chunk info, RAID5/6 numbers will be incorrect, run as root
363 Overall:
364 Device size: 1.82TiB
365 Device allocated: 1.17TiB
366 Device unallocated: 669.99GiB
367 Device missing: 0.00B
368 Device slack: 1.00GiB
369 Used: 1.14TiB
370 Free (estimated): 692.57GiB (min: 692.57GiB)
371 Free (statfs, df) 692.57GiB
372 Data ratio: 1.00
373 Metadata ratio: 1.00
374 Global reserve: 512.00MiB (used: 0.00B)
375 Multiple profiles: no
376 • Device size -- sum of raw device capacity available to the
378 filesystem, note that this may not be the same as the total
379 device size (the difference is accounted as slack)
380 • Device allocated -- sum of total space allocated for
382 data/metadata/system profiles, this also accounts space re‐
383 served but not yet used for extents
384 • Device unallocated -- the remaining unallocated space for fu‐
386 ture allocations (difference of the above two numbers)
387 • Device missing -- sum of capacity of all missing devices
389 • Device slack -- sum of slack space on all devices (difference
391 between entire device size and the space occupied by filesys‐
392 tem)
393 • Used -- sum of the used space of data/metadata/system pro‐
395 files, not including the reserved space
396 • Free (estimated) -- approximate size of the remaining free
398 space usable for data, including currently allocated space and
399 estimating the usage of the unallocated space based on the
400 block group profiles, the min is the lower bound of the esti‐
401 mate in case multiple profiles are present
402 • Free (statfs, df) -- the amount of space available for data as
404 reported by the statfs syscall, also returned as Avail in the
405 output of df. The value is calculated in a different way and
406 may not match the estimate in some cases (e.g. multiple pro‐
407 files).
408 • Data ratio -- ratio of total space for data including redun‐
410 dancy or parity to the effectively usable data space, e.g.
411 single is 1.0, RAID1 is 2.0 and for RAID5/6 it depends on the
412 number of devices
413 • Metadata ratio -- ditto, for metadata
415 • Global reserve -- portion of metadata currently used for
417 global block reserve, used for emergency purposes (like dele‐
418 tion on a full filesystem)
419 • Multiple profiles -- what block group types (data, metadata)
421 have more than one profile (single, raid1, ...), see btrfs(5)
422 section FILESYSTEMS WITH MULTIPLE PROFILES.
423 And on a zoned filesystem there are two more lines in the Device
425 section:
426 Device zone unusable: 5.13GiB
428 Device zone size: 256.00MiB
429 • Device zone unusable -- sum of of space that's been used in
431 the past but now is not due to COW and not referenced anymore,
432 the chunks have to be reclaimed and zones reset to make it us‐
433 able again
434 • Device zone size -- the reported zone size of the host-managed
436 device, same for all devices
437 The root user will also see stats broken down by block group
439 types:
440 Data,single: Size:1.15TiB, Used:1.13TiB (98.26%)
442 /dev/sdb 1.15TiB
443 Metadata,single: Size:12.00GiB, Used:6.45GiB (53.75%)
445 /dev/sdb 12.00GiB
446 System,single: Size:32.00MiB, Used:144.00KiB (0.44%)
448 /dev/sdb 32.00MiB
449 Unallocated:
451 /dev/sdb 669.99GiB
452 Data is block group type, single is block group profile, Size is
454 total size occupied by this type, Used is the actually used
455 space, the percent is ratio of Used/Size. The Unallocated is re‐
456 maining space.
457 Options
459 -b|--raw
461 raw numbers in bytes, without the B suffix
462 -h|--human-readable
464 print human friendly numbers, base 1024, this is the de‐
465 fault
466 -H print human friendly numbers, base 1000
468 --iec select the 1024 base for the following options, according
470 to the IEC standard
471 --si select the 1000 base for the following options, according
473 to the SI standard
474 -k|--kbytes
476 show sizes in KiB, or kB with --si
477 -m|--mbytes
479 show sizes in MiB, or MB with --si
480 -g|--gbytes
482 show sizes in GiB, or GB with --si
483 -t|--tbytes
485 show sizes in TiB, or TB with --si
486 -T show data in tabular format
488 If conflicting options are passed, the last one takes prece‐
490 dence.
491
493 $ btrfs filesystem defrag -v -r dir/
494 Recursively defragment files under dir/, print files as they are pro‐
496 cessed. The file names will be printed in batches, similarly the
497 amount of data triggered by defragmentation will be proportional to
498 last N printed files. The system dirty memory throttling will slow down
499 the defragmentation but there can still be a lot of IO load and the
500 system may stall for a moment.
501 $ btrfs filesystem defrag -v -r -f dir/
503 Recursively defragment files under dir/, be verbose and wait until all
505 blocks are flushed before processing next file. You can note slower
506 progress of the output and lower IO load (proportional to currently de‐
507 fragmented file).
508 $ btrfs filesystem defrag -v -r -f -clzo dir/
510 Recursively defragment files under dir/, be verbose, wait until all
512 blocks are flushed and force file compression.
513 $ btrfs filesystem defrag -v -r -t 64M dir/
515 Recursively defragment files under dir/, be verbose and try to merge
517 extents to be about 64MiB. As stated above, the success rate depends on
518 actual free space fragmentation and the final result is not guaranteed
519 to meet the target even if run repeatedly.
520 $ btrfs filesystem resize -1G /path
522 $ btrfs filesystem resize 1:-1G /path
524 Shrink size of the filesystem's device id 1 by 1GiB. The first syntax
526 expects a device with id 1 to exist, otherwise fails. The second is
527 equivalent and more explicit. For a single-device filesystem it's typi‐
528 cally not necessary to specify the devid though.
529 $ btrfs filesystem resize max /path
531 $ btrfs filesystem resize 1:max /path
533 Let's assume that devid 1 exists and the filesystem does not occupy the
535 whole block device, e.g. it has been enlarged and we want to grow the
536 filesystem. By simply using max as size we will achieve that.
537 NOTE:
539 There are two ways to minimize the filesystem on a given device. The
540 btrfs inspect-internal min-dev-size command, or iteratively shrink
541 in steps.
542
544 btrfs filesystem returns a zero exit status if it succeeds. Non zero is
545 returned in case of failure.
546
548 btrfs is part of btrfs-progs. Please refer to the documentation at
549 https://btrfs.readthedocs.io.
550
552 btrfs-subvolume(8), mkfs.btrfs(8)
5536.6.2 Nov 24, 2023 BTRFS-FILESYSTEM(8)