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 and mount points). The start position and
103 the number of bytes to defragment can be specified by start and
104 length using -s and -l options below. Extents bigger than value
105 given by -t will be skipped, otherwise this value is used as a
106 target extent size, but is only advisory and may not be reached if
107 the free space is too fragmented. Use 0 to take the kernel default,
108 which is 256kB but may change in the future. You can also turn on
109 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 -v
131 be verbose, print file names as they’re submitted for
132 defragmentation
133 -c[<algo>]
135 compress file contents while defragmenting. Optional argument
136 selects the compression algorithm, zlib (default), lzo or zstd.
137 Currently it’s not possible to select no compression. See also
138 section EXAMPLES.
139 -r
141 defragment files recursively in given directories, does not
142 descend to subvolumes or mount points
143 -f
145 flush data for each file before going to the next file.
146 This will limit the amount of dirty data to current file,
148 otherwise the amount accumulates from several files and will
149 increase system load. This can also lead to ENOSPC if there’s
150 too much dirty data to write and it’s not possible to make the
151 reservations for the new data (ie. how the COW design works).
152 -s <start>[kKmMgGtTpPeE]
154 defragmentation will start from the given offset, default is
155 beginning of a file
156 -l <len>[kKmMgGtTpPeE]
158 defragment only up to len bytes, default is the file size
159 -t <size>[kKmMgGtTpPeE]
161 target extent size, do not touch extents bigger than size,
162 default: 32M
163 The value is only advisory and the final size of the extents
165 may differ, depending on the state of the free space and
166 fragmentation or other internal logic. Reasonable values are
167 from tens to hundreds of megabytes.
168 du [options] <path> [<path>..]
170 Calculate disk usage of the target files using FIEMAP. For
171 individual files, it will report a count of total bytes, and
172 exclusive (not shared) bytes. We also calculate a set shared value
173 which is described below.
174 Each argument to btrfs filesystem du will have a set shared value
176 calculated for it. We define each set as those files found by a
177 recursive search of an argument (recursion descends to subvolumes
178 but not mount points). The set shared value then is a sum of all
179 shared space referenced by the set.
180 set shared takes into account overlapping shared extents, hence it
182 isn’t as simple as adding up shared extents.
183 Options
185 -s|--summarize
187 display only a total for each argument
188 --raw
190 raw numbers in bytes, without the B suffix.
191 --human-readable
193 print human friendly numbers, base 1024, this is the default
194 --iec
196 select the 1024 base for the following options, according to
197 the IEC standard.
198 --si
200 select the 1000 base for the following options, according to
201 the SI standard.
202 --kbytes
204 show sizes in KiB, or kB with --si.
205 --mbytes
207 show sizes in MiB, or MB with --si.
208 --gbytes
210 show sizes in GiB, or GB with --si.
211 --tbytes
213 show sizes in TiB, or TB with --si.
214 label [<device>|<mountpoint>] [<newlabel>]
216 Show or update the label of a filesystem. This works on a mounted
217 filesystem or a filesystem image.
218 The newlabel argument is optional. Current label is printed if the
220 argument is omitted.
221 Note
223 the maximum allowable length shall be less than 256 chars and
224 must not contain a newline. The trailing newline is stripped
225 automatically.
226 resize [<devid>:][+/-]<size>[kKmMgGtTpPeE]|[<devid>:]max <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 show [options] [<path>|<uuid>|<device>|<label>]
263 Show the btrfs filesystem with some additional info about devices
264 and space allocation.
265 If no option none of path/uuid/device/label is passed, information
267 about all the BTRFS filesystems is shown, both mounted and
268 unmounted.
269 Options
271 -m|--mounted
273 probe kernel for mounted BTRFS filesystems
274 -d|--all-devices
276 scan all devices under /dev, otherwise the devices list is
277 extracted from the /proc/partitions file. This is a fallback
278 option if there’s no device node manager (like udev) available
279 in the system.
280 --raw
282 raw numbers in bytes, without the B suffix
283 --human-readable
285 print human friendly numbers, base 1024, this is the default
286 --iec
288 select the 1024 base for the following options, according to
289 the IEC standard
290 --si
292 select the 1000 base for the following options, according to
293 the SI standard
294 --kbytes
296 show sizes in KiB, or kB with --si
297 --mbytes
299 show sizes in MiB, or MB with --si
300 --gbytes
302 show sizes in GiB, or GB with --si
303 --tbytes
305 show sizes in TiB, or TB with --si
306 sync <path>
308 Force a sync of the filesystem at path, similar to the sync(1)
309 command. In addition, it starts cleaning of deleted subvolumes. To
310 wait for the subvolume deletion to complete use the btrfs subvolume
311 sync command.
312 usage [options] <path> [<path>...]
314 Show detailed information about internal filesystem usage. This is
315 supposed to replace the btrfs filesystem df command in the long
316 run.
317 The level of detail can differ if the command is run under a
319 regular or the root user (due to use of restricted ioctl). For both
320 there’s a summary section with information about space usage:
321 $ btrfs filesystem usage /path
323 WARNING: cannot read detailed chunk info, RAID5/6 numbers will be incorrect, run as root
324 Overall:
325 Device size: 1.82TiB
326 Device allocated: 1.17TiB
327 Device unallocated: 669.99GiB
328 Device missing: 0.00B
329 Used: 1.14TiB
330 Free (estimated): 692.57GiB (min: 692.57GiB)
331 Data ratio: 1.00
332 Metadata ratio: 1.00
333 Global reserve: 512.00MiB (used: 0.00B)
334 The root user will also see stats broken down by block group types:
336 Data,single: Size:1.15TiB, Used:1.13TiB
338 /dev/sdb 1.15TiB
339 Metadata,single: Size:12.00GiB, Used:6.45GiB
341 /dev/sdb 12.00GiB
342 System,single: Size:32.00MiB, Used:144.00KiB
344 /dev/sdb 32.00MiB
345 Unallocated:
347 /dev/sdb 669.99GiB
348 Options
350 -b|--raw
352 raw numbers in bytes, without the B suffix
353 -h|--human-readable
355 print human friendly numbers, base 1024, this is the default
356 -H
358 print human friendly numbers, base 1000
359 --iec
361 select the 1024 base for the following options, according to
362 the IEC standard
363 --si
365 select the 1000 base for the following options, according to
366 the SI standard
367 -k|--kbytes
369 show sizes in KiB, or kB with --si
370 -m|--mbytes
372 show sizes in MiB, or MB with --si
373 -g|--gbytes
375 show sizes in GiB, or GB with --si
376 -t|--tbytes
378 show sizes in TiB, or TB with --si
379 -T
381 show data in tabular format
382 If conflicting options are passed, the last one takes
384 precedence.
385
387 $ btrfs filesystem defrag -v -r dir/
388 Recursively defragment files under dir/, print files as they are
390 processed. The file names will be printed in batches, similarly the
391 amount of data triggered by defragmentation will be proportional to
392 last N printed files. The system dirty memory throttling will slow down
393 the defragmentation but there can still be a lot of IO load and the
394 system may stall for a moment.
395 $ btrfs filesystem defrag -v -r -f dir/
397 Recursively defragment files under dir/, be verbose and wait until all
399 blocks are flushed before processing next file. You can note slower
400 progress of the output and lower IO load (proportional to currently
401 defragmented file).
402 $ btrfs filesystem defrag -v -r -f -clzo dir/
404 Recursively defragment files under dir/, be verbose, wait until all
406 blocks are flushed and force file compression.
407 $ btrfs filesystem defrag -v -r -t 64M dir/
409 Recursively defragment files under dir/, be verbose and try to merge
411 extents to be about 64MiB. As stated above, the success rate depends on
412 actual free space fragmentation and the final result is not guaranteed
413 to meet the target even if run repeatedly.
414 $ btrfs filesystem resize -1G /path
416 $ btrfs filesystem resize 1:-1G /path
418 Shrink size of the filesystem’s device id 1 by 1GiB. The first syntax
420 expects a device with id 1 to exist, otherwise fails. The second is
421 equivalent and more explicit. For a single-device filesystem it’s
422 typically not necessary to specify the devid though.
423 $ btrfs filesystem resize max /path
425 $ btrfs filesystem resize 1:max /path
427 Let’s assume that devid 1 exists and the filesystem does not occupy the
429 whole block device, eg. it has been enlarged and we want to grow the
430 filesystem. By simply using max as size we will achieve that.
431 Note
433 There are two ways to minimize the filesystem on a given device.
434 The btrfs inspect-internal min-dev-size command, or iteratively
435 shrink in steps.
436
438 btrfs filesystem returns a zero exit status if it succeeds. Non zero is
439 returned in case of failure.
440
442 btrfs is part of btrfs-progs. Please refer to the btrfs wiki
443 http://btrfs.wiki.kernel.org for further details.
444
446 btrfs-subvolume(8), mkfs.btrfs(8),
447Btrfs v5.6 04/05/2020 BTRFS-FILESYSTEM(8)