diff options
Diffstat (limited to 'upstream/opensuse-leap-15-6/man8/btrfs-qgroup.8')
| -rw-r--r-- | upstream/opensuse-leap-15-6/man8/btrfs-qgroup.8 | 316 |
1 files changed, 316 insertions, 0 deletions
diff --git a/upstream/opensuse-leap-15-6/man8/btrfs-qgroup.8 b/upstream/opensuse-leap-15-6/man8/btrfs-qgroup.8 new file mode 100644 index 00000000..bae97fe5 --- /dev/null +++ b/upstream/opensuse-leap-15-6/man8/btrfs-qgroup.8 @@ -0,0 +1,316 @@ +.\" 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-QGROUP" "8" "Sep 13, 2023" "6.5.1" "BTRFS" +.SH NAME +btrfs-qgroup \- control the quota group of a btrfs filesystem +.SH SYNOPSIS +.sp +\fBbtrfs qgroup\fP <subcommand> <args> +.SH DESCRIPTION +.sp +\fBbtrfs qgroup\fP is used to control quota group (qgroup) of a btrfs filesystem. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +To use qgroup you need to enable quota first using \fBbtrfs quota enable\fP +command. +.UNINDENT +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +Qgroup is not stable yet and will impact performance in current mainline +kernel (v4.14). +.UNINDENT +.UNINDENT +.SH QGROUP +.sp +Quota groups or qgroup in btrfs make a tree hierarchy, the leaf qgroups are +attached to subvolumes. The size limits are set per qgroup and apply when any +limit is reached in tree that contains a given subvolume. +.sp +The limits are separated between shared and exclusive and reflect the extent +ownership. For example a fresh snapshot shares almost all the blocks with the +original subvolume, new writes to either subvolume will raise towards the +exclusive limit. +.sp +The qgroup identifiers conform to \fIlevel/id\fP where level 0 is reserved to the +qgroups associated with subvolumes. Such qgroups are created automatically. +.sp +The qgroup hierarchy is built by commands \fBcreate\fP and \fBassign\fP\&. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +If the qgroup of a subvolume is destroyed, quota about the subvolume will +not be functional until qgroup \fI0/<subvolume id>\fP is created again. +.UNINDENT +.UNINDENT +.SH SUBCOMMAND +.INDENT 0.0 +.TP +.B assign [options] <src> <dst> <path> +Assign qgroup \fIsrc\fP as the child qgroup of \fIdst\fP in the btrfs filesystem +identified by \fIpath\fP\&. +.sp +\fBOptions\fP +.INDENT 7.0 +.TP +.B \-\-rescan +(default since: 4.19) Automatically schedule quota rescan if the new qgroup +assignment would lead to quota inconsistency. See \fIQUOTA RESCAN\fP for more +information. +.TP +.B \-\-no\-rescan +Explicitly ask not to do a rescan, even if the assignment will make the quotas +inconsistent. This may be useful for repeated calls where the rescan would add +unnecessary overhead. +.UNINDENT +.TP +.B create <qgroupid> <path> +Create a subvolume quota group. +.sp +For the \fI0/<subvolume id>\fP qgroup, a qgroup can be created even before the +subvolume is created. +.TP +.B destroy <qgroupid> <path> +Destroy a qgroup. +.sp +If a qgroup is not isolated, meaning it is a parent or child qgroup, then it +can only be destroyed after the relationship is removed. +.TP +.B clear\-stale <path> +Clear all stale qgroups whose subvolume does not exist anymore, this is the +level 0 qgroup like 0/subvolid. Higher level qgroups are not deleted even +if they don\(aqt have any child qgroups. +.TP +.B limit [options] <size>|none [<qgroupid>] <path> +Limit the size of a qgroup to \fIsize\fP or no limit in the btrfs filesystem +identified by \fIpath\fP\&. +.sp +If \fIqgroupid\fP is not given, qgroup of the subvolume identified by \fIpath\fP +is used if possible. +.sp +\fBOptions\fP +.INDENT 7.0 +.TP +.B \-c +limit amount of data after compression. This is the default, it is currently not +possible to turn off this option. +.TP +.B \-e +limit space exclusively assigned to this qgroup. +.UNINDENT +.TP +.B remove <src> <dst> <path> +Remove the relationship between child qgroup \fIsrc\fP and parent qgroup \fIdst\fP in +the btrfs filesystem identified by \fIpath\fP\&. +.sp +\fBOptions\fP +.INDENT 7.0 +.TP +.B \-\-rescan +(default since: 4.19) Automatically schedule quota rescan if the removed qgroup +relation would lead to quota inconsistency. See \fIQUOTA RESCAN\fP for more +information. +.TP +.B \-\-no\-rescan +Explicitly ask not to do a rescan, even if the removal will make the quotas +inconsistent. This may be useful for repeated calls where the rescan would add +unnecessary overhead. +.UNINDENT +.TP +.B show [options] <path> +Show all qgroups in the btrfs filesystem identified by <path>. +.sp +\fBOptions\fP +.INDENT 7.0 +.TP +.B \-p +print parent qgroup id. +.TP +.B \-c +print child qgroup id. +.TP +.B \-r +print limit of referenced size of qgroup. +.TP +.B \-e +print limit of exclusive size of qgroup. +.TP +.B \-F +list all qgroups which impact the given path(include ancestral qgroups) +.TP +.B \-f +list all qgroups which impact the given path(exclude ancestral qgroups) +.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 +.INDENT 7.0 +.TP +.B \-\-sort=[+/\-]<attr>[,[+/\-]<attr>]... +list qgroups in order of <attr>. +.sp +<attr> can be one or more of qgroupid,rfer,excl,max_rfer,max_excl. +.sp +Prefix \fI+\fP means ascending order and \fI\-\fP means descending order of \fIattr\fP\&. +If no prefix is given, use ascending order by default. +.sp +If multiple \fIattr\fP values are given, use comma to separate. +.UNINDENT +.INDENT 7.0 +.TP +.B \-\-sync +To retrieve information after updating the state of qgroups, +force sync of the filesystem identified by \fIpath\fP before getting information. +.UNINDENT +.UNINDENT +.SH QUOTA RESCAN +.sp +The rescan reads all extent sharing metadata and updates the respective qgroups +accordingly. +.sp +The information consists of bytes owned exclusively (\fIexcl\fP) or shared/referred +to (\fIrfer\fP). There\(aqs no explicit information about which extents are shared or +owned exclusively. This means when qgroup relationship changes, extent owners +change and qgroup numbers are no longer consistent unless we do a full rescan. +.sp +However there are cases where we can avoid a full rescan, if a subvolume whose +\fIrfer\fP number equals its \fIexcl\fP number, which means all bytes are exclusively +owned, then assigning/removing this subvolume only needs to add/subtract \fIrfer\fP +number from its parent qgroup. This can speed up the rescan. +.SH EXAMPLES +.SS Make a parent group that has two quota group children +.sp +Given the following filesystem mounted at \fB/mnt/my\-vault\fP +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +Label: none uuid: 60d2ab3b\-941a\-4f22\-8d1a\-315f329797b2 + Total devices 1 FS bytes used 128.00KiB + devid 1 size 5.00GiB used 536.00MiB path /dev/vdb +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Enable quota and create subvolumes. Check subvolume ids. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ cd /mnt/my\-vault +$ btrfs quota enable . +$ btrfs subvolume create a +$ btrfs subvolume create b +$ btrfs subvolume list . + +ID 261 gen 61 top level 5 path a +ID 262 gen 62 top level 5 path b +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Create qgroup and set limit to 10MiB. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ btrfs qgroup create 1/100 . +$ btrfs qgroup limit 10M 1/100 . +$ btrfs qgroup assign 0/261 1/100 . +$ btrfs qgroup assign 0/262 1/100 . +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +And check qgroups. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ btrfs qgroup show . + +qgroupid rfer excl +\-\-\-\-\-\-\-\- \-\-\-\- \-\-\-\- +0/5 16.00KiB 16.00KiB +0/261 16.00KiB 16.00KiB +0/262 16.00KiB 16.00KiB +1/100 32.00KiB 32.00KiB +.ft P +.fi +.UNINDENT +.UNINDENT +.SH EXIT STATUS +.sp +\fBbtrfs qgroup\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\&. +.SH SEE ALSO +.sp +\fI\%btrfs\-quota(8)\fP, +\fI\%btrfs\-subvolume(8)\fP, +\fI\%mkfs.btrfs(8)\fP +.\" Generated by docutils manpage writer. +. |