diff options
Diffstat (limited to 'upstream/debian-bookworm/man8/btrfs-filesystem.8')
| -rw-r--r-- | upstream/debian-bookworm/man8/btrfs-filesystem.8 | 640 |
1 files changed, 640 insertions, 0 deletions
diff --git a/upstream/debian-bookworm/man8/btrfs-filesystem.8 b/upstream/debian-bookworm/man8/btrfs-filesystem.8 new file mode 100644 index 00000000..27dc963a --- /dev/null +++ b/upstream/debian-bookworm/man8/btrfs-filesystem.8 @@ -0,0 +1,640 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "BTRFS-FILESYSTEM" "8" "Feb 28, 2023" "6.2" "BTRFS" +.SH NAME +btrfs-filesystem \- command group that primarily does work on the whole filesystems +.SH SYNOPSIS +.sp +\fBbtrfs filesystem\fP <subcommand> <args> +.SH DESCRIPTION +.sp +\fBbtrfs filesystem\fP is used to perform several whole filesystem level tasks, +including all the regular filesystem operations like resizing, space stats, +label setting/getting, and defragmentation. There are other whole filesystem +tasks like scrub or balance that are grouped in separate commands. +.SH SUBCOMMAND +.INDENT 0.0 +.TP +.B df [options] <path> +Show a terse summary information about allocation of block group types of a given +mount point. The original purpose of this command was a debugging helper. The +output needs to be further interpreted and is not suitable for quick overview. +.sp +An example with description: +.INDENT 7.0 +.IP \(bu 2 +device size: \fI1.9TiB\fP, one device, no RAID +.IP \(bu 2 +filesystem size: \fI1.9TiB\fP +.IP \(bu 2 +created with: \fBmkfs.btrfs \-d single \-m single\fP +.UNINDENT +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ btrfs filesystem df /path +Data, single: total=1.15TiB, used=1.13TiB +System, single: total=32.00MiB, used=144.00KiB +Metadata, single: total=12.00GiB, used=6.45GiB +GlobalReserve, single: total=512.00MiB, used=0.00B +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 7.0 +.IP \(bu 2 +\fIData\fP, \fISystem\fP and \fIMetadata\fP are separate block group types. +\fIGlobalReserve\fP is an artificial and internal emergency space, see +below. +.IP \(bu 2 +\fIsingle\fP \-\- the allocation profile, defined at mkfs time +.IP \(bu 2 +\fItotal\fP \-\- sum of space reserved for all allocation profiles of the +given type, i.e. all Data/single. Note that it\(aqs not total size of +filesystem. +.IP \(bu 2 +\fIused\fP \-\- sum of used space of the above, i.e. file extents, metadata blocks +.UNINDENT +.sp +\fIGlobalReserve\fP is an artificial and internal emergency space. It is used e.g. +when the filesystem is full. Its \fItotal\fP size is dynamic based on the +filesystem size, usually not larger than 512MiB, \fIused\fP may fluctuate. +.sp +The GlobalReserve is a portion of Metadata. In case the filesystem metadata is +exhausted, \fIGlobalReserve/total + Metadata/used = Metadata/total\fP\&. Otherwise +there appears to be some unused space of Metadata. +.sp +\fBOptions\fP +.INDENT 7.0 +.TP +.B \-b|\-\-raw +raw numbers in bytes, without the \fIB\fP suffix +.TP +.B \-h|\-\-human\-readable +print human friendly numbers, base 1024, this is the default +.UNINDENT +.INDENT 7.0 +.TP +.B \-H +print human friendly numbers, base 1000 +.TP +.B \-\-iec +select the 1024 base for the following options, according to the IEC standard +.TP +.B \-\-si +select the 1000 base for the following options, according to the SI standard +.UNINDENT +.INDENT 7.0 +.TP +.B \-k|\-\-kbytes +show sizes in KiB, or kB with \-\-si +.TP +.B \-m|\-\-mbytes +show sizes in MiB, or MB with \-\-si +.TP +.B \-g|\-\-gbytes +show sizes in GiB, or GB with \-\-si +.TP +.B \-t|\-\-tbytes +show sizes in TiB, or TB with \-\-si +.UNINDENT +.sp +If conflicting options are passed, the last one takes precedence. +.TP +.B defragment [options] <file>|<dir> [<file>|<dir>...] +Defragment file data on a mounted filesystem. Requires kernel 2.6.33 and newer. +.sp +If \fI\-r\fP is passed, files in dir will be defragmented recursively (not +descending to subvolumes, mount points and directory symlinks). +The start position and the number of bytes to defragment can be specified by +start and length using \fI\-s\fP and \fI\-l\fP options below. +Extents bigger than value given by \fI\-t\fP will be skipped, otherwise this value +is used as a target extent size, but is only advisory and may not be reached +if the free space is too fragmented. +Use 0 to take the kernel default, which is 256KiB but may change in the future. +You can also turn on compression in defragment operations. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Defragmenting with Linux kernel versions < 3.9 or ≥ 3.14\-rc2 as well as +with Linux stable kernel versions ≥ 3.10.31, ≥ 3.12.12 or ≥ 3.13.4 will break up +the reflinks of COW data (for example files copied with \fBcp \-\-reflink\fP, +snapshots or de\-duplicated data). +This may cause considerable increase of space usage depending on the broken up +reflinks. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Directory arguments without \fI\-r\fP do not defragment files recursively but will +defragment certain internal trees (extent tree and the subvolume tree). This has been +confusing and could be removed in the future. +.UNINDENT +.UNINDENT +.sp +For \fIstart\fP, \fIlen\fP, \fIsize\fP it is possible to append +units designator: \fIK\fP, \fIM\fP, \fIG\fP, \fIT\fP, \fIP\fP, or \fIE\fP, which represent +KiB, MiB, GiB, TiB, PiB, or EiB, respectively (case does not matter). +.sp +\fBOptions\fP +.INDENT 7.0 +.TP +.B \-c[<algo>] +compress file contents while defragmenting. Optional argument selects the compression +algorithm, \fIzlib\fP (default), \fIlzo\fP or \fIzstd\fP\&. Currently it\(aqs not possible to select no +compression. See also section \fIEXAMPLES\fP\&. +.UNINDENT +.INDENT 7.0 +.TP +.B \-r +defragment files recursively in given directories, does not descend to +subvolumes or mount points +.TP +.B \-f +flush data for each file before going to the next file. +.sp +This will limit the amount of dirty data to current file, otherwise the amount +accumulates from several files and will increase system load. This can also lead +to ENOSPC if there\(aqs too much dirty data to write and it\(aqs not possible to make +the reservations for the new data (i.e. how the COW design works). +.UNINDENT +.INDENT 7.0 +.TP +.B \-s <start>[kKmMgGtTpPeE] +defragmentation will start from the given offset, default is beginning of a file +.TP +.B \-l <len>[kKmMgGtTpPeE] +defragment only up to \fIlen\fP bytes, default is the file size +.TP +.B \-t <size>[kKmMgGtTpPeE] +target extent size, do not touch extents bigger than \fIsize\fP, default: 32MiB +.sp +The value is only advisory and the final size of the extents may differ, +depending on the state of the free space and fragmentation or other internal +logic. Reasonable values are from tens to hundreds of megabytes. +.UNINDENT +.INDENT 7.0 +.TP +.B \-v +(deprecated) alias for global \fI\-v\fP option +.UNINDENT +.TP +.B du [options] <path> [<path>..] +Calculate disk usage of the target files using FIEMAP. For individual +files, it will report a count of total bytes, and exclusive (not +shared) bytes. We also calculate a \(aqset shared\(aq value which is +described below. +.sp +Each argument to \fBbtrfs filesystem du\fP will have a \fIset shared\fP value +calculated for it. We define each \fIset\fP as those files found by a +recursive search of an argument (recursion descends to subvolumes but not +mount points). The \fIset shared\fP value then is a sum of all shared space +referenced by the set. +.sp +\fIset shared\fP takes into account overlapping shared extents, hence it +isn\(aqt as simple as adding up shared extents. +.sp +\fBOptions\fP +.INDENT 7.0 +.TP +.B \-s|\-\-summarize +display only a total for each argument +.UNINDENT +.INDENT 7.0 +.TP +.B \-\-raw +raw numbers in bytes, without the \fIB\fP suffix. +.TP +.B \-\-human\-readable +print human friendly numbers, base 1024, this is the default +.TP +.B \-\-iec +select the 1024 base for the following options, according to the IEC standard. +.TP +.B \-\-si +select the 1000 base for the following options, according to the SI standard. +.TP +.B \-\-kbytes +show sizes in KiB, or kB with \-\-si. +.TP +.B \-\-mbytes +show sizes in MiB, or MB with \-\-si. +.TP +.B \-\-gbytes +show sizes in GiB, or GB with \-\-si. +.TP +.B \-\-tbytes +show sizes in TiB, or TB with \-\-si. +.UNINDENT +.TP +.B label [<device>|<mountpoint>] [<newlabel>] +Show or update the label of a filesystem. This works on a mounted filesystem or +a filesystem image. +.sp +The \fInewlabel\fP argument is optional. Current label is printed if the argument +is omitted. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +The maximum allowable length shall be less than 256 chars and must not contain +a newline. The trailing newline is stripped automatically. +.UNINDENT +.UNINDENT +.TP +.B mkswapfile [\-s size] file +Create a new file that\(aqs suitable and formatted as a swapfile. Default +size is 2GiB, fixed page size 4KiB, minimum size is 40KiB. +.sp +A swapfile must be created in a specific way: NOCOW and preallocated. +Subvolume containing a swapfile cannot be snapshotted and blocks of an +activated swapfile cannot be balanced. +.sp +Swapfile creation can be achieved by standalone commands too. Activation +needs to be done by command \fBswapon(8)\fP\&. See also command \fBbtrfs +inspect\-internal map\-swapfile\fP and the \fI\%Swapfile feature\fP description. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +The command is a simplified version of \(aqmkswap\(aq, if you want to set +label, page size, or other parameters please use \(aqmkswap\(aq proper. +.UNINDENT +.UNINDENT +.sp +\fBOptions\fP +.INDENT 7.0 +.TP +.B \-s|\-\-size SIZE +Create swapfile of a given size SIZE (accepting k/m/g/e/p +suffix). +.TP +.B \-U|\-\-uuid UUID +specify UUID to use, or a special value: clear (all zeros), random, +time (time\-based random) +.UNINDENT +.TP +.B resize [options] [<devid>:][+/\-]<size>[kKmMgGtTpPeE]|[<devid>:]max <path> +Resize a mounted filesystem identified by \fIpath\fP\&. A particular device +can be resized by specifying a \fIdevid\fP\&. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +If \fIpath\fP is a file containing a BTRFS image then resize does not work +as expected and does not resize the image. This would resize the underlying +filesystem instead. +.UNINDENT +.UNINDENT +.sp +The \fIdevid\fP can be found in the output of \fBbtrfs filesystem show\fP and +defaults to 1 if not specified. +The \fIsize\fP parameter specifies the new size of the filesystem. +If the prefix \fI+\fP or \fI\-\fP is present the size is increased or decreased +by the quantity \fIsize\fP\&. +If no units are specified, bytes are assumed for \fIsize\fP\&. +Optionally, the size parameter may be suffixed by one of the following +unit designators: \fIK\fP, \fIM\fP, \fIG\fP, \fIT\fP, \fIP\fP, or \fIE\fP, which represent +KiB, MiB, GiB, TiB, PiB, or EiB, respectively (case does not matter). +.sp +If \fImax\fP is passed, the filesystem will occupy all available space on the +device respecting \fIdevid\fP (remember, devid 1 by default). +.sp +The resize command does not manipulate the size of underlying +partition. If you wish to enlarge/reduce a filesystem, you must make sure you +can expand the partition before enlarging the filesystem and shrink the +partition after reducing the size of the filesystem. This can done using +\fBfdisk(8)\fP or \fBparted(8)\fP to delete the existing partition and recreate +it with the new desired size. When recreating the partition make sure to use +the same starting partition offset as before. +.sp +Growing is usually instant as it only updates the size. However, shrinking could +take a long time if there are data in the device area that\(aqs beyond the new +end. Relocation of the data takes time. +.sp +See also section \fIEXAMPLES\fP\&. +.sp +\fBOptions\fP +.INDENT 7.0 +.TP +.B \-\-enqueue +wait if there\(aqs another exclusive operation running, otherwise continue +.UNINDENT +.TP +.B show [options] [<path>|<uuid>|<device>|<label>] +Show the btrfs filesystem with some additional info about devices and space +allocation. +.sp +If no option none of \fIpath\fP/\fIuuid\fP/\fIdevice\fP/\fIlabel\fP is passed, information +about all the BTRFS filesystems is shown, both mounted and unmounted. +.sp +\fBOptions\fP +.INDENT 7.0 +.TP +.B \-m|\-\-mounted +probe kernel for mounted BTRFS filesystems +.TP +.B \-d|\-\-all\-devices +scan all devices under \fI/dev\fP, otherwise the devices list is extracted from the +\fI/proc/partitions\fP file. This is a fallback option if there\(aqs no device node +manager (like udev) available in the system. +.UNINDENT +.INDENT 7.0 +.TP +.B \-\-raw +raw numbers in bytes, without the \fIB\fP suffix +.TP +.B \-\-human\-readable +print human friendly numbers, base 1024, this is the default +.TP +.B \-\-iec +select the 1024 base for the following options, according to the IEC standard +.TP +.B \-\-si +select the 1000 base for the following options, according to the SI standard +.TP +.B \-\-kbytes +show sizes in KiB, or kB with \-\-si +.TP +.B \-\-mbytes +show sizes in MiB, or MB with \-\-si +.TP +.B \-\-gbytes +show sizes in GiB, or GB with \-\-si +.TP +.B \-\-tbytes +show sizes in TiB, or TB with \-\-si +.UNINDENT +.TP +.B sync <path> +Force a sync of the filesystem at \fIpath\fP, similar to the \fBsync(1)\fP command. In +addition, it starts cleaning of deleted subvolumes. To wait for the subvolume +deletion to complete use the \fBbtrfs subvolume sync\fP command. +.TP +.B usage [options] <path> [<path>...] +Show detailed information about internal filesystem usage. This is supposed to +replace the \fBbtrfs filesystem df\fP command in the long run. +.sp +The level of detail can differ if the command is run under a regular or the +root user (due to use of restricted ioctl). For both there\(aqs a summary section +with information about space usage: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ btrfs filesystem usage /path +WARNING: cannot read detailed chunk info, RAID5/6 numbers will be incorrect, run as root +Overall: + Device size: 1.82TiB + Device allocated: 1.17TiB + Device unallocated: 669.99GiB + Device missing: 0.00B + Device slack: 1.00GiB + Used: 1.14TiB + Free (estimated): 692.57GiB (min: 692.57GiB) + Free (statfs, df) 692.57GiB + Data ratio: 1.00 + Metadata ratio: 1.00 + Global reserve: 512.00MiB (used: 0.00B) + Multiple profiles: no +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 7.0 +.IP \(bu 2 +\fIDevice size\fP \-\- sum of raw device capacity available to the +filesystem, note that this may not be the same as the total device +size (the difference is accounted as slack) +.IP \(bu 2 +\fIDevice allocated\fP \-\- sum of total space allocated for +data/metadata/system profiles, this also accounts space reserved but +not yet used for extents +.IP \(bu 2 +\fIDevice unallocated\fP \-\- the remaining unallocated space for future +allocations (difference of the above two numbers) +.IP \(bu 2 +\fIDevice missing\fP \-\- sum of capacity of all missing devices +.IP \(bu 2 +\fIDevice slack\fP \-\- sum of slack space on all devices (difference +between entire device size and the space occupied by filesystem) +.IP \(bu 2 +\fIUsed\fP \-\- sum of the used space of data/metadata/system profiles, not +including the reserved space +.IP \(bu 2 +\fIFree (estimated)\fP \-\- approximate size of the remaining free space +usable for data, including currently allocated space and estimating +the usage of the unallocated space based on the block group profiles, +the \fImin\fP is the lower bound of the estimate in case multiple +profiles are present +.IP \(bu 2 +\fIFree (statfs, df)\fP \-\- the amount of space available for data as +reported by the \fBstatfs\fP syscall, also returned as \fIAvail\fP in the +output of \fBdf\fP\&. The value is calculated in a different way and may +not match the estimate in some cases (e.g. multiple profiles). +.IP \(bu 2 +\fIData ratio\fP \-\- ratio of total space for data including redundancy or +parity to the effectively usable data space, e.g. single is 1.0, RAID1 +is 2.0 and for RAID5/6 it depends on the number of devices +.IP \(bu 2 +\fIMetadata ratio\fP \-\- ditto, for metadata +.IP \(bu 2 +\fIGlobal reserve\fP \-\- portion of metadata currently used for global +block reserve, used for emergency purposes (like deletion on a full +filesystem) +.IP \(bu 2 +\fIMultiple profiles\fP \-\- what block group types (data, metadata) have +more than one profile (single, raid1, ...), see \fI\%btrfs(5)\fP section +\fIFILESYSTEMS WITH MULTIPLE BLOCK GROUP PROFILES\fP\&. +.UNINDENT +.sp +And on a zoned filesystem there are two more lines in the \fIDevice\fP section: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +Device zone unusable: 5.13GiB +Device zone size: 256.00MiB +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 7.0 +.IP \(bu 2 +\fIDevice zone unusable\fP \-\- sum of of space that\(aqs been used in the +past but now is not due to COW and not referenced anymore, the chunks +have to be reclaimed and zones reset to make it usable again +.IP \(bu 2 +\fIDevice zone size\fP \-\- the reported zone size of the host\-managed +device, same for all devices +.UNINDENT +.sp +The root user will also see stats broken down by block group types: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +Data,single: Size:1.15TiB, Used:1.13TiB (98.26%) + /dev/sdb 1.15TiB + +Metadata,single: Size:12.00GiB, Used:6.45GiB (53.75%) + /dev/sdb 12.00GiB + +System,single: Size:32.00MiB, Used:144.00KiB (0.44%) + /dev/sdb 32.00MiB + +Unallocated: + /dev/sdb 669.99GiB +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fIData\fP is block group type, \fIsingle\fP is block group profile, \fISize\fP is total +size occupied by this type, \fIUsed\fP is the actually used space, the percent is +ratio of \fIUsed/Size\fP\&. The \fIUnallocated\fP is remaining space. +.sp +\fBOptions\fP +.INDENT 7.0 +.TP +.B \-b|\-\-raw +raw numbers in bytes, without the \fIB\fP suffix +.TP +.B \-h|\-\-human\-readable +print human friendly numbers, base 1024, this is the default +.UNINDENT +.INDENT 7.0 +.TP +.B \-H +print human friendly numbers, base 1000 +.TP +.B \-\-iec +select the 1024 base for the following options, according to the IEC standard +.TP +.B \-\-si +select the 1000 base for the following options, according to the SI standard +.UNINDENT +.INDENT 7.0 +.TP +.B \-k|\-\-kbytes +show sizes in KiB, or kB with \-\-si +.TP +.B \-m|\-\-mbytes +show sizes in MiB, or MB with \-\-si +.TP +.B \-g|\-\-gbytes +show sizes in GiB, or GB with \-\-si +.TP +.B \-t|\-\-tbytes +show sizes in TiB, or TB with \-\-si +.UNINDENT +.INDENT 7.0 +.TP +.B \-T +show data in tabular format +.UNINDENT +.sp +If conflicting options are passed, the last one takes precedence. +.UNINDENT +.SH EXAMPLES +.sp +\fB$ btrfs filesystem defrag \-v \-r dir/\fP +.sp +Recursively defragment files under \fIdir/\fP, print files as they are processed. +The file names will be printed in batches, similarly the amount of data triggered +by defragmentation will be proportional to last N printed files. The system dirty +memory throttling will slow down the defragmentation but there can still be a lot +of IO load and the system may stall for a moment. +.sp +\fB$ btrfs filesystem defrag \-v \-r \-f dir/\fP +.sp +Recursively defragment files under \fIdir/\fP, be verbose and wait until all blocks +are flushed before processing next file. You can note slower progress of the +output and lower IO load (proportional to currently defragmented file). +.sp +\fB$ btrfs filesystem defrag \-v \-r \-f \-clzo dir/\fP +.sp +Recursively defragment files under \fIdir/\fP, be verbose, wait until all blocks are +flushed and force file compression. +.sp +\fB$ btrfs filesystem defrag \-v \-r \-t 64M dir/\fP +.sp +Recursively defragment files under \fIdir/\fP, be verbose and try to merge extents +to be about 64MiB. As stated above, the success rate depends on actual free +space fragmentation and the final result is not guaranteed to meet the target +even if run repeatedly. +.sp +\fB$ btrfs filesystem resize \-1G /path\fP +.sp +\fB$ btrfs filesystem resize 1:\-1G /path\fP +.sp +Shrink size of the filesystem\(aqs device id 1 by 1GiB. The first syntax expects a +device with id 1 to exist, otherwise fails. The second is equivalent and more +explicit. For a single\-device filesystem it\(aqs typically not necessary to +specify the devid though. +.sp +\fB$ btrfs filesystem resize max /path\fP +.sp +\fB$ btrfs filesystem resize 1:max /path\fP +.sp +Let\(aqs assume that devid 1 exists and the filesystem does not occupy the whole +block device, e.g. it has been enlarged and we want to grow the filesystem. By +simply using \fImax\fP as size we will achieve that. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +There are two ways to minimize the filesystem on a given device. The +\fBbtrfs inspect\-internal min\-dev\-size\fP command, or iteratively shrink in steps. +.UNINDENT +.UNINDENT +.SH EXIT STATUS +.sp +\fBbtrfs filesystem\fP returns a zero exit status if it succeeds. Non zero is +returned in case of failure. +.SH AVAILABILITY +.sp +\fBbtrfs\fP is part of btrfs\-progs. Please refer to the documentation at +\fI\%https://btrfs.readthedocs.io\fP or wiki \fI\%http://btrfs.wiki.kernel.org\fP for further +information. +.SH SEE ALSO +.sp +\fI\%btrfs\-subvolume(8)\fP, +\fI\%mkfs.btrfs(8)\fP +.\" Generated by docutils manpage writer. +. |