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. This is done via a special
309 ioctl and will also trigger cleaning of deleted subvolumes. Besides
310 that it’s equivalent to the sync(1) command.
311 usage [options] <path> [<path>...]
313 Show detailed information about internal filesystem usage. This is
314 supposed to replace the btrfs filesystem df command in the long
315 run.
316 The level of detail can differ if the command is run under a
318 regular or the root user (due to use of restricted ioctl). For both
319 there’s a summary section with information about space usage:
320 $ btrfs filesystem usage /path
322 WARNING: cannot read detailed chunk info, RAID5/6 numbers will be incorrect, run as root
323 Overall:
324 Device size: 1.82TiB
325 Device allocated: 1.17TiB
326 Device unallocated: 669.99GiB
327 Device missing: 0.00B
328 Used: 1.14TiB
329 Free (estimated): 692.57GiB (min: 692.57GiB)
330 Data ratio: 1.00
331 Metadata ratio: 1.00
332 Global reserve: 512.00MiB (used: 0.00B)
333 The root user will also see stats broken down by block group types:
335 Data,single: Size:1.15TiB, Used:1.13TiB
337 /dev/sdb 1.15TiB
338 Metadata,single: Size:12.00GiB, Used:6.45GiB
340 /dev/sdb 12.00GiB
341 System,single: Size:32.00MiB, Used:144.00KiB
343 /dev/sdb 32.00MiB
344 Unallocated:
346 /dev/sdb 669.99GiB
347 Options
349 -b|--raw
351 raw numbers in bytes, without the B suffix
352 -h|--human-readable
354 print human friendly numbers, base 1024, this is the default
355 -H
357 print human friendly numbers, base 1000
358 --iec
360 select the 1024 base for the following options, according to
361 the IEC standard
362 --si
364 select the 1000 base for the following options, according to
365 the SI standard
366 -k|--kbytes
368 show sizes in KiB, or kB with --si
369 -m|--mbytes
371 show sizes in MiB, or MB with --si
372 -g|--gbytes
374 show sizes in GiB, or GB with --si
375 -t|--tbytes
377 show sizes in TiB, or TB with --si
378 -T
380 show data in tabular format
381 If conflicting options are passed, the last one takes
383 precedence.
384
386 $ btrfs filesystem defrag -v -r dir/
387 Recursively defragment files under dir/, print files as they are
389 processed. The file names will be printed in batches, similarly the
390 amount of data triggered by defragmentation will be proportional to
391 last N printed files. The system dirty memory throttling will slow down
392 the defragmentation but there can still be a lot of IO load and the
393 system may stall for a moment.
394 $ btrfs filesystem defrag -v -r -f dir/
396 Recursively defragment files under dir/, be verbose and wait until all
398 blocks are flushed before processing next file. You can note slower
399 progress of the output and lower IO load (proportional to currently
400 defragmented file).
401 $ btrfs filesystem defrag -v -r -f -clzo dir/
403 Recursively defragment files under dir/, be verbose, wait until all
405 blocks are flushed and force file compression.
406 $ btrfs filesystem defrag -v -r -t 64M dir/
408 Recursively defragment files under dir/, be verbose and try to merge
410 extents to be about 64MiB. As stated above, the success rate depends on
411 actual free space fragmentation and the final result is not guaranteed
412 to meet the target even if run repeatedly.
413 $ btrfs filesystem resize -1G /path
415 $ btrfs filesystem resize 1:-1G /path
417 Shrink size of the filesystem’s device id 1 by 1GiB. The first syntax
419 expects a device with id 1 to exist, otherwise fails. The second is
420 equivalent and more explicit. For a single-device filesystem it’s
421 typically not necessary to specify the devid though.
422 $ btrfs filesystem resize max /path
424 $ btrfs filesystem resize 1:max /path
426 Let’s assume that devid 1 exists and the filesystem does not occupy the
428 whole block device, eg. it has been enlarged and we want to grow the
429 filesystem. By simply using max as size we will achieve that.
430 Note
432 There are two ways to minimize the filesystem on a given device.
433 The btrfs inspect-internal min-dev-size command, or iteratively
434 shrink in steps.
435
437 btrfs filesystem returns a zero exit status if it succeeds. Non zero is
438 returned in case of failure.
439
441 btrfs is part of btrfs-progs. Please refer to the btrfs wiki
442 http://btrfs.wiki.kernel.org for further details.
443
445 mkfs.btrfs(8),
446Btrfs v5.4 12/03/2019 BTRFS-FILESYSTEM(8)