Manpage/btrfs-qgroup

From btrfs Wiki
(Difference between revisions)
Jump to: navigation, search
(Update from git, v5.14.2)
(remove content)
 
Line 1: Line 1:
=btrfs-qgroup(8) manual page=
 
 
{{GeneratedManpage
 
{{GeneratedManpage
 
|name=btrfs-qgroup}}
 
|name=btrfs-qgroup}}
 
==NAME==
 
btrfs-qgroup - control the quota group of a btrfs filesystem
 
 
==SYNOPSIS==
 
 
<p><b>btrfs qgroup</b> <em>&lt;subcommand&gt;</em> <em>&lt;args&gt;</em></p>
 
==DESCRIPTION==
 
 
<p><b>btrfs qgroup</b> is used to control quota group (qgroup) of a btrfs filesystem.</p>
 
<blockquote><b>Note:</b>
 
To use qgroup you need to enable quota first using <b>btrfs quota enable</b>
 
command.</blockquote>
 
<blockquote><b>Warning:</b>
 
Qgroup is not stable yet and will impact performance in current mainline
 
kernel (v4.14).</blockquote>
 
==QGROUP==
 
 
<p>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.</p>
 
<p>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.</p>
 
<p>The qgroup identifiers conform to <em>level/id</em> where level 0 is reserved to the
 
qgroups associated with subvolumes. Such qgroups are created automatically.</p>
 
<p>The qgroup hierarchy is built by commands <b>create</b> and <b>assign</b>.</p>
 
<blockquote><b>Note:</b>
 
If the qgroup of a subvolume is destroyed, quota about the subvolume
 
will not be functional until qgroup <em>0/<em>&lt;subvolume id&gt;</em></em> is created again.</blockquote>
 
==SUBCOMMAND==
 
 
<dl>
 
<dt>
 
<b>assign</b> [options] <em>&lt;src&gt;</em> <em>&lt;dst&gt;</em> <em>&lt;path&gt;</em>
 
<dd>
 
<p>
 
Assign qgroup <em>&lt;src&gt;</em> as the child qgroup of <em>&lt;dst&gt;</em> in the btrfs filesystem
 
identified by <em>&lt;path&gt;</em>.
 
</p>
 
<p><tt>Options</tt></p>
 
<dl>
 
<dt>
 
--rescan
 
<dd>
 
<p>
 
(default since: 4.19) Automatically schedule quota rescan if the new qgroup
 
assignment would lead to quota inconsistency. See <em>QUOTA RESCAN</em> for more
 
information.
 
</p>
 
 
<dt>
 
--no-rescan
 
<dd>
 
<p>
 
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.
 
</p>
 
 
</dl>
 
 
<dt>
 
<b>create</b> <em>&lt;qgroupid&gt;</em> <em>&lt;path&gt;</em>
 
<dd>
 
<p>
 
Create a subvolume quota group.
 
</p>
 
<p>For the <em>0/<em>&lt;subvolume id&gt;</em></em> qgroup, a qgroup can be created even before the
 
subvolume is created.</p>
 
 
<dt>
 
<b>destroy</b> <em>&lt;qgroupid&gt;</em> <em>&lt;path&gt;</em>
 
<dd>
 
<p>
 
Destroy a qgroup.
 
</p>
 
<p>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.</p>
 
 
<dt>
 
<b>limit</b> [options] <em>&lt;size&gt;</em>|none [<em>&lt;qgroupid&gt;</em>] <em>&lt;path&gt;</em>
 
<dd>
 
<p>
 
Limit the size of a qgroup to <em>&lt;size&gt;</em> or no limit in the btrfs filesystem
 
identified by <em>&lt;path&gt;</em>.
 
</p>
 
<p>If <em>&lt;qgroupid&gt;</em> is not given, qgroup of the subvolume identified by <em>&lt;path&gt;</em>
 
is used if possible.</p>
 
<p><tt>Options</tt></p>
 
<dl>
 
<dt>
 
-c
 
<dd>
 
<p>
 
limit amount of data after compression. This is the default, it is currently not
 
possible to turn off this option.
 
</p>
 
 
<dt>
 
-e
 
<dd>
 
<p>
 
limit space exclusively assigned to this qgroup.
 
</p>
 
 
</dl>
 
 
<dt>
 
<b>remove</b> <em>&lt;src&gt;</em> <em>&lt;dst&gt;</em> <em>&lt;path&gt;</em>
 
<dd>
 
<p>
 
Remove the relationship between child qgroup <em>&lt;src&gt;</em> and parent qgroup <em>&lt;dst&gt;</em> in
 
the btrfs filesystem identified by <em>&lt;path&gt;</em>.
 
</p>
 
<p><tt>Options</tt></p>
 
<dl>
 
<dt>
 
--rescan
 
<dd>
 
<p>
 
(default since: 4.19) Automatically schedule quota rescan if the removed qgroup
 
relation would lead to quota inconsistency. See <em>QUOTA RESCAN</em> for more
 
information.
 
</p>
 
 
<dt>
 
--no-rescan
 
<dd>
 
<p>
 
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.
 
</p>
 
 
</dl>
 
 
<dt>
 
<b>show</b> [options] <em>&lt;path&gt;</em>
 
<dd>
 
<p>
 
Show all qgroups in the btrfs filesystem identified by <em>&lt;path&gt;</em>.
 
</p>
 
<p><tt>Options</tt></p>
 
<dl>
 
<dt>
 
-p
 
<dd>
 
<p>
 
print parent qgroup id.
 
</p>
 
 
<dt>
 
-c
 
<dd>
 
<p>
 
print child qgroup id.
 
</p>
 
 
<dt>
 
-r
 
<dd>
 
<p>
 
print limit of referenced size of qgroup.
 
</p>
 
 
<dt>
 
-e
 
<dd>
 
<p>
 
print limit of exclusive size of qgroup.
 
</p>
 
 
<dt>
 
-F
 
<dd>
 
<p>
 
list all qgroups which impact the given path(include ancestral qgroups)
 
</p>
 
 
<dt>
 
-f
 
<dd>
 
<p>
 
list all qgroups which impact the given path(exclude ancestral qgroups)
 
</p>
 
 
<dt>
 
--raw
 
<dd>
 
<p>
 
raw numbers in bytes, without the <em>B</em> suffix.
 
</p>
 
 
<dt>
 
--human-readable
 
<dd>
 
<p>
 
print human friendly numbers, base 1024, this is the default
 
</p>
 
 
<dt>
 
--iec
 
<dd>
 
<p>
 
select the 1024 base for the following options, according to the IEC standard.
 
</p>
 
 
<dt>
 
--si
 
<dd>
 
<p>
 
select the 1000 base for the following options, according to the SI standard.
 
</p>
 
 
<dt>
 
--kbytes
 
<dd>
 
<p>
 
show sizes in KiB, or kB with --si.
 
</p>
 
 
<dt>
 
--mbytes
 
<dd>
 
<p>
 
show sizes in MiB, or MB with --si.
 
</p>
 
 
<dt>
 
--gbytes
 
<dd>
 
<p>
 
show sizes in GiB, or GB with --si.
 
</p>
 
 
<dt>
 
--tbytes
 
<dd>
 
<p>
 
show sizes in TiB, or TB with --si.
 
</p>
 
 
<dt>
 
--sort=[+/-]<em>&lt;attr&gt;</em>[,[+/-]<em>&lt;attr&gt;</em>]&#8230;
 
<dd>
 
<p>
 
list qgroups in order of <em>&lt;attr&gt;</em>.
 
</p>
 
<p><em>&lt;attr&gt;</em> can be one or more of qgroupid,rfer,excl,max_rfer,max_excl.</p>
 
<p>Prefix '+' means ascending order and '-' means descending order of <em>&lt;attr&gt;</em>.
 
If no prefix is given, use ascending order by default.</p>
 
<p>If multiple <em>&lt;attr&gt;</em>s is given, use comma to separate.</p>
 
 
<dt>
 
--sync
 
<dd>
 
<p>
 
To retrieve information after updating the state of qgroups,
 
force sync of the filesystem identified by <em>&lt;path&gt;</em> before getting information.
 
</p>
 
 
</dl>
 
 
</dl>
 
==QUOTA RESCAN==
 
 
<p>The rescan reads all extent sharing metadata and updates the respective qgoups
 
accordingly.</p>
 
<p>The information consists of bytes owned exclusively (<em>excl</em>) or shared/referred
 
to (<em>rfer</em>). There&#8217;s 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.</p>
 
<p>However there are cases where we can avoid a full rescan, if a subvolume whose
 
<em>rfer</em> number equals its <em>excl</em> number, which means all bytes are exclusively
 
owned, then assigning/removing this subvolume only needs to add/subtract <em>rfer</em>
 
number from its parent qgroup. This can speed up the rescan.</p>
 
==EXAMPLES==
 
 
<table frame="void" width="100%" cellpadding="4">
 
<tr><td style="border-left: 2px solid silver;">
 
<p>Given the following filesystem mounted at <tt>/mnt/my-vault</tt></p>
 
<pre>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</pre>
 
<p>Enable quota and create subvolumes.  Check subvolume ids.</p>
 
<table border="0" bgcolor="#e8e8e8" width="100%" cellpadding="10"><tr><td><!-- Generator: GNU source-highlight
 
by Lorenzo Bettini
 
http://www.lorenzobettini.it
 
http://www.gnu.org/software/src-highlite -->
 
<pre><tt>$ cd /mnt/my-vault
 
$ btrfs quota <b><font color="#0000FF">enable</font></b> <font color="#990000">.</font>
 
$ btrfs subvolume create a
 
$ btrfs subvolume create b
 
$ btrfs subvolume list <font color="#990000">.</font>
 
 
ID <font color="#993399">261</font> gen <font color="#993399">61</font> top level <font color="#993399">5</font> path a
 
ID <font color="#993399">262</font> gen <font color="#993399">62</font> top level <font color="#993399">5</font> path b</tt></pre></td></tr></table>
 
<p>Create qgroup and set limit to 10MiB.</p>
 
<table border="0" bgcolor="#e8e8e8" width="100%" cellpadding="10"><tr><td><!-- Generator: GNU source-highlight
 
by Lorenzo Bettini
 
http://www.lorenzobettini.it
 
http://www.gnu.org/software/src-highlite -->
 
<pre><tt>$ btrfs qgroup create <font color="#993399">1</font><font color="#990000">/</font><font color="#993399">100</font> <font color="#990000">.</font>
 
$ btrfs qgroup limit 10M <font color="#993399">1</font><font color="#990000">/</font><font color="#993399">100</font> <font color="#990000">.</font>
 
$ btrfs qgroup assign <font color="#993399">0</font><font color="#990000">/</font><font color="#993399">261</font> <font color="#993399">1</font><font color="#990000">/</font><font color="#993399">100</font> <font color="#990000">.</font>
 
$ btrfs qgroup assign <font color="#993399">0</font><font color="#990000">/</font><font color="#993399">262</font> <font color="#993399">1</font><font color="#990000">/</font><font color="#993399">100</font> <font color="#990000">.</font></tt></pre></td></tr></table>
 
<p>And check qgroups.</p>
 
<table border="0" bgcolor="#e8e8e8" width="100%" cellpadding="10"><tr><td><!-- Generator: GNU source-highlight
 
by Lorenzo Bettini
 
http://www.lorenzobettini.it
 
http://www.gnu.org/software/src-highlite -->
 
<pre><tt>$ btrfs qgroup show <font color="#990000">.</font>
 
 
qgroupid        rfer        excl
 
<font color="#993399">0</font><font color="#990000">/</font><font color="#993399">5</font>          <font color="#993399">16</font><font color="#990000">.</font>00KiB    <font color="#993399">16</font><font color="#990000">.</font>00KiB
 
<font color="#993399">0</font><font color="#990000">/</font><font color="#993399">261</font>        <font color="#993399">16</font><font color="#990000">.</font>00KiB    <font color="#993399">16</font><font color="#990000">.</font>00KiB
 
<font color="#993399">0</font><font color="#990000">/</font><font color="#993399">262</font>        <font color="#993399">16</font><font color="#990000">.</font>00KiB    <font color="#993399">16</font><font color="#990000">.</font>00KiB
 
<font color="#993399">1</font><font color="#990000">/</font><font color="#993399">100</font>        <font color="#993399">32</font><font color="#990000">.</font>00KiB    <font color="#993399">32</font><font color="#990000">.</font>00KiB</tt></pre></td></tr></table>
 
</td></tr></table>
 
<p><b>Example 1. </b>Make a parent group that has two quota group children</p>
 
==EXIT STATUS==
 
 
<p><b>btrfs qgroup</b> returns a zero exit status if it succeeds. Non zero is
 
returned in case of failure.</p>
 
==AVAILABILITY==
 
 
<p><b>btrfs</b> is part of btrfs-progs.
 
Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
 
further details.</p>
 
==SEE ALSO==
 
 
<p>[[Manpage/mkfs.btrfs|mkfs.btrfs(8)]],
 
[[Manpage/btrfs-subvolume|btrfs-subvolume(8)]],
 
[[Manpage/btrfs-quota|btrfs-quota(8)]],</p>
 
[[Category:Manpage]]
 

Latest revision as of 12:31, 12 January 2022

Note: manual pages are located at read-the-docs site, please update your links.


Personal tools