|
|
| 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><subcommand></em> <em><args></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><subvolume id></em></em> is created again.</blockquote>
| |
| − | ==SUBCOMMAND==
| |
| − |
| |
| − | <dl>
| |
| − | <dt>
| |
| − | <b>assign</b> [options] <em><src></em> <em><dst></em> <em><path></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | Assign qgroup <em><src></em> as the child qgroup of <em><dst></em> in the btrfs filesystem
| |
| − | identified by <em><path></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><qgroupid></em> <em><path></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | Create a subvolume quota group.
| |
| − | </p>
| |
| − | <p>For the <em>0/<em><subvolume id></em></em> qgroup, a qgroup can be created even before the
| |
| − | subvolume is created.</p>
| |
| − |
| |
| − | <dt>
| |
| − | <b>destroy</b> <em><qgroupid></em> <em><path></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><size></em>|none [<em><qgroupid></em>] <em><path></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | Limit the size of a qgroup to <em><size></em> or no limit in the btrfs filesystem
| |
| − | identified by <em><path></em>.
| |
| − | </p>
| |
| − | <p>If <em><qgroupid></em> is not given, qgroup of the subvolume identified by <em><path></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><src></em> <em><dst></em> <em><path></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | Remove the relationship between child qgroup <em><src></em> and parent qgroup <em><dst></em> in
| |
| − | the btrfs filesystem identified by <em><path></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><path></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | Show all qgroups in the btrfs filesystem identified by <em><path></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><attr></em>[,[+/-]<em><attr></em>]…
| |
| − | <dd>
| |
| − | <p>
| |
| − | list qgroups in order of <em><attr></em>.
| |
| − | </p>
| |
| − | <p><em><attr></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><attr></em>.
| |
| − | If no prefix is given, use ascending order by default.</p>
| |
| − | <p>If multiple <em><attr></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><path></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’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]]
| |
