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. The
102 start position and the number of bytes to defragment can be
103 specified by start and length using -s and -l options below.
104 Extents bigger than value given by -t will be skipped, otherwise
105 this value is used as a target extent size, but is only advisory
106 and may not be reached if the free space is too fragmented. Use 0
107 to take the kernel default, which is 256kB but may change in the
108 future. You can also turn on compression in defragment operations.
109 Warning
111 Defragmenting with Linux kernel versions < 3.9 or ≥ 3.14-rc2 as
112 well as with Linux stable kernel versions ≥ 3.10.31, ≥ 3.12.12
113 or ≥ 3.13.4 will break up the reflinks of COW data (for example
114 files copied with cp --reflink, snapshots or de-duplicated
115 data). This may cause considerable increase of space usage
116 depending on the broken up reflinks.
117 Note
119 Directory arguments without -r do not defragment files
120 recursively but will defragment certain internal trees (extent
121 tree and the subvolume tree). This has been confusing and could
122 be removed in the future.
123 For start, len, size it is possible to append units designator:
124 'K', 'M', 'G', 'T', 'P', or 'E', which represent KiB, MiB, GiB,
125 TiB, PiB, or EiB, respectively (case does not matter).
126 Options
128 -v
130 be verbose, print file names as they’re submitted for
131 defragmentation
132 -c[<algo>]
134 compress file contents while defragmenting. Optional argument
135 selects the compression algorithm, zlib (default), lzo or zstd.
136 Currently it’s not possible to select no compression. See also
137 section EXAMPLES.
138 -r
140 defragment files recursively in given directories
141 -f
143 flush data for each file before going to the next file.
144 This will limit the amount of dirty data to current file,
146 otherwise the amount accumulates from several files and will
147 increase system load. This can also lead to ENOSPC if there’s
148 too much dirty data to write and it’s not possible to make the
149 reservations for the new data (ie. how the COW design works).
150 -s <start>[kKmMgGtTpPeE]
152 defragmentation will start from the given offset, default is
153 beginning of a file
154 -l <len>[kKmMgGtTpPeE]
156 defragment only up to len bytes, default is the file size
157 -t <size>[kKmMgGtTpPeE]
159 target extent size, do not touch extents bigger than size,
160 default: 32M
161 The value is only advisory and the final size of the extents
163 may differ, depending on the state of the free space and
164 fragmentation or other internal logic. Reasonable values are
165 from tens to hundreds of megabytes.
166 du [options] <path> [<path>..]
168 Calculate disk usage of the target files using FIEMAP. For
169 individual files, it will report a count of total bytes, and
170 exclusive (not shared) bytes. We also calculate a set shared value
171 which is described below.
172 Each argument to btrfs filesystem du will have a set shared value
174 calculated for it. We define each set as those files found by a
175 recursive search of an argument. The set shared value then is a sum
176 of all shared space referenced by the set.
177 set shared takes into account overlapping shared extents, hence it
179 isn’t as simple as adding up shared extents.
180 Options
182 -s|--summarize
184 display only a total for each argument
185 --raw
187 raw numbers in bytes, without the B suffix.
188 --human-readable
190 print human friendly numbers, base 1024, this is the default
191 --iec
193 select the 1024 base for the following options, according to
194 the IEC standard.
195 --si
197 select the 1000 base for the following options, according to
198 the SI standard.
199 --kbytes
201 show sizes in KiB, or kB with --si.
202 --mbytes
204 show sizes in MiB, or MB with --si.
205 --gbytes
207 show sizes in GiB, or GB with --si.
208 --tbytes
210 show sizes in TiB, or TB with --si.
211 label [<device>|<mountpoint>] [<newlabel>]
213 Show or update the label of a filesystem. This works on a mounted
214 filesystem or a filesystem image.
215 The newlabel argument is optional. Current label is printed if the
217 argument is omitted.
218 Note
220 the maximum allowable length shall be less than 256 chars and
221 must not contain a newline. The trailing newline is stripped
222 automatically.
223 resize [<devid>:][+/-]<size>[kKmMgGtTpPeE]|[<devid>:]max <path>
225 Resize a mounted filesystem identified by path. A particular device
226 can be resized by specifying a devid.
227 Warning
229 If path is a file containing a BTRFS image then resize does not
230 work as expected and does not resize the image. This would
231 resize the underlying filesystem instead.
232 The devid can be found in the output of btrfs filesystem show and
233 defaults to 1 if not specified. The size parameter specifies the
234 new size of the filesystem. If the prefix + or - is present the
235 size is increased or decreased by the quantity size. If no units
236 are specified, bytes are assumed for size. Optionally, the size
237 parameter may be suffixed by one of the following unit designators:
238 'K', 'M', 'G', 'T', 'P', or 'E', which represent KiB, MiB, GiB,
239 TiB, PiB, or EiB, respectively (case does not matter).
240 If max is passed, the filesystem will occupy all available space on
242 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 the
248 filesystem. This can done using fdisk(8) or parted(8) to delete the
249 existing partition and recreate it with the new desired size. When
250 recreating the partition make sure to use the same starting
251 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 time.
256 See also section EXAMPLES.
258 show [options] [<path>|<uuid>|<device>|<label>]
260 Show the btrfs filesystem with some additional info about devices
261 and space allocation.
262 If no option none of path/uuid/device/label is passed, information
264 about all the BTRFS filesystems is shown, both mounted and
265 unmounted.
266 Options
268 -m|--mounted
270 probe kernel for mounted BTRFS filesystems
271 -d|--all-devices
273 scan all devices under /dev, otherwise the devices list is
274 extracted from the /proc/partitions file. This is a fallback
275 option if there’s no device node manager (like udev) available
276 in the system.
277 --raw
279 raw numbers in bytes, without the B suffix
280 --human-readable
282 print human friendly numbers, base 1024, this is the default
283 --iec
285 select the 1024 base for the following options, according to
286 the IEC standard
287 --si
289 select the 1000 base for the following options, according to
290 the SI standard
291 --kbytes
293 show sizes in KiB, or kB with --si
294 --mbytes
296 show sizes in MiB, or MB with --si
297 --gbytes
299 show sizes in GiB, or GB with --si
300 --tbytes
302 show sizes in TiB, or TB with --si
303 sync <path>
305 Force a sync of the filesystem at path. This is done via a special
306 ioctl and will also trigger cleaning of deleted subvolumes. Besides
307 that it’s equivalent to the sync(1) command.
308 usage [options] <path> [<path>...]
310 Show detailed information about internal filesystem usage. This is
311 supposed to replace the btrfs filesystem df command in the long
312 run.
313 The level of detail can differ if the command is run under a
315 regular or the root user (due to use of restricted ioctl). For both
316 there’s a summary section with information about space usage:
317 $ btrfs filesystem usage /path
319 WARNING: cannot read detailed chunk info, RAID5/6 numbers will be incorrect, run as root
320 Overall:
321 Device size: 1.82TiB
322 Device allocated: 1.17TiB
323 Device unallocated: 669.99GiB
324 Device missing: 0.00B
325 Used: 1.14TiB
326 Free (estimated): 692.57GiB (min: 692.57GiB)
327 Data ratio: 1.00
328 Metadata ratio: 1.00
329 Global reserve: 512.00MiB (used: 0.00B)
330 The root user will also see stats broken down by block group types:
332 Data,single: Size:1.15TiB, Used:1.13TiB
334 /dev/sdb 1.15TiB
335 Metadata,single: Size:12.00GiB, Used:6.45GiB
337 /dev/sdb 12.00GiB
338 System,single: Size:32.00MiB, Used:144.00KiB
340 /dev/sdb 32.00MiB
341 Unallocated:
343 /dev/sdb 669.99GiB
344 Options
346 -b|--raw
348 raw numbers in bytes, without the B suffix
349 -h|--human-readable
351 print human friendly numbers, base 1024, this is the default
352 -H
354 print human friendly numbers, base 1000
355 --iec
357 select the 1024 base for the following options, according to
358 the IEC standard
359 --si
361 select the 1000 base for the following options, according to
362 the SI standard
363 -k|--kbytes
365 show sizes in KiB, or kB with --si
366 -m|--mbytes
368 show sizes in MiB, or MB with --si
369 -g|--gbytes
371 show sizes in GiB, or GB with --si
372 -t|--tbytes
374 show sizes in TiB, or TB with --si
375 -T
377 show data in tabular format
378 If conflicting options are passed, the last one takes
380 precedence.
381
383 $ btrfs filesystem defrag -v -r dir/
384 Recursively defragment files under dir/, print files as they are
386 processed. The file names will be printed in batches, similarly the
387 amount of data triggered by defragmentation will be proportional to
388 last N printed files. The system dirty memory throttling will slow down
389 the defragmentation but there can still be a lot of IO load and the
390 system may stall for a moment.
391 $ btrfs filesystem defrag -v -r -f dir/
393 Recursively defragment files under dir/, be verbose and wait until all
395 blocks are flushed before processing next file. You can note slower
396 progress of the output and lower IO load (proportional to currently
397 defragmented file).
398 $ btrfs filesystem defrag -v -r -f -clzo dir/
400 Recursively defragment files under dir/, be verbose, wait until all
402 blocks are flushed and force file compression.
403 $ btrfs filesystem defrag -v -r -t 64M dir/
405 Recursively defragment files under dir/, be verbose and try to merge
407 extents to be about 64MiB. As stated above, the success rate depends on
408 actual free space fragmentation and the final result is not guaranteed
409 to meet the target even if run repeatedly.
410 $ btrfs filesystem resize -1G /path
412 $ btrfs filesystem resize 1:-1G /path
414 Shrink size of the filesystem’s device id 1 by 1GiB. The first syntax
416 expects a device with id 1 to exist, otherwise fails. The second is
417 equivalent and more explicit. For a single-device filesystem it’s
418 typically not necessary to specify the devid though.
419 $ btrfs filesystem resize max /path
421 $ btrfs filesystem resize 1:max /path
423 Let’s assume that devid 1 exists and the filesystem does not occupy the
425 whole block device, eg. it has been enlarged and we want to grow the
426 filesystem. By simply using max as size we will achieve that.
427 Note
429 There are two ways to minimize the filesystem on a given device.
430 The btrfs inspect-internal min-dev-size command, or iteratively
431 shrink in steps.
432
434 btrfs filesystem returns a zero exit status if it succeeds. Non zero is
435 returned in case of failure.
436
438 btrfs is part of btrfs-progs. Please refer to the btrfs wiki
439 http://btrfs.wiki.kernel.org for further details.
440
442 mkfs.btrfs(8),
443Btrfs v5.1 05/17/2019 BTRFS-FILESYSTEM(8)