| 1 |
.\" Man page generated from reStructuredText |
| 2 |
.\" by the Docutils 0.22.4 manpage writer. |
| 3 |
. |
| 4 |
. |
| 5 |
.nr rst2man-indent-level 0 |
| 6 |
. |
| 7 |
.de1 rstReportMargin |
| 8 |
\\$1 \\n[an-margin] |
| 9 |
level \\n[rst2man-indent-level] |
| 10 |
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| 11 |
- |
| 12 |
\\n[rst2man-indent0] |
| 13 |
\\n[rst2man-indent1] |
| 14 |
\\n[rst2man-indent2] |
| 15 |
.. |
| 16 |
.de1 INDENT |
| 17 |
.\" .rstReportMargin pre: |
| 18 |
. RS \\$1 |
| 19 |
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] |
| 20 |
. nr rst2man-indent-level +1 |
| 21 |
.\" .rstReportMargin post: |
| 22 |
.. |
| 23 |
.de UNINDENT |
| 24 |
. RE |
| 25 |
.\" indent \\n[an-margin] |
| 26 |
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| 27 |
.nr rst2man-indent-level -1 |
| 28 |
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| 29 |
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u |
| 30 |
.. |
| 31 |
.TH "BTRFS-FILESYSTEM" "8" "May 10, 2026" "7.0" "BTRFS" |
| 32 |
.SH NAME |
| 33 |
btrfs-filesystem \- command group that primarily does work on the whole filesystems |
| 34 |
.SH SYNOPSIS |
| 35 |
.sp |
| 36 |
\fBbtrfs filesystem\fP <subcommand> <args> |
| 37 |
.SH DESCRIPTION |
| 38 |
.sp |
| 39 |
\fBbtrfs filesystem\fP is used to perform several whole filesystem level tasks, |
| 40 |
including all the regular filesystem operations like resizing, space stats, |
| 41 |
label setting/getting, and defragmentation. There are other whole filesystem |
| 42 |
tasks like scrub or balance that are grouped in separate commands (btrfs\-scrub(8) \%<>, btrfs\-balance(8) \%<>). |
| 43 |
.SH SUBCOMMAND |
| 44 |
.INDENT 0.0 |
| 45 |
.TP |
| 46 |
.B df [options] <path> |
| 47 |
Show a terse summary information about allocation of block group types of a given |
| 48 |
mount point. The original purpose of this command was a debugging helper. The |
| 49 |
output needs to be further interpreted and is not suitable for quick overview. |
| 50 |
.sp |
| 51 |
An example with description: |
| 52 |
.INDENT 7.0 |
| 53 |
.IP \(bu 2 |
| 54 |
device size: \fI1.9TiB\fP, one device, no RAID |
| 55 |
.IP \(bu 2 |
| 56 |
filesystem size: \fI1.9TiB\fP |
| 57 |
.IP \(bu 2 |
| 58 |
created with: \fBmkfs.btrfs \-d single \-m single\fP |
| 59 |
.UNINDENT |
| 60 |
.INDENT 7.0 |
| 61 |
.INDENT 3.5 |
| 62 |
.sp |
| 63 |
.EX |
| 64 |
$ btrfs filesystem df /path |
| 65 |
Data, single: total=1.15TiB, used=1.13TiB |
| 66 |
System, single: total=32.00MiB, used=144.00KiB |
| 67 |
Metadata, single: total=12.00GiB, used=6.45GiB |
| 68 |
GlobalReserve, single: total=512.00MiB, used=0.00B |
| 69 |
.EE |
| 70 |
.UNINDENT |
| 71 |
.UNINDENT |
| 72 |
.INDENT 7.0 |
| 73 |
.IP \(bu 2 |
| 74 |
\fIData\fP, \fISystem\fP and \fIMetadata\fP are separate block group types. |
| 75 |
\fIGlobalReserve\fP is an artificial and internal emergency space, see |
| 76 |
below. |
| 77 |
.IP \(bu 2 |
| 78 |
\fIsingle\fP \-\- the allocation profile, defined at mkfs time |
| 79 |
.IP \(bu 2 |
| 80 |
\fItotal\fP \-\- sum of space reserved for all allocation profiles of the |
| 81 |
given type, i.e. all Data/single. Note that it\(aqs not total size of |
| 82 |
filesystem. |
| 83 |
.IP \(bu 2 |
| 84 |
\fIused\fP \-\- sum of used space of the above, i.e. file extents, metadata blocks |
| 85 |
.UNINDENT |
| 86 |
.sp |
| 87 |
\fIGlobalReserve\fP is an artificial and internal emergency space. It is used e.g. |
| 88 |
when the filesystem is full. Its \fItotal\fP size is dynamic based on the |
| 89 |
filesystem size, usually not larger than 512MiB, \fIused\fP may fluctuate. |
| 90 |
.sp |
| 91 |
The GlobalReserve is a portion of Metadata. In case the filesystem metadata is |
| 92 |
exhausted, \fIGlobalReserve/total + Metadata/used = Metadata/total\fP\&. Otherwise |
| 93 |
there appears to be some unused space of Metadata. |
| 94 |
.sp |
| 95 |
\fBOptions\fP |
| 96 |
.INDENT 7.0 |
| 97 |
.TP |
| 98 |
.B \-b|\-\-raw |
| 99 |
raw numbers in bytes, without the \fIB\fP suffix |
| 100 |
.TP |
| 101 |
.B \-h|\-\-human\-readable |
| 102 |
print human friendly numbers, base 1024, this is the default |
| 103 |
.UNINDENT |
| 104 |
.INDENT 7.0 |
| 105 |
.TP |
| 106 |
.B \-H |
| 107 |
print human friendly numbers, base 1000 |
| 108 |
.TP |
| 109 |
.B \-\-iec |
| 110 |
select the 1024 base for the following options, according to the IEC standard |
| 111 |
.TP |
| 112 |
.B \-\-si |
| 113 |
select the 1000 base for the following options, according to the SI standard |
| 114 |
.UNINDENT |
| 115 |
.INDENT 7.0 |
| 116 |
.TP |
| 117 |
.B \-k|\-\-kbytes |
| 118 |
show sizes in KiB, or kB with \-\-si |
| 119 |
.TP |
| 120 |
.B \-m|\-\-mbytes |
| 121 |
show sizes in MiB, or MB with \-\-si |
| 122 |
.TP |
| 123 |
.B \-g|\-\-gbytes |
| 124 |
show sizes in GiB, or GB with \-\-si |
| 125 |
.TP |
| 126 |
.B \-t|\-\-tbytes |
| 127 |
show sizes in TiB, or TB with \-\-si |
| 128 |
.UNINDENT |
| 129 |
.sp |
| 130 |
If conflicting options are passed, the last one takes precedence. |
| 131 |
.UNINDENT |
| 132 |
.INDENT 0.0 |
| 133 |
.TP |
| 134 |
.B defragment [options] <file>|<dir> [<file>|<dir>...] |
| 135 |
Defragment file data on a mounted filesystem. Requires kernel 2.6.33 and newer. |
| 136 |
.sp |
| 137 |
If \fI\-r\fP is passed, files in \fIdir\fP will be defragmented recursively (not |
| 138 |
descending to subvolumes, mount points and directory symlinks). |
| 139 |
The start position and the number of bytes to defragment can be specified by |
| 140 |
start and length using \fI\-s\fP and \fI\-l\fP options below. |
| 141 |
Extents bigger than value given by \fI\-t\fP will be skipped, otherwise this value |
| 142 |
is used as a target extent size, but is only advisory and may not be reached |
| 143 |
if the free space is too fragmented. |
| 144 |
Use 0 to take the kernel default, which is 256KiB but may change in the future. |
| 145 |
You can also turn on compression in defragment operations. |
| 146 |
.sp |
| 147 |
\fBWarning:\fP |
| 148 |
.INDENT 7.0 |
| 149 |
.INDENT 3.5 |
| 150 |
Defragmenting with Linux kernel versions < 3.9 or ≥ 3.14\-rc2 as well as |
| 151 |
with Linux stable kernel versions ≥ 3.10.31, ≥ 3.12.12 or ≥ 3.13.4 will break up |
| 152 |
the reflinks of COW data (for example files copied with \fBcp \-\-reflink\fP, |
| 153 |
snapshots or de\-duplicated data). |
| 154 |
This may cause considerable increase of space usage depending on the broken up |
| 155 |
reflinks. |
| 156 |
.UNINDENT |
| 157 |
.UNINDENT |
| 158 |
.sp |
| 159 |
\fBNote:\fP |
| 160 |
.INDENT 7.0 |
| 161 |
.INDENT 3.5 |
| 162 |
Directory arguments without \fI\-r\fP do not defragment files recursively but will |
| 163 |
defragment certain internal trees (extent tree and the subvolume tree). This has been |
| 164 |
confusing and could be removed in the future. |
| 165 |
.UNINDENT |
| 166 |
.UNINDENT |
| 167 |
.sp |
| 168 |
For \fIstart\fP, \fIlen\fP, \fIsize\fP it is possible to append |
| 169 |
units designator: \fIK\fP, \fIM\fP, \fIG\fP, \fIT\fP, \fIP\fP, or \fIE\fP, which represent |
| 170 |
KiB, MiB, GiB, TiB, PiB, or EiB, respectively (case does not matter). |
| 171 |
.sp |
| 172 |
\fBOptions\fP |
| 173 |
.INDENT 7.0 |
| 174 |
.TP |
| 175 |
.B \-c[<algo>] |
| 176 |
compress file contents while defragmenting. Optional argument selects the compression |
| 177 |
algorithm, \fIzlib\fP (default), \fIlzo\fP or \fIzstd\fP\&. Currently it\(aqs not possible to select no |
| 178 |
compression. See also section \fIEXAMPLES\fP\&. |
| 179 |
.TP |
| 180 |
.B \-L|\-\-level <level> |
| 181 |
Since kernel 6.15 the compression can also take the level parameter which will be used |
| 182 |
only for the defragmentation and overrides the eventual mount option compression level. |
| 183 |
Valid levels depend on the compression algorithms: \fIzlib\fP |
| 184 |
1..9, \fIlzo\fP does not have any levels, \fIzstd\fP the standard levels 1..15 and also the |
| 185 |
realtime \-1..\-15. |
| 186 |
.UNINDENT |
| 187 |
.INDENT 7.0 |
| 188 |
.TP |
| 189 |
.B \-\-nocomp |
| 190 |
Do not compress while defragmenting, uncompress extents if needed. |
| 191 |
.TP |
| 192 |
.B \-r |
| 193 |
defragment files recursively in given directories, does not descend to |
| 194 |
subvolumes or mount points |
| 195 |
.TP |
| 196 |
.B \-f |
| 197 |
flush data for each file before going to the next file. |
| 198 |
.sp |
| 199 |
This will limit the amount of dirty data to current file, otherwise the amount |
| 200 |
accumulates from several files and will increase system load. This can also lead |
| 201 |
to ENOSPC if there\(aqs too much dirty data to write and it\(aqs not possible to make |
| 202 |
the reservations for the new data (i.e. how the COW design works). |
| 203 |
.UNINDENT |
| 204 |
.INDENT 7.0 |
| 205 |
.TP |
| 206 |
.B \-s <start>[kKmMgGtTpPeE] |
| 207 |
defragmentation will start from the given offset, default is beginning of a file |
| 208 |
.TP |
| 209 |
.B \-l <len>[kKmMgGtTpPeE] |
| 210 |
defragment only up to \fIlen\fP bytes, default is the file size |
| 211 |
.TP |
| 212 |
.B \-t <size>[kKmMgGtTpPeE] |
| 213 |
target extent size, do not touch extents bigger than \fIsize\fP, default: 32MiB |
| 214 |
.sp |
| 215 |
The value is only advisory and the final size of the extents may differ, |
| 216 |
depending on the state of the free space and fragmentation or other internal |
| 217 |
logic. Reasonable values are from tens to hundreds of megabytes. |
| 218 |
.UNINDENT |
| 219 |
.INDENT 7.0 |
| 220 |
.TP |
| 221 |
.BI \-\-step \ SIZE |
| 222 |
Perform defragmentation in the range in SIZE steps and flush (\fI\-f\fP) after each one. |
| 223 |
The range is default (the whole file) or given by \fI\-s\fP and \fI\-l\fP, split into |
| 224 |
the steps or done in one go if the step is larger. Minimum range size is 256KiB. |
| 225 |
With verbosity options the progress of defragmentation will be also printed. |
| 226 |
.TP |
| 227 |
.B \-v |
| 228 |
(deprecated) alias for global \fI\-v\fP option |
| 229 |
.UNINDENT |
| 230 |
.TP |
| 231 |
.B du [options] <path> [<path>..] |
| 232 |
Calculate disk usage of the target files using FIEMAP. For individual |
| 233 |
files, it will report a count of total bytes, and exclusive (not |
| 234 |
shared) bytes. We also calculate a \(aqset shared\(aq value which is |
| 235 |
described below. |
| 236 |
.sp |
| 237 |
Each argument to \fBbtrfs filesystem du\fP will have a \fIset shared\fP value |
| 238 |
calculated for it. We define each \fIset\fP as those files found by a |
| 239 |
recursive search of an argument (recursion descends to subvolumes but not |
| 240 |
mount points). The \fIset shared\fP value then is a sum of all shared space |
| 241 |
referenced by the set. |
| 242 |
.sp |
| 243 |
\fIset shared\fP takes into account overlapping shared extents, hence it |
| 244 |
isn\(aqt as simple as adding up shared extents. |
| 245 |
.sp |
| 246 |
\fBOptions\fP |
| 247 |
.INDENT 7.0 |
| 248 |
.TP |
| 249 |
.B \-s|\-\-summarize |
| 250 |
display only a total for each argument |
| 251 |
.UNINDENT |
| 252 |
.INDENT 7.0 |
| 253 |
.TP |
| 254 |
.B \-\-raw |
| 255 |
raw numbers in bytes, without the \fIB\fP suffix. |
| 256 |
.TP |
| 257 |
.B \-\-human\-readable |
| 258 |
print human friendly numbers, base 1024, this is the default |
| 259 |
.TP |
| 260 |
.B \-\-iec |
| 261 |
select the 1024 base for the following options, according to the IEC standard. |
| 262 |
.TP |
| 263 |
.B \-\-si |
| 264 |
select the 1000 base for the following options, according to the SI standard. |
| 265 |
.TP |
| 266 |
.B \-\-kbytes |
| 267 |
show sizes in KiB, or kB with \-\-si. |
| 268 |
.TP |
| 269 |
.B \-\-mbytes |
| 270 |
show sizes in MiB, or MB with \-\-si. |
| 271 |
.TP |
| 272 |
.B \-\-gbytes |
| 273 |
show sizes in GiB, or GB with \-\-si. |
| 274 |
.TP |
| 275 |
.B \-\-tbytes |
| 276 |
show sizes in TiB, or TB with \-\-si. |
| 277 |
.UNINDENT |
| 278 |
.UNINDENT |
| 279 |
.INDENT 0.0 |
| 280 |
.TP |
| 281 |
.B label [<device>|<mountpoint>] [<newlabel>] |
| 282 |
Show or update the label of a filesystem. This works on a mounted filesystem or |
| 283 |
a filesystem image. |
| 284 |
.sp |
| 285 |
The \fInewlabel\fP argument is optional. Current label is printed if the argument |
| 286 |
is omitted. |
| 287 |
.sp |
| 288 |
\fBNote:\fP |
| 289 |
.INDENT 7.0 |
| 290 |
.INDENT 3.5 |
| 291 |
The maximum allowable length shall be less than 256 chars and must not contain |
| 292 |
a newline. The trailing newline is stripped automatically. |
| 293 |
.UNINDENT |
| 294 |
.UNINDENT |
| 295 |
.TP |
| 296 |
.B mkswapfile [\-s size] file |
| 297 |
Create a new file that\(aqs suitable and formatted as a swapfile. Default |
| 298 |
size is 2GiB, fixed page size 4KiB, minimum size is 40KiB. |
| 299 |
.sp |
| 300 |
A swapfile must be created in a specific way: NOCOW and preallocated. |
| 301 |
Subvolume containing a swapfile cannot be snapshotted and blocks of an |
| 302 |
activated swapfile cannot be balanced. |
| 303 |
.sp |
| 304 |
Swapfile creation can be achieved by standalone commands too. Activation |
| 305 |
needs to be done by command swapon(8) \%<https://\:man7\:.org/\:linux/\:man-pages/\:man8/\:swapon\:.8\:.html>\&. See also command |
| 306 |
\fBbtrfs inspect\-internal map\-swapfile\fP |
| 307 |
and the Swapfile feature \%<> description. |
| 308 |
.sp |
| 309 |
\fBNote:\fP |
| 310 |
.INDENT 7.0 |
| 311 |
.INDENT 3.5 |
| 312 |
The command is a simplified version of \(aqmkswap\(aq, if you want to set |
| 313 |
label, page size, or other parameters please use \(aqmkswap\(aq proper. |
| 314 |
.UNINDENT |
| 315 |
.UNINDENT |
| 316 |
.sp |
| 317 |
\fBOptions\fP |
| 318 |
.INDENT 7.0 |
| 319 |
.TP |
| 320 |
.B \-s|\-\-size SIZE |
| 321 |
Create swapfile of a given size SIZE (accepting k/m/g/e/p |
| 322 |
suffix). |
| 323 |
.TP |
| 324 |
.B \-U|\-\-uuid UUID |
| 325 |
specify UUID to use, or a special value: clear (all zeros), random, |
| 326 |
time (time\-based random) |
| 327 |
.UNINDENT |
| 328 |
.UNINDENT |
| 329 |
.INDENT 0.0 |
| 330 |
.TP |
| 331 |
.B resize [options] [<devid>:][+/\-]<size>[kKmMgGtTpPeE]|[<devid>:]max <path> |
| 332 |
Resize a mounted filesystem identified by \fIpath\fP\&. A particular device |
| 333 |
can be resized by specifying a \fIdevid\fP\&. |
| 334 |
.sp |
| 335 |
\fBNote:\fP |
| 336 |
.INDENT 7.0 |
| 337 |
.INDENT 3.5 |
| 338 |
To resize a file containing a BTRFS image, please use the \-\-offline flag. |
| 339 |
.UNINDENT |
| 340 |
.UNINDENT |
| 341 |
.sp |
| 342 |
The \fIdevid\fP can be found in the output of \fBbtrfs filesystem show\fP and |
| 343 |
defaults to 1 if not specified. |
| 344 |
The \fIsize\fP parameter specifies the new size of the filesystem. |
| 345 |
If the prefix \fI+\fP or \fI\-\fP is present the size is increased or decreased |
| 346 |
by the quantity \fIsize\fP\&. |
| 347 |
If no units are specified, bytes are assumed for \fIsize\fP\&. |
| 348 |
Optionally, the size parameter may be suffixed by one of the following |
| 349 |
unit designators: \fIK\fP, \fIM\fP, \fIG\fP, \fIT\fP, \fIP\fP, or \fIE\fP, which represent |
| 350 |
KiB, MiB, GiB, TiB, PiB, or EiB, respectively (case does not matter). |
| 351 |
.sp |
| 352 |
If \fImax\fP is passed, the filesystem will occupy all available space on the |
| 353 |
device respecting \fIdevid\fP (remember, devid 1 by default). |
| 354 |
.sp |
| 355 |
The resize command does not manipulate the size of underlying |
| 356 |
partition. If you wish to enlarge/reduce a filesystem, you must make sure you |
| 357 |
expand the partition before enlarging the filesystem and shrink the |
| 358 |
partition after reducing the size of the filesystem. This can be done using |
| 359 |
fdisk(8) \%<https://\:man7\:.org/\:linux/\:man-pages/\:man8/\:fdisk\:.8\:.html> or parted(8) \%<https://\:man7\:.org/\:linux/\:man-pages/\:man8/\:parted\:.8\:.html> to delete the existing partition and recreate |
| 360 |
it with the new desired size. When recreating the partition make sure to use |
| 361 |
the same starting partition offset as before. |
| 362 |
.sp |
| 363 |
The size of the portion that the filesystem uses of an underlying device can be |
| 364 |
determined via the \fBbtrfs filesystem show \-\-raw\fP command on the |
| 365 |
filesystem’s mount point (where it’s given for each \fIdevid\fP after the string |
| 366 |
\fIsize\fP or via the \fBbtrfs inspect\-internal dump\-super\fP command on the |
| 367 |
specific device (where it’s given as the value of \fIdev_item.total_bytes\fP, which |
| 368 |
is not to be confused with \fItotal_bytes\fP). |
| 369 |
The value is also the address of the first byte not used by the |
| 370 |
filesystem. |
| 371 |
.sp |
| 372 |
Growing is usually instant as it only updates the size. However, shrinking could |
| 373 |
take a long time if there are data in the device area that\(aqs beyond the new |
| 374 |
end. Relocation of the data takes time. |
| 375 |
.sp |
| 376 |
Note that there\(aqs a lower limit on the new size (either specified |
| 377 |
as an absolute size or difference) that is checked by kernel and |
| 378 |
rejected eventually as invalid. Lower values will print a warning but |
| 379 |
still pass the request to kernel. The currently known value is 256MiB. |
| 380 |
.sp |
| 381 |
See also section \fIEXAMPLES\fP\&. |
| 382 |
.sp |
| 383 |
\fBOptions\fP |
| 384 |
.INDENT 7.0 |
| 385 |
.TP |
| 386 |
.B \-\-enqueue |
| 387 |
wait if there\(aqs another exclusive operation running, otherwise continue |
| 388 |
.TP |
| 389 |
.B \-\-offline |
| 390 |
resize an unmounted (offline) filesystem |
| 391 |
.sp |
| 392 |
\fBWarning:\fP |
| 393 |
.INDENT 7.0 |
| 394 |
.INDENT 3.5 |
| 395 |
The offline resize functionality currently |
| 396 |
supports \fBonly increasing\fP the size of \fBsingle\-device\fP |
| 397 |
filesystems. IOW, shrinking and multi\-device filesystems are |
| 398 |
\fBnot supported\fP with this option. |
| 399 |
.UNINDENT |
| 400 |
.UNINDENT |
| 401 |
.sp |
| 402 |
For filesystems stored in regular files, the file will be |
| 403 |
truncated to the new size as part of the resize operation. |
| 404 |
This flag is cannot be used together with with \-\-enqueue since |
| 405 |
offline resizing is synchronous. |
| 406 |
.UNINDENT |
| 407 |
.TP |
| 408 |
.B show [options] [<path>|<uuid>|<device>|<label>] |
| 409 |
Show the btrfs filesystem with some additional info about devices and space |
| 410 |
allocation. |
| 411 |
.sp |
| 412 |
If no option none of \fIpath\fP/\fIuuid\fP/\fIdevice\fP/\fIlabel\fP is passed, information |
| 413 |
about all the BTRFS filesystems is shown, both mounted and unmounted. |
| 414 |
.sp |
| 415 |
\fBOptions\fP |
| 416 |
.INDENT 7.0 |
| 417 |
.TP |
| 418 |
.B \-m|\-\-mounted |
| 419 |
probe kernel for mounted BTRFS filesystems |
| 420 |
.TP |
| 421 |
.B \-d|\-\-all\-devices |
| 422 |
scan all devices under \fB/dev\fP, otherwise the devices list is extracted from the |
| 423 |
\fB/proc/partitions\fP file. This is a fallback option if there\(aqs no device node |
| 424 |
manager (like udev) available in the system. |
| 425 |
.UNINDENT |
| 426 |
.INDENT 7.0 |
| 427 |
.TP |
| 428 |
.B \-\-raw |
| 429 |
raw numbers in bytes, without the \fIB\fP suffix |
| 430 |
.TP |
| 431 |
.B \-\-human\-readable |
| 432 |
print human friendly numbers, base 1024, this is the default |
| 433 |
.TP |
| 434 |
.B \-\-iec |
| 435 |
select the 1024 base for the following options, according to the IEC standard |
| 436 |
.TP |
| 437 |
.B \-\-si |
| 438 |
select the 1000 base for the following options, according to the SI standard |
| 439 |
.TP |
| 440 |
.B \-\-kbytes |
| 441 |
show sizes in KiB, or kB with \-\-si |
| 442 |
.TP |
| 443 |
.B \-\-mbytes |
| 444 |
show sizes in MiB, or MB with \-\-si |
| 445 |
.TP |
| 446 |
.B \-\-gbytes |
| 447 |
show sizes in GiB, or GB with \-\-si |
| 448 |
.TP |
| 449 |
.B \-\-tbytes |
| 450 |
show sizes in TiB, or TB with \-\-si |
| 451 |
.UNINDENT |
| 452 |
.TP |
| 453 |
.B commit\-stats |
| 454 |
Print number of commits and time stats since mount. This is also available |
| 455 |
in \fB/sys/fs/btrfs/FSID/commit_stats\fP\&. The stats are not persistent |
| 456 |
and are collected since mount of the filesystem, one of them can be reset |
| 457 |
to zero (\fIMax commit duration\fP). |
| 458 |
.INDENT 7.0 |
| 459 |
.INDENT 3.5 |
| 460 |
.sp |
| 461 |
.EX |
| 462 |
UUID: bd18ebe1\-7e1d\-414f\-a3d5\-2644388b51cc |
| 463 |
Commit stats since mount: |
| 464 |
Total commits: 1133 |
| 465 |
Last commit duration: 0ms |
| 466 |
Max commit duration: 10ms |
| 467 |
Total time spent in commit: 4543ms |
| 468 |
.EE |
| 469 |
.UNINDENT |
| 470 |
.UNINDENT |
| 471 |
.sp |
| 472 |
\fBOptions\fP |
| 473 |
.INDENT 7.0 |
| 474 |
.TP |
| 475 |
.B \-z|\-\-reset |
| 476 |
print stats and reset \(aqmax_commit_ms\(aq (needs root) |
| 477 |
.UNINDENT |
| 478 |
.TP |
| 479 |
.B sync <path> |
| 480 |
Force a sync of the filesystem at \fIpath\fP, similar to the sync(1) \%<https://\:man7\:.org/\:linux/\:man-pages/\:man1/\:sync\:.1\:.html> command. In |
| 481 |
addition, it starts cleaning of deleted subvolumes. To wait for the subvolume |
| 482 |
deletion to complete use the \fBbtrfs subvolume sync\fP command. |
| 483 |
.TP |
| 484 |
.B usage [options] <path> [<path>...] |
| 485 |
Show detailed information about internal filesystem usage. This is supposed to |
| 486 |
replace the \fBbtrfs filesystem df\fP command in the long run. |
| 487 |
.sp |
| 488 |
The level of detail can differ if the command is run under a regular or the |
| 489 |
root user (due to use of restricted ioctl). For both there\(aqs a summary section |
| 490 |
with information about space usage: |
| 491 |
.INDENT 7.0 |
| 492 |
.INDENT 3.5 |
| 493 |
.sp |
| 494 |
.EX |
| 495 |
$ btrfs filesystem usage /path |
| 496 |
WARNING: cannot read detailed chunk info, RAID5/6 numbers will be incorrect, run as root |
| 497 |
Overall: |
| 498 |
Device size: 1.82TiB |
| 499 |
Device allocated: 1.17TiB |
| 500 |
Device unallocated: 669.99GiB |
| 501 |
Device missing: 0.00B |
| 502 |
Device slack: 1.00GiB |
| 503 |
Used: 1.14TiB |
| 504 |
Free (estimated): 692.57GiB (min: 692.57GiB) |
| 505 |
Free (statfs, df) 692.57GiB |
| 506 |
Data ratio: 1.00 |
| 507 |
Metadata ratio: 1.00 |
| 508 |
Global reserve: 512.00MiB (used: 0.00B) |
| 509 |
Multiple profiles: no |
| 510 |
.EE |
| 511 |
.UNINDENT |
| 512 |
.UNINDENT |
| 513 |
.INDENT 7.0 |
| 514 |
.IP \(bu 2 |
| 515 |
\fIDevice size\fP \-\- sum of raw device capacity available to the |
| 516 |
filesystem, note that this may not be the same as the total device |
| 517 |
size (the difference is accounted as slack) |
| 518 |
.IP \(bu 2 |
| 519 |
\fIDevice allocated\fP \-\- sum of total space allocated for |
| 520 |
data/metadata/system profiles, this also accounts space reserved but |
| 521 |
not yet used for extents |
| 522 |
.IP \(bu 2 |
| 523 |
\fIDevice unallocated\fP \-\- the remaining unallocated space for future |
| 524 |
allocations (difference of the above two numbers) |
| 525 |
.IP \(bu 2 |
| 526 |
\fIDevice missing\fP \-\- sum of capacity of all missing devices |
| 527 |
.IP \(bu 2 |
| 528 |
\fIDevice slack\fP \-\- sum of slack space on all devices (difference |
| 529 |
between entire device size and the space occupied by filesystem) |
| 530 |
.IP \(bu 2 |
| 531 |
\fIUsed\fP \-\- sum of the used space of data/metadata/system profiles, not |
| 532 |
including the reserved space |
| 533 |
.IP \(bu 2 |
| 534 |
\fIFree (estimated)\fP \-\- approximate size of the remaining free space |
| 535 |
usable for data, including currently allocated space and estimating |
| 536 |
the usage of the unallocated space based on the block group profiles, |
| 537 |
the \fImin\fP is the lower bound of the estimate in case multiple |
| 538 |
profiles are present |
| 539 |
.IP \(bu 2 |
| 540 |
\fIFree (statfs, df)\fP \-\- the amount of space available for data as |
| 541 |
reported by the \fBstatfs/statvfs\fP syscall, also returned as \fIAvail\fP in the |
| 542 |
output of \fBdf\fP\&. The value is calculated in a different way and may |
| 543 |
not match the estimate in some cases (e.g. multiple profiles). |
| 544 |
.IP \(bu 2 |
| 545 |
\fIData ratio\fP \-\- ratio of total space for data including redundancy or |
| 546 |
parity to the effectively usable data space, e.g. single is 1.0, RAID1 |
| 547 |
is 2.0 and for RAID5/6 it depends on the number of devices |
| 548 |
.IP \(bu 2 |
| 549 |
\fIMetadata ratio\fP \-\- ditto, for metadata |
| 550 |
.IP \(bu 2 |
| 551 |
\fIGlobal reserve\fP \-\- portion of metadata currently used for global |
| 552 |
block reserve, used for emergency purposes (like deletion on a full |
| 553 |
filesystem) |
| 554 |
.IP \(bu 2 |
| 555 |
\fIMultiple profiles\fP \-\- what block group types (data, metadata) have |
| 556 |
more than one profile (single, raid1, ...), see btrfs(5) \%<> section |
| 557 |
FILESYSTEMS WITH MULTIPLE PROFILES \%<#\:man-btrfs5-filesystem-with-multiple-profiles>\&. |
| 558 |
.UNINDENT |
| 559 |
.sp |
| 560 |
And on a zoned filesystem there are two more lines in the \fIDevice\fP section: |
| 561 |
.INDENT 7.0 |
| 562 |
.INDENT 3.5 |
| 563 |
.sp |
| 564 |
.EX |
| 565 |
Device zone unusable: 5.13GiB |
| 566 |
Device zone size: 256.00MiB |
| 567 |
.EE |
| 568 |
.UNINDENT |
| 569 |
.UNINDENT |
| 570 |
.INDENT 7.0 |
| 571 |
.IP \(bu 2 |
| 572 |
\fIDevice zone unusable\fP \-\- sum of of space that\(aqs been used in the |
| 573 |
past but now is not due to COW and not referenced anymore, the chunks |
| 574 |
have to be reclaimed and zones reset to make it usable again |
| 575 |
.IP \(bu 2 |
| 576 |
\fIDevice zone size\fP \-\- the reported zone size of the host\-managed |
| 577 |
device, same for all devices |
| 578 |
.UNINDENT |
| 579 |
.sp |
| 580 |
The root user will also see stats broken down by block group types: |
| 581 |
.INDENT 7.0 |
| 582 |
.INDENT 3.5 |
| 583 |
.sp |
| 584 |
.EX |
| 585 |
Data,single: Size:1.15TiB, Used:1.13TiB (98.26%) |
| 586 |
/dev/sdb 1.15TiB |
| 587 |
|
| 588 |
Metadata,single: Size:12.00GiB, Used:6.45GiB (53.75%) |
| 589 |
/dev/sdb 12.00GiB |
| 590 |
|
| 591 |
System,single: Size:32.00MiB, Used:144.00KiB (0.44%) |
| 592 |
/dev/sdb 32.00MiB |
| 593 |
|
| 594 |
Unallocated: |
| 595 |
/dev/sdb 669.99GiB |
| 596 |
.EE |
| 597 |
.UNINDENT |
| 598 |
.UNINDENT |
| 599 |
.sp |
| 600 |
\fIData\fP is block group type, \fIsingle\fP is block group profile, \fISize\fP is total |
| 601 |
size occupied by this type, \fIUsed\fP is the actually used space, the percent is |
| 602 |
ratio of \fIUsed/Size\fP\&. The \fIUnallocated\fP is remaining space. |
| 603 |
.sp |
| 604 |
\fBOptions\fP |
| 605 |
.INDENT 7.0 |
| 606 |
.TP |
| 607 |
.B \-b|\-\-raw |
| 608 |
raw numbers in bytes, without the \fIB\fP suffix |
| 609 |
.TP |
| 610 |
.B \-h|\-\-human\-readable |
| 611 |
print human friendly numbers, base 1024, this is the default |
| 612 |
.UNINDENT |
| 613 |
.INDENT 7.0 |
| 614 |
.TP |
| 615 |
.B \-H |
| 616 |
print human friendly numbers, base 1000 |
| 617 |
.TP |
| 618 |
.B \-\-iec |
| 619 |
select the 1024 base for the following options, according to the IEC standard |
| 620 |
.TP |
| 621 |
.B \-\-si |
| 622 |
select the 1000 base for the following options, according to the SI standard |
| 623 |
.UNINDENT |
| 624 |
.INDENT 7.0 |
| 625 |
.TP |
| 626 |
.B \-k|\-\-kbytes |
| 627 |
show sizes in KiB, or kB with \-\-si |
| 628 |
.TP |
| 629 |
.B \-m|\-\-mbytes |
| 630 |
show sizes in MiB, or MB with \-\-si |
| 631 |
.TP |
| 632 |
.B \-g|\-\-gbytes |
| 633 |
show sizes in GiB, or GB with \-\-si |
| 634 |
.TP |
| 635 |
.B \-t|\-\-tbytes |
| 636 |
show sizes in TiB, or TB with \-\-si |
| 637 |
.UNINDENT |
| 638 |
.INDENT 7.0 |
| 639 |
.TP |
| 640 |
.B \-T |
| 641 |
show data in tabular format |
| 642 |
.UNINDENT |
| 643 |
.sp |
| 644 |
If conflicting options are passed, the last one takes precedence. |
| 645 |
.UNINDENT |
| 646 |
.SH EXAMPLES |
| 647 |
.sp |
| 648 |
\fB$ btrfs filesystem defrag \-v \-r dir/\fP |
| 649 |
.sp |
| 650 |
Recursively defragment files under \fBdir/\fP, print files as they are processed. |
| 651 |
The file names will be printed in batches, similarly the amount of data triggered |
| 652 |
by defragmentation will be proportional to last N printed files. The system dirty |
| 653 |
memory throttling will slow down the defragmentation but there can still be a lot |
| 654 |
of IO load and the system may stall for a moment. |
| 655 |
.sp |
| 656 |
\fB$ btrfs filesystem defrag \-v \-r \-f dir/\fP |
| 657 |
.sp |
| 658 |
Recursively defragment files under \fBdir/\fP, be verbose and wait until all blocks |
| 659 |
are flushed before processing next file. You can note slower progress of the |
| 660 |
output and lower IO load (proportional to currently defragmented file). |
| 661 |
.sp |
| 662 |
\fB$ btrfs filesystem defrag \-v \-r \-f \-clzo dir/\fP |
| 663 |
.sp |
| 664 |
Recursively defragment files under \fBdir/\fP, be verbose, wait until all blocks are |
| 665 |
flushed and force file compression. |
| 666 |
.sp |
| 667 |
\fB$ btrfs filesystem defrag \-v \-r \-t 64M dir/\fP |
| 668 |
.sp |
| 669 |
Recursively defragment files under \fBdir/\fP, be verbose and try to merge extents |
| 670 |
to be about 64MiB. As stated above, the success rate depends on actual free |
| 671 |
space fragmentation and the final result is not guaranteed to meet the target |
| 672 |
even if run repeatedly. |
| 673 |
.sp |
| 674 |
\fB$ btrfs filesystem resize \-1G /path\fP |
| 675 |
.sp |
| 676 |
\fB$ btrfs filesystem resize 1:\-1G /path\fP |
| 677 |
.sp |
| 678 |
Shrink size of the filesystem\(aqs device id 1 by 1GiB. The first syntax expects a |
| 679 |
device with id 1 to exist, otherwise fails. The second is equivalent and more |
| 680 |
explicit. For a single\-device filesystem it\(aqs typically not necessary to |
| 681 |
specify the devid though. |
| 682 |
.sp |
| 683 |
\fB$ btrfs filesystem resize max /path\fP |
| 684 |
.sp |
| 685 |
\fB$ btrfs filesystem resize 1:max /path\fP |
| 686 |
.sp |
| 687 |
Let\(aqs assume that devid 1 exists and the filesystem does not occupy the whole |
| 688 |
block device, e.g. it has been enlarged and we want to grow the filesystem. By |
| 689 |
simply using \fImax\fP as size we will achieve that. |
| 690 |
.sp |
| 691 |
\fBNote:\fP |
| 692 |
.INDENT 0.0 |
| 693 |
.INDENT 3.5 |
| 694 |
There are two ways to minimize the filesystem on a given device. The |
| 695 |
\fBbtrfs inspect\-internal min\-dev\-size\fP command, or iteratively shrink in steps. |
| 696 |
.UNINDENT |
| 697 |
.UNINDENT |
| 698 |
.SH EXIT STATUS |
| 699 |
.sp |
| 700 |
\fBbtrfs filesystem\fP returns a zero exit status if it succeeds. Non zero is |
| 701 |
returned in case of failure. |
| 702 |
.SH AVAILABILITY |
| 703 |
.sp |
| 704 |
\fBbtrfs\fP is part of btrfs\-progs. Please refer to the documentation at |
| 705 |
\%<https://\:btrfs\:.readthedocs\:.io>\&. |
| 706 |
.SH SEE ALSO |
| 707 |
.sp |
| 708 |
btrfs\-subvolume(8) \%<>, |
| 709 |
mkfs.btrfs(8) \%<> |
| 710 |
.\" End of generated man page. |