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, ie. all Data/single. Note that it's not total
48 size of filesystem.
49 • used -- sum of used space of the above, ie. file extents,
51 metadata blocks
52 GlobalReserve is an artificial and internal emergency space. It
54 is used eg. 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 (ie. 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 resize [options] [<devid>:][+/-]<size>[kKmMgGtTpPeE]|[<devid>:]max
223 <path>
224 Resize a mounted filesystem identified by path. A particular de‐
225 vice can be resized by specifying a devid.
226 WARNING:
228 If path is a file containing a BTRFS image then resize does
229 not work as expected and does not resize the image. This
230 would resize the underlying filesystem instead.
231 The devid can be found in the output of btrfs filesystem show
233 and defaults to 1 if not specified. The size parameter speci‐
234 fies the new size of the filesystem. If the prefix + or - is
235 present the size is increased or decreased by the quantity size.
236 If no units are specified, bytes are assumed for size. Option‐
237 ally, the size parameter may be suffixed by one of the following
238 unit designators: K, M, G, T, P, or E, which represent KiB, MiB,
239 GiB, TiB, PiB, or EiB, respectively (case does not matter).
240 If max is passed, the filesystem will occupy all available space
242 on the device respecting devid (remember, devid 1 by default).
243 The resize command does not manipulate the size of underlying
245 partition. If you wish to enlarge/reduce a filesystem, you must
246 make sure you can expand the partition before enlarging the
247 filesystem and shrink the partition after reducing the size of
248 the filesystem. This can done using fdisk(8) or parted(8) to
249 delete the existing partition and recreate it with the new de‐
250 sired size. When recreating the partition make sure to use the
251 same starting partition offset as before.
252 Growing is usually instant as it only updates the size. However,
254 shrinking could take a long time if there are data in the device
255 area that's beyond the new end. Relocation of the data takes
256 time.
257 See also section EXAMPLES.
259 Options
261 --enqueue
263 wait if there's another exclusive operation running, oth‐
264 erwise continue
265 show [options] [<path>|<uuid>|<device>|<label>]
267 Show the btrfs filesystem with some additional info about de‐
268 vices and space allocation.
269 If no option none of path/uuid/device/label is passed, informa‐
271 tion about all the BTRFS filesystems is shown, both mounted and
272 unmounted.
273 Options
275 -m|--mounted
277 probe kernel for mounted BTRFS filesystems
278 -d|--all-devices
280 scan all devices under /dev, otherwise the devices list
281 is extracted from the /proc/partitions file. This is a
282 fallback option if there's no device node manager (like
283 udev) available in the system.
284 --raw raw numbers in bytes, without the B suffix
286 --human-readable
288 print human friendly numbers, base 1024, this is the de‐
289 fault
290 --iec select the 1024 base for the following options, according
292 to the IEC standard
293 --si select the 1000 base for the following options, according
295 to the SI standard
296 --kbytes
298 show sizes in KiB, or kB with --si
299 --mbytes
301 show sizes in MiB, or MB with --si
302 --gbytes
304 show sizes in GiB, or GB with --si
305 --tbytes
307 show sizes in TiB, or TB with --si
308 sync <path>
310 Force a sync of the filesystem at path, similar to the sync(1)
311 command. In addition, it starts cleaning of deleted subvolumes.
312 To wait for the subvolume deletion to complete use the btrfs
313 subvolume sync command.
314 usage [options] <path> [<path>...]
316 Show detailed information about internal filesystem usage. This
317 is supposed to replace the btrfs filesystem df command in the
318 long run.
319 The level of detail can differ if the command is run under a
321 regular or the root user (due to use of restricted ioctl). For
322 both there's a summary section with information about space us‐
323 age:
324 $ btrfs filesystem usage /path
326 WARNING: cannot read detailed chunk info, RAID5/6 numbers will be incorrect, run as root
327 Overall:
328 Device size: 1.82TiB
329 Device allocated: 1.17TiB
330 Device unallocated: 669.99GiB
331 Device missing: 0.00B
332 Used: 1.14TiB
333 Free (estimated): 692.57GiB (min: 692.57GiB)
334 Free (statfs, df) 692.57GiB
335 Data ratio: 1.00
336 Metadata ratio: 1.00
337 Global reserve: 512.00MiB (used: 0.00B)
338 Multiple profiles: no
339 • Device size -- sum of raw device capacity available to the
341 filesystem
342 • Device allocated -- sum of total space allocated for
344 data/metadata/system profiles, this also accounts space re‐
345 served but not yet used for extents
346 • Device unallocated -- the remaining unallocated space for fu‐
348 ture allocations (difference of the above two numbers)
349 • Device missing -- sum of capacity of all missing devices
351 • Used -- sum of the used space of data/metadata/system pro‐
353 files, not including the reserved space
354 • Free (estimated) -- approximate size of the remaining free
356 space usable for data, including currently allocated space and
357 estimating the usage of the unallocated space based on the
358 block group profiles, the min is the lower bound of the esti‐
359 mate in case multiple profiles are present
360 • Free (statfs, df) -- the amount of space available for data as
362 reported by the statfs syscall, also returned as Avail in the
363 output of df. The value is calculated in a different way and
364 may not match the estimate in some cases (eg. multiple pro‐
365 files).
366 • Data ratio -- ratio of total space for data including redun‐
368 dancy or parity to the effectively usable data space, eg. sin‐
369 gle is 1.0, RAID1 is 2.0 and for RAID5/6 it depends on the
370 number of devices
371 • Metadata ratio -- dtto, for metadata
373 • Global reserve -- portion of metadata currently used for
375 global block reserve, used for emergency purposes (like dele‐
376 tion on a full filesystem)
377 • Multiple profiles -- what block group types (data, metadata)
379 have more than one profile (single, raid1, ...), see btrfs(5)
380 section FILESYSTEMS WITH MULTIPLE BLOCK GROUP PROFILES.
381 And on a zoned filesystem there are two more lines in the Device
383 section:
384 Device zone unusable: 5.13GiB
386 Device zone size: 256.00MiB
387 • Device zone unusable -- sum of of space that's been used in
389 the past but now is not due to COW and not referenced anymory,
390 the chunks have to be reclaimed and zones reset to make it us‐
391 able again
392 • Device zone size -- the reported zone size of the host-managed
394 device, same for all devices
395 The root user will also see stats broken down by block group
397 types:
398 Data,single: Size:1.15TiB, Used:1.13TiB (98.26%)
400 /dev/sdb 1.15TiB
401 Metadata,single: Size:12.00GiB, Used:6.45GiB (53.75%)
403 /dev/sdb 12.00GiB
404 System,single: Size:32.00MiB, Used:144.00KiB (0.44%)
406 /dev/sdb 32.00MiB
407 Unallocated:
409 /dev/sdb 669.99GiB
410 Data is block group type, single is block group profile, Size is
412 total size occupied by this type, Used is the actually used
413 space, the percent is ratio of Used/Size. The Unallocated is re‐
414 maining space.
415 Options
417 -b|--raw
419 raw numbers in bytes, without the B suffix
420 -h|--human-readable
422 print human friendly numbers, base 1024, this is the de‐
423 fault
424 -H print human friendly numbers, base 1000
426 --iec select the 1024 base for the following options, according
428 to the IEC standard
429 --si select the 1000 base for the following options, according
431 to the SI standard
432 -k|--kbytes
434 show sizes in KiB, or kB with --si
435 -m|--mbytes
437 show sizes in MiB, or MB with --si
438 -g|--gbytes
440 show sizes in GiB, or GB with --si
441 -t|--tbytes
443 show sizes in TiB, or TB with --si
444 -T show data in tabular format
446 If conflicting options are passed, the last one takes prece‐
448 dence.
449
451 $ btrfs filesystem defrag -v -r dir/
452 Recursively defragment files under dir/, print files as they are pro‐
454 cessed. The file names will be printed in batches, similarly the
455 amount of data triggered by defragmentation will be proportional to
456 last N printed files. The system dirty memory throttling will slow down
457 the defragmentation but there can still be a lot of IO load and the
458 system may stall for a moment.
459 $ btrfs filesystem defrag -v -r -f dir/
461 Recursively defragment files under dir/, be verbose and wait until all
463 blocks are flushed before processing next file. You can note slower
464 progress of the output and lower IO load (proportional to currently de‐
465 fragmented file).
466 $ btrfs filesystem defrag -v -r -f -clzo dir/
468 Recursively defragment files under dir/, be verbose, wait until all
470 blocks are flushed and force file compression.
471 $ btrfs filesystem defrag -v -r -t 64M dir/
473 Recursively defragment files under dir/, be verbose and try to merge
475 extents to be about 64MiB. As stated above, the success rate depends on
476 actual free space fragmentation and the final result is not guaranteed
477 to meet the target even if run repeatedly.
478 $ btrfs filesystem resize -1G /path
480 $ btrfs filesystem resize 1:-1G /path
482 Shrink size of the filesystem's device id 1 by 1GiB. The first syntax
484 expects a device with id 1 to exist, otherwise fails. The second is
485 equivalent and more explicit. For a single-device filesystem it's typi‐
486 cally not necessary to specify the devid though.
487 $ btrfs filesystem resize max /path
489 $ btrfs filesystem resize 1:max /path
491 Let's assume that devid 1 exists and the filesystem does not occupy the
493 whole block device, eg. it has been enlarged and we want to grow the
494 filesystem. By simply using max as size we will achieve that.
495 NOTE:
497 There are two ways to minimize the filesystem on a given device. The
498 btrfs inspect-internal min-dev-size command, or iteratively shrink
499 in steps.
500
502 btrfs filesystem returns a zero exit status if it succeeds. Non zero is
503 returned in case of failure.
504
506 btrfs is part of btrfs-progs. Please refer to the btrfs wiki
507 http://btrfs.wiki.kernel.org for further details.
508
510 btrfs-subvolume(8), mkfs.btrfs(8)
511
513 2022
5145.18 May 25, 2022 BTRFS-FILESYSTEM(8)