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 -v (deprecated) alias for global -v option
165 du [options] <path> [<path>..]
167 Calculate disk usage of the target files using FIEMAP. For indi‐
168 vidual files, it will report a count of total bytes, and exclu‐
169 sive (not shared) bytes. We also calculate a 'set shared' value
170 which is described below.
171 Each argument to btrfs filesystem du will have a set shared
173 value calculated for it. We define each set as those files found
174 by a recursive search of an argument (recursion descends to sub‐
175 volumes but not mount points). The set shared value then is a
176 sum of all shared space referenced by the set.
177 set shared takes into account overlapping shared extents, hence
179 it isn't as simple as adding up shared extents.
180 Options
182 -s|--summarize
184 display only a total for each argument
185 --raw raw numbers in bytes, without the B suffix.
187 --human-readable
189 print human friendly numbers, base 1024, this is the de‐
190 fault
191 --iec select the 1024 base for the following options, according
193 to the IEC standard.
194 --si select the 1000 base for the following options, according
196 to the SI standard.
197 --kbytes
199 show sizes in KiB, or kB with --si.
200 --mbytes
202 show sizes in MiB, or MB with --si.
203 --gbytes
205 show sizes in GiB, or GB with --si.
206 --tbytes
208 show sizes in TiB, or TB with --si.
209 label [<device>|<mountpoint>] [<newlabel>]
211 Show or update the label of a filesystem. This works on a
212 mounted filesystem or a filesystem image.
213 The newlabel argument is optional. Current label is printed if
215 the argument is omitted.
216 NOTE:
218 The maximum allowable length shall be less than 256 chars and
219 must not contain a newline. The trailing newline is stripped
220 automatically.
221 mkswapfile [-s size] file
223 Create a new file that's suitable and formatted as a swapfile.
224 Default size is 2GiB, fixed page size 4KiB, minimum size is
225 40KiB.
226 A swapfile must be created in a specific way: NOCOW and preallo‐
228 cated. Subvolume containing a swapfile cannot be snapshotted
229 and blocks of an activated swapfile cannot be balanced.
230 Swapfile creation can be achieved by standalone commands too.
232 Activation needs to be done by command swapon(8). See also com‐
233 mand btrfs inspect-internal map-swapfile and the Swapfile fea‐
234 ture description.
235 NOTE:
237 The command is a simplified version of 'mkswap', if you want
238 to set label, page size, or other parameters please use 'mk‐
239 swap' proper.
240 Options
242 -s|--size SIZE
244 Create swapfile of a given size SIZE (accepting k/m/g/e/p
245 suffix).
246 resize [options] [<devid>:][+/-]<size>[kKmMgGtTpPeE]|[<devid>:]max
248 <path>
249 Resize a mounted filesystem identified by path. A particular de‐
250 vice can be resized by specifying a devid.
251 WARNING:
253 If path is a file containing a BTRFS image then resize does
254 not work as expected and does not resize the image. This
255 would resize the underlying filesystem instead.
256 The devid can be found in the output of btrfs filesystem show
258 and defaults to 1 if not specified. The size parameter speci‐
259 fies the new size of the filesystem. If the prefix + or - is
260 present the size is increased or decreased by the quantity size.
261 If no units are specified, bytes are assumed for size. Option‐
262 ally, the size parameter may be suffixed by one of the following
263 unit designators: K, M, G, T, P, or E, which represent KiB, MiB,
264 GiB, TiB, PiB, or EiB, respectively (case does not matter).
265 If max is passed, the filesystem will occupy all available space
267 on the device respecting devid (remember, devid 1 by default).
268 The resize command does not manipulate the size of underlying
270 partition. If you wish to enlarge/reduce a filesystem, you must
271 make sure you can expand the partition before enlarging the
272 filesystem and shrink the partition after reducing the size of
273 the filesystem. This can done using fdisk(8) or parted(8) to
274 delete the existing partition and recreate it with the new de‐
275 sired size. When recreating the partition make sure to use the
276 same starting partition offset as before.
277 Growing is usually instant as it only updates the size. However,
279 shrinking could take a long time if there are data in the device
280 area that's beyond the new end. Relocation of the data takes
281 time.
282 See also section EXAMPLES.
284 Options
286 --enqueue
288 wait if there's another exclusive operation running, oth‐
289 erwise continue
290 show [options] [<path>|<uuid>|<device>|<label>]
292 Show the btrfs filesystem with some additional info about de‐
293 vices and space allocation.
294 If no option none of path/uuid/device/label is passed, informa‐
296 tion about all the BTRFS filesystems is shown, both mounted and
297 unmounted.
298 Options
300 -m|--mounted
302 probe kernel for mounted BTRFS filesystems
303 -d|--all-devices
305 scan all devices under /dev, otherwise the devices list
306 is extracted from the /proc/partitions file. This is a
307 fallback option if there's no device node manager (like
308 udev) available in the system.
309 --raw raw numbers in bytes, without the B suffix
311 --human-readable
313 print human friendly numbers, base 1024, this is the de‐
314 fault
315 --iec select the 1024 base for the following options, according
317 to the IEC standard
318 --si select the 1000 base for the following options, according
320 to the SI standard
321 --kbytes
323 show sizes in KiB, or kB with --si
324 --mbytes
326 show sizes in MiB, or MB with --si
327 --gbytes
329 show sizes in GiB, or GB with --si
330 --tbytes
332 show sizes in TiB, or TB with --si
333 sync <path>
335 Force a sync of the filesystem at path, similar to the sync(1)
336 command. In addition, it starts cleaning of deleted subvolumes.
337 To wait for the subvolume deletion to complete use the btrfs
338 subvolume sync command.
339 usage [options] <path> [<path>...]
341 Show detailed information about internal filesystem usage. This
342 is supposed to replace the btrfs filesystem df command in the
343 long run.
344 The level of detail can differ if the command is run under a
346 regular or the root user (due to use of restricted ioctl). For
347 both there's a summary section with information about space us‐
348 age:
349 $ btrfs filesystem usage /path
351 WARNING: cannot read detailed chunk info, RAID5/6 numbers will be incorrect, run as root
352 Overall:
353 Device size: 1.82TiB
354 Device allocated: 1.17TiB
355 Device unallocated: 669.99GiB
356 Device missing: 0.00B
357 Device slack: 1.00GiB
358 Used: 1.14TiB
359 Free (estimated): 692.57GiB (min: 692.57GiB)
360 Free (statfs, df) 692.57GiB
361 Data ratio: 1.00
362 Metadata ratio: 1.00
363 Global reserve: 512.00MiB (used: 0.00B)
364 Multiple profiles: no
365 • Device size -- sum of raw device capacity available to the
367 filesystem, note that this may not be the same as the total
368 device size (the difference is accounted as slack)
369 • Device allocated -- sum of total space allocated for
371 data/metadata/system profiles, this also accounts space re‐
372 served but not yet used for extents
373 • Device unallocated -- the remaining unallocated space for fu‐
375 ture allocations (difference of the above two numbers)
376 • Device missing -- sum of capacity of all missing devices
378 • Device slack -- sum of slack space on all devices (difference
380 between entire device size and the space occupied by filesys‐
381 tem)
382 • Used -- sum of the used space of data/metadata/system pro‐
384 files, not including the reserved space
385 • Free (estimated) -- approximate size of the remaining free
387 space usable for data, including currently allocated space and
388 estimating the usage of the unallocated space based on the
389 block group profiles, the min is the lower bound of the esti‐
390 mate in case multiple profiles are present
391 • Free (statfs, df) -- the amount of space available for data as
393 reported by the statfs syscall, also returned as Avail in the
394 output of df. The value is calculated in a different way and
395 may not match the estimate in some cases (e.g. multiple pro‐
396 files).
397 • Data ratio -- ratio of total space for data including redun‐
399 dancy or parity to the effectively usable data space, e.g.
400 single is 1.0, RAID1 is 2.0 and for RAID5/6 it depends on the
401 number of devices
402 • Metadata ratio -- ditto, for metadata
404 • Global reserve -- portion of metadata currently used for
406 global block reserve, used for emergency purposes (like dele‐
407 tion on a full filesystem)
408 • Multiple profiles -- what block group types (data, metadata)
410 have more than one profile (single, raid1, ...), see btrfs(5)
411 section FILESYSTEMS WITH MULTIPLE BLOCK GROUP PROFILES.
412 And on a zoned filesystem there are two more lines in the Device
414 section:
415 Device zone unusable: 5.13GiB
417 Device zone size: 256.00MiB
418 • Device zone unusable -- sum of of space that's been used in
420 the past but now is not due to COW and not referenced anymore,
421 the chunks have to be reclaimed and zones reset to make it us‐
422 able again
423 • Device zone size -- the reported zone size of the host-managed
425 device, same for all devices
426 The root user will also see stats broken down by block group
428 types:
429 Data,single: Size:1.15TiB, Used:1.13TiB (98.26%)
431 /dev/sdb 1.15TiB
432 Metadata,single: Size:12.00GiB, Used:6.45GiB (53.75%)
434 /dev/sdb 12.00GiB
435 System,single: Size:32.00MiB, Used:144.00KiB (0.44%)
437 /dev/sdb 32.00MiB
438 Unallocated:
440 /dev/sdb 669.99GiB
441 Data is block group type, single is block group profile, Size is
443 total size occupied by this type, Used is the actually used
444 space, the percent is ratio of Used/Size. The Unallocated is re‐
445 maining space.
446 Options
448 -b|--raw
450 raw numbers in bytes, without the B suffix
451 -h|--human-readable
453 print human friendly numbers, base 1024, this is the de‐
454 fault
455 -H print human friendly numbers, base 1000
457 --iec select the 1024 base for the following options, according
459 to the IEC standard
460 --si select the 1000 base for the following options, according
462 to the SI standard
463 -k|--kbytes
465 show sizes in KiB, or kB with --si
466 -m|--mbytes
468 show sizes in MiB, or MB with --si
469 -g|--gbytes
471 show sizes in GiB, or GB with --si
472 -t|--tbytes
474 show sizes in TiB, or TB with --si
475 -T show data in tabular format
477 If conflicting options are passed, the last one takes prece‐
479 dence.
480
482 $ btrfs filesystem defrag -v -r dir/
483 Recursively defragment files under dir/, print files as they are pro‐
485 cessed. The file names will be printed in batches, similarly the
486 amount of data triggered by defragmentation will be proportional to
487 last N printed files. The system dirty memory throttling will slow down
488 the defragmentation but there can still be a lot of IO load and the
489 system may stall for a moment.
490 $ btrfs filesystem defrag -v -r -f dir/
492 Recursively defragment files under dir/, be verbose and wait until all
494 blocks are flushed before processing next file. You can note slower
495 progress of the output and lower IO load (proportional to currently de‐
496 fragmented file).
497 $ btrfs filesystem defrag -v -r -f -clzo dir/
499 Recursively defragment files under dir/, be verbose, wait until all
501 blocks are flushed and force file compression.
502 $ btrfs filesystem defrag -v -r -t 64M dir/
504 Recursively defragment files under dir/, be verbose and try to merge
506 extents to be about 64MiB. As stated above, the success rate depends on
507 actual free space fragmentation and the final result is not guaranteed
508 to meet the target even if run repeatedly.
509 $ btrfs filesystem resize -1G /path
511 $ btrfs filesystem resize 1:-1G /path
513 Shrink size of the filesystem's device id 1 by 1GiB. The first syntax
515 expects a device with id 1 to exist, otherwise fails. The second is
516 equivalent and more explicit. For a single-device filesystem it's typi‐
517 cally not necessary to specify the devid though.
518 $ btrfs filesystem resize max /path
520 $ btrfs filesystem resize 1:max /path
522 Let's assume that devid 1 exists and the filesystem does not occupy the
524 whole block device, e.g. it has been enlarged and we want to grow the
525 filesystem. By simply using max as size we will achieve that.
526 NOTE:
528 There are two ways to minimize the filesystem on a given device. The
529 btrfs inspect-internal min-dev-size command, or iteratively shrink
530 in steps.
531
533 btrfs filesystem returns a zero exit status if it succeeds. Non zero is
534 returned in case of failure.
535
537 btrfs is part of btrfs-progs. Please refer to the documentation at
538 https://btrfs.readthedocs.io or wiki http://btrfs.wiki.kernel.org for
539 further information.
540
542 btrfs-subvolume(8), mkfs.btrfs(8)
5436.1.3 Jan 25, 2023 BTRFS-FILESYSTEM(8)