1BTRFS-FILESYSTEM(8) Btrfs Manual 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 command
23 was a debugging helper. The output needs to be further interpreted
24 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 is
54 used eg. when the filesystem is full. Its total size is dynamic
55 based on the filesystem size, usually not larger than 512MiB, used
56 may fluctuate.
57 The GlobalReserve is a portion of Metadata. In case the filesystem
59 metadata is exhausted, GlobalReserve/total + Metadata/used =
60 Metadata/total. Otherwise there appears to be some unused space of
61 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 default
70 -H
72 print human friendly numbers, base 1000
73 --iec
75 select the 1024 base for the following options, according to
76 the IEC standard
77 --si
79 select the 1000 base for the following options, according to
80 the SI standard
81 -k|--kbytes
83 show sizes in KiB, or kB with --si
84 -m|--mbytes
86 show sizes in MiB, or MB with --si
87 -g|--gbytes
89 show sizes in GiB, or GB with --si
90 -t|--tbytes
92 show sizes in TiB, or TB with --si
93 If conflicting options are passed, the last one takes
95 precedence.
96 defragment [options] <file>|<dir> [<file>|<dir>...]
98 Defragment file data on a mounted filesystem. Requires kernel
99 2.6.33 and newer.
100 If -r is passed, files in dir will be defragmented recursively (not
102 descending to subvolumes, mount points and directory symlinks). The
103 start position and the number of bytes to defragment can be
104 specified by start and length using -s and -l options below.
105 Extents bigger than value given by -t will be skipped, otherwise
106 this value is used as a target extent size, but is only advisory
107 and may not be reached if the free space is too fragmented. Use 0
108 to take the kernel default, which is 256kB but may change in the
109 future. You can also turn on compression in defragment operations.
110 Warning
112 Defragmenting with Linux kernel versions < 3.9 or ≥ 3.14-rc2 as
113 well as with Linux stable kernel versions ≥ 3.10.31, ≥ 3.12.12
114 or ≥ 3.13.4 will break up the reflinks of COW data (for example
115 files copied with cp --reflink, snapshots or de-duplicated
116 data). This may cause considerable increase of space usage
117 depending on the broken up reflinks.
118 Note
120 Directory arguments without -r do not defragment files
121 recursively but will defragment certain internal trees (extent
122 tree and the subvolume tree). This has been confusing and could
123 be removed in the future.
124 For start, len, size it is possible to append units designator:
125 'K', 'M', 'G', 'T', 'P', or 'E', which represent KiB, MiB, GiB,
126 TiB, PiB, or EiB, respectively (case does not matter).
127 Options
129 -c[<algo>]
131 compress file contents while defragmenting. Optional argument
132 selects the compression algorithm, zlib (default), lzo or zstd.
133 Currently it’s not possible to select no compression. See also
134 section EXAMPLES.
135 -r
137 defragment files recursively in given directories, does not
138 descend to subvolumes or mount points
139 -f
141 flush data for each file before going to the next file.
142 This will limit the amount of dirty data to current file,
144 otherwise the amount accumulates from several files and will
145 increase system load. This can also lead to ENOSPC if there’s
146 too much dirty data to write and it’s not possible to make the
147 reservations for the new data (ie. how the COW design works).
148 -s <start>[kKmMgGtTpPeE]
150 defragmentation will start from the given offset, default is
151 beginning of a file
152 -l <len>[kKmMgGtTpPeE]
154 defragment only up to len bytes, default is the file size
155 -t <size>[kKmMgGtTpPeE]
157 target extent size, do not touch extents bigger than size,
158 default: 32M
159 The value is only advisory and the final size of the extents
161 may differ, depending on the state of the free space and
162 fragmentation or other internal logic. Reasonable values are
163 from tens to hundreds of megabytes.
164 -v
166 (deprecated) alias for global -v option
167 du [options] <path> [<path>..]
169 Calculate disk usage of the target files using FIEMAP. For
170 individual files, it will report a count of total bytes, and
171 exclusive (not shared) bytes. We also calculate a set shared value
172 which is described below.
173 Each argument to btrfs filesystem du will have a set shared value
175 calculated for it. We define each set as those files found by a
176 recursive search of an argument (recursion descends to subvolumes
177 but not mount points). The set shared value then is a sum of all
178 shared space referenced by the set.
179 set shared takes into account overlapping shared extents, hence it
181 isn’t as simple as adding up shared extents.
182 Options
184 -s|--summarize
186 display only a total for each argument
187 --raw
189 raw numbers in bytes, without the B suffix.
190 --human-readable
192 print human friendly numbers, base 1024, this is the default
193 --iec
195 select the 1024 base for the following options, according to
196 the IEC standard.
197 --si
199 select the 1000 base for the following options, according to
200 the SI standard.
201 --kbytes
203 show sizes in KiB, or kB with --si.
204 --mbytes
206 show sizes in MiB, or MB with --si.
207 --gbytes
209 show sizes in GiB, or GB with --si.
210 --tbytes
212 show sizes in TiB, or TB with --si.
213 label [<device>|<mountpoint>] [<newlabel>]
215 Show or update the label of a filesystem. This works on a mounted
216 filesystem or a filesystem image.
217 The newlabel argument is optional. Current label is printed if the
219 argument is omitted.
220 Note
222 the maximum allowable length shall be less than 256 chars and
223 must not contain a newline. The trailing newline is stripped
224 automatically.
225 resize [options] [<devid>:][+/-]<size>[kKmMgGtTpPeE]|[<devid>:]max
227 <path>
228 Resize a mounted filesystem identified by path. A particular device
229 can be resized by specifying a devid.
230 Warning
232 If path is a file containing a BTRFS image then resize does not
233 work as expected and does not resize the image. This would
234 resize the underlying filesystem instead.
235 The devid can be found in the output of btrfs filesystem show and
236 defaults to 1 if not specified. The size parameter specifies the
237 new size of the filesystem. If the prefix + or - is present the
238 size is increased or decreased by the quantity size. If no units
239 are specified, bytes are assumed for size. Optionally, the size
240 parameter may be suffixed by one of the following unit designators:
241 'K', 'M', 'G', 'T', 'P', or 'E', which represent KiB, MiB, GiB,
242 TiB, PiB, or EiB, respectively (case does not matter).
243 If max is passed, the filesystem will occupy all available space on
245 the device respecting devid (remember, devid 1 by default).
246 The resize command does not manipulate the size of underlying
248 partition. If you wish to enlarge/reduce a filesystem, you must
249 make sure you can expand the partition before enlarging the
250 filesystem and shrink the partition after reducing the size of the
251 filesystem. This can done using fdisk(8) or parted(8) to delete the
252 existing partition and recreate it with the new desired size. When
253 recreating the partition make sure to use the same starting
254 partition offset as before.
255 Growing is usually instant as it only updates the size. However,
257 shrinking could take a long time if there are data in the device
258 area that’s beyond the new end. Relocation of the data takes time.
259 See also section EXAMPLES.
261 Options
263 --enqueue
265 wait if there’s another exclusive operation running, otherwise
266 continue
267 show [options] [<path>|<uuid>|<device>|<label>]
269 Show the btrfs filesystem with some additional info about devices
270 and space allocation.
271 If no option none of path/uuid/device/label is passed, information
273 about all the BTRFS filesystems is shown, both mounted and
274 unmounted.
275 Options
277 -m|--mounted
279 probe kernel for mounted BTRFS filesystems
280 -d|--all-devices
282 scan all devices under /dev, otherwise the devices list is
283 extracted from the /proc/partitions file. This is a fallback
284 option if there’s no device node manager (like udev) available
285 in the system.
286 --raw
288 raw numbers in bytes, without the B suffix
289 --human-readable
291 print human friendly numbers, base 1024, this is the default
292 --iec
294 select the 1024 base for the following options, according to
295 the IEC standard
296 --si
298 select the 1000 base for the following options, according to
299 the SI standard
300 --kbytes
302 show sizes in KiB, or kB with --si
303 --mbytes
305 show sizes in MiB, or MB with --si
306 --gbytes
308 show sizes in GiB, or GB with --si
309 --tbytes
311 show sizes in TiB, or TB with --si
312 sync <path>
314 Force a sync of the filesystem at path, similar to the sync(1)
315 command. In addition, it starts cleaning of deleted subvolumes. To
316 wait for the subvolume deletion to complete use the btrfs subvolume
317 sync command.
318 usage [options] <path> [<path>...]
320 Show detailed information about internal filesystem usage. This is
321 supposed to replace the btrfs filesystem df command in the long
322 run.
323 The level of detail can differ if the command is run under a
325 regular or the root user (due to use of restricted ioctl). For both
326 there’s a summary section with information about space usage:
327 $ btrfs filesystem usage /path
329 WARNING: cannot read detailed chunk info, RAID5/6 numbers will be incorrect, run as root
330 Overall:
331 Device size: 1.82TiB
332 Device allocated: 1.17TiB
333 Device unallocated: 669.99GiB
334 Device missing: 0.00B
335 Used: 1.14TiB
336 Free (estimated): 692.57GiB (min: 692.57GiB)
337 Free (statfs, df) 692.57GiB
338 Data ratio: 1.00
339 Metadata ratio: 1.00
340 Global reserve: 512.00MiB (used: 0.00B)
341 Multiple profiles: no
342 • Device size — sum of raw device capacity available to the
344 filesystem
345 • Device allocated — sum of total space allocated for
347 data/metadata/system profiles, this also accounts space
348 reserved but not yet used for extents
349 • Device unallocated — the remaining unallocated space for future
351 allocations (difference of the above two numbers)
352 • Device missing — sum of capacity of all missing devices
354 • Used — sum of the used space of data/metadata/system profiles,
356 not including the reserved space
357 • Free (estimated) — approximate size of the remaining free space
359 usable for data, including currently allocated space and
360 estimating the usage of the unallocated space based on the
361 block group profiles, the min is the lower bound of the
362 estimate in case multiple profiles are present
363 • Free (statfs, df) — the amount of space available for data as
365 reported by the statfs syscall, also returned as Avail in the
366 output of df. The value is calculated in a different way and
367 may not match the estimate in some cases (eg. multiple
368 profiles).
369 • Data ratio — ratio of total space for data including redundancy
371 or parity to the effectively usable data space, eg. single is
372 1.0, RAID1 is 2.0 and for RAID5/6 it depends on the number of
373 devices
374 • Metadata ratio — dtto, for metadata
376 • Global reserve — portion of metadata currently used for global
378 block reserve, used for emergency purposes (like deletion on a
379 full filesystem)
380 • Multiple profiles — what block group types (data, metadata)
382 have more than one profile (single, raid1, ...), see btrfs(5)
383 section FILESYSTEMS WITH MULTIPLE BLOCK GROUP PROFILES.
384 The root user will also see stats broken down by block group types:
386 Data,single: Size:1.15TiB, Used:1.13TiB (98.26%)
388 /dev/sdb 1.15TiB
389 Metadata,single: Size:12.00GiB, Used:6.45GiB (53.75%)
391 /dev/sdb 12.00GiB
392 System,single: Size:32.00MiB, Used:144.00KiB (0.44%)
394 /dev/sdb 32.00MiB
395 Unallocated:
397 /dev/sdb 669.99GiB
398 Data is block group type, single is block group profile, Size is
400 total size occupied by this type, Used is the actually used space,
401 the percent is ratio of Used/Size. The Unallocated is remaining
402 space.
403 Options
405 -b|--raw
407 raw numbers in bytes, without the B suffix
408 -h|--human-readable
410 print human friendly numbers, base 1024, this is the default
411 -H
413 print human friendly numbers, base 1000
414 --iec
416 select the 1024 base for the following options, according to
417 the IEC standard
418 --si
420 select the 1000 base for the following options, according to
421 the SI standard
422 -k|--kbytes
424 show sizes in KiB, or kB with --si
425 -m|--mbytes
427 show sizes in MiB, or MB with --si
428 -g|--gbytes
430 show sizes in GiB, or GB with --si
431 -t|--tbytes
433 show sizes in TiB, or TB with --si
434 -T
436 show data in tabular format
437 If conflicting options are passed, the last one takes
439 precedence.
440
442 $ btrfs filesystem defrag -v -r dir/
443 Recursively defragment files under dir/, print files as they are
445 processed. The file names will be printed in batches, similarly the
446 amount of data triggered by defragmentation will be proportional to
447 last N printed files. The system dirty memory throttling will slow down
448 the defragmentation but there can still be a lot of IO load and the
449 system may stall for a moment.
450 $ btrfs filesystem defrag -v -r -f dir/
452 Recursively defragment files under dir/, be verbose and wait until all
454 blocks are flushed before processing next file. You can note slower
455 progress of the output and lower IO load (proportional to currently
456 defragmented file).
457 $ btrfs filesystem defrag -v -r -f -clzo dir/
459 Recursively defragment files under dir/, be verbose, wait until all
461 blocks are flushed and force file compression.
462 $ btrfs filesystem defrag -v -r -t 64M dir/
464 Recursively defragment files under dir/, be verbose and try to merge
466 extents to be about 64MiB. As stated above, the success rate depends on
467 actual free space fragmentation and the final result is not guaranteed
468 to meet the target even if run repeatedly.
469 $ btrfs filesystem resize -1G /path
471 $ btrfs filesystem resize 1:-1G /path
473 Shrink size of the filesystem’s device id 1 by 1GiB. The first syntax
475 expects a device with id 1 to exist, otherwise fails. The second is
476 equivalent and more explicit. For a single-device filesystem it’s
477 typically not necessary to specify the devid though.
478 $ btrfs filesystem resize max /path
480 $ btrfs filesystem resize 1:max /path
482 Let’s assume that devid 1 exists and the filesystem does not occupy the
484 whole block device, eg. it has been enlarged and we want to grow the
485 filesystem. By simply using max as size we will achieve that.
486 Note
488 There are two ways to minimize the filesystem on a given device.
489 The btrfs inspect-internal min-dev-size command, or iteratively
490 shrink in steps.
491
493 btrfs filesystem returns a zero exit status if it succeeds. Non zero is
494 returned in case of failure.
495
497 btrfs is part of btrfs-progs. Please refer to the btrfs wiki
498 http://btrfs.wiki.kernel.org for further details.
499
501 btrfs-subvolume(8), mkfs.btrfs(8),
502Btrfs v5.12.1 05/13/2021 BTRFS-FILESYSTEM(8)