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. 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
312       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
317           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
321               $ 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
334           The root user will also see stats broken down by block group types:
335
336               Data,single: Size:1.15TiB, Used:1.13TiB
337                  /dev/sdb        1.15TiB
338
339               Metadata,single: Size:12.00GiB, Used:6.45GiB
340                  /dev/sdb       12.00GiB
341
342               System,single: Size:32.00MiB, Used:144.00KiB
343                  /dev/sdb       32.00MiB
344
345               Unallocated:
346                  /dev/sdb      669.99GiB
347
348           Options
349
350           -b|--raw
351               raw numbers in bytes, without the B suffix
352
353           -h|--human-readable
354               print human friendly numbers, base 1024, this is the default
355
356           -H
357               print human friendly numbers, base 1000
358
359           --iec
360               select the 1024 base for the following options, according to
361               the IEC standard
362
363           --si
364               select the 1000 base for the following options, according to
365               the SI standard
366
367           -k|--kbytes
368               show sizes in KiB, or kB with --si
369
370           -m|--mbytes
371               show sizes in MiB, or MB with --si
372
373           -g|--gbytes
374               show sizes in GiB, or GB with --si
375
376           -t|--tbytes
377               show sizes in TiB, or TB with --si
378
379           -T
380               show data in tabular format
381
382               If conflicting options are passed, the last one takes
383               precedence.
384

EXAMPLES

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

EXIT STATUS

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

AVAILABILITY

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

SEE ALSO

445       mkfs.btrfs(8),
446
447
448
449Btrfs v5.4                        12/03/2019               BTRFS-FILESYSTEM(8)
Impressum