1BTRFS-FILESYSTEM(8)              Btrfs Manual              BTRFS-FILESYSTEM(8)
2
3
4

NAME

6       btrfs-filesystem - command group that primarily does work on the whole
7       filesystems
8

SYNOPSIS

10       btrfs filesystem <subcommand> <args>
11

DESCRIPTION

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

SUBCOMMAND

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
26           An example with description:
27
28           ·   device size: 1.9TiB, one device, no RAID
29
30           ·   filesystem size: 1.9TiB
31
32           ·   created with: mkfs.btrfs -d single -m single
33
34               $ 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
40           ·   Data, System and Metadata are separate block group types.
41               GlobalReserve is an artificial and internal emergency space,
42               see below.
43
44           ·   single — the allocation profile, defined at mkfs time
45
46           ·   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
50           ·   used — sum of used space of the above, ie. file extents,
51               metadata blocks
52
53           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
58           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
63           Options
64
65           -b|--raw
66               raw numbers in bytes, without the B suffix
67
68           -h|--human-readable
69               print human friendly numbers, base 1024, this is the default
70
71           -H
72               print human friendly numbers, base 1000
73
74           --iec
75               select the 1024 base for the following options, according to
76               the IEC standard
77
78           --si
79               select the 1000 base for the following options, according to
80               the SI standard
81
82           -k|--kbytes
83               show sizes in KiB, or kB with --si
84
85           -m|--mbytes
86               show sizes in MiB, or MB with --si
87
88           -g|--gbytes
89               show sizes in GiB, or GB with --si
90
91           -t|--tbytes
92               show sizes in TiB, or TB with --si
93
94               If conflicting options are passed, the last one takes
95               precedence.
96
97       defragment [options] <file>|<dir> [<file>|<dir>...]
98           Defragment file data on a mounted filesystem. Requires kernel
99           2.6.33 and newer.
100
101           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
111               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
119               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
128           Options
129
130           -v
131               be verbose, print file names as they’re submitted for
132               defragmentation
133
134           -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
140           -r
141               defragment files recursively in given directories, does not
142               descend to subvolumes or mount points
143
144           -f
145               flush data for each file before going to the next file.
146
147               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
153           -s <start>[kKmMgGtTpPeE]
154               defragmentation will start from the given offset, default is
155               beginning of a file
156
157           -l <len>[kKmMgGtTpPeE]
158               defragment only up to len bytes, default is the file size
159
160           -t <size>[kKmMgGtTpPeE]
161               target extent size, do not touch extents bigger than size,
162               default: 32M
163
164               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
169       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
175           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
181           set shared takes into account overlapping shared extents, hence it
182           isn’t as simple as adding up shared extents.
183
184           Options
185
186           -s|--summarize
187               display only a total for each argument
188
189           --raw
190               raw numbers in bytes, without the B suffix.
191
192           --human-readable
193               print human friendly numbers, base 1024, this is the default
194
195           --iec
196               select the 1024 base for the following options, according to
197               the IEC standard.
198
199           --si
200               select the 1000 base for the following options, according to
201               the SI standard.
202
203           --kbytes
204               show sizes in KiB, or kB with --si.
205
206           --mbytes
207               show sizes in MiB, or MB with --si.
208
209           --gbytes
210               show sizes in GiB, or GB with --si.
211
212           --tbytes
213               show sizes in TiB, or TB with --si.
214
215       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
219           The newlabel argument is optional. Current label is printed if the
220           argument is omitted.
221
222               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
227       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
231               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
244           If max is passed, the filesystem will occupy all available space on
245           the device respecting devid (remember, devid 1 by default).
246
247           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
256           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
260           See also section EXAMPLES.
261
262       show [options] [<path>|<uuid>|<device>|<label>]
263           Show the btrfs filesystem with some additional info about devices
264           and space allocation.
265
266           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
270           Options
271
272           -m|--mounted
273               probe kernel for mounted BTRFS filesystems
274
275           -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
281           --raw
282               raw numbers in bytes, without the B suffix
283
284           --human-readable
285               print human friendly numbers, base 1024, this is the default
286
287           --iec
288               select the 1024 base for the following options, according to
289               the IEC standard
290
291           --si
292               select the 1000 base for the following options, according to
293               the SI standard
294
295           --kbytes
296               show sizes in KiB, or kB with --si
297
298           --mbytes
299               show sizes in MiB, or MB with --si
300
301           --gbytes
302               show sizes in GiB, or GB with --si
303
304           --tbytes
305               show sizes in TiB, or TB with --si
306
307       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
313       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
318           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
322               $ 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
335           The root user will also see stats broken down by block group types:
336
337               Data,single: Size:1.15TiB, Used:1.13TiB
338                  /dev/sdb        1.15TiB
339
340               Metadata,single: Size:12.00GiB, Used:6.45GiB
341                  /dev/sdb       12.00GiB
342
343               System,single: Size:32.00MiB, Used:144.00KiB
344                  /dev/sdb       32.00MiB
345
346               Unallocated:
347                  /dev/sdb      669.99GiB
348
349           Options
350
351           -b|--raw
352               raw numbers in bytes, without the B suffix
353
354           -h|--human-readable
355               print human friendly numbers, base 1024, this is the default
356
357           -H
358               print human friendly numbers, base 1000
359
360           --iec
361               select the 1024 base for the following options, according to
362               the IEC standard
363
364           --si
365               select the 1000 base for the following options, according to
366               the SI standard
367
368           -k|--kbytes
369               show sizes in KiB, or kB with --si
370
371           -m|--mbytes
372               show sizes in MiB, or MB with --si
373
374           -g|--gbytes
375               show sizes in GiB, or GB with --si
376
377           -t|--tbytes
378               show sizes in TiB, or TB with --si
379
380           -T
381               show data in tabular format
382
383               If conflicting options are passed, the last one takes
384               precedence.
385

EXAMPLES

387       $ btrfs filesystem defrag -v -r dir/
388
389       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
396       $ btrfs filesystem defrag -v -r -f dir/
397
398       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
403       $ btrfs filesystem defrag -v -r -f -clzo dir/
404
405       Recursively defragment files under dir/, be verbose, wait until all
406       blocks are flushed and force file compression.
407
408       $ btrfs filesystem defrag -v -r -t 64M dir/
409
410       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
415       $ btrfs filesystem resize -1G /path
416
417       $ btrfs filesystem resize 1:-1G /path
418
419       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
424       $ btrfs filesystem resize max /path
425
426       $ btrfs filesystem resize 1:max /path
427
428       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
432           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

EXIT STATUS

438       btrfs filesystem returns a zero exit status if it succeeds. Non zero is
439       returned in case of failure.
440

AVAILABILITY

442       btrfs is part of btrfs-progs. Please refer to the btrfs wiki
443       http://btrfs.wiki.kernel.org for further details.
444

SEE ALSO

446       btrfs-subvolume(8), mkfs.btrfs(8),
447
448
449
450Btrfs v5.6                        04/05/2020               BTRFS-FILESYSTEM(8)
Impressum