Manpage/btrfs-quota

From btrfs Wiki
(Difference between revisions)
Jump to: navigation, search
(git 5.4)
(remove content)
 
Line 1: Line 1:
=btrfs-quota(8) manual page=
 
 
{{GeneratedManpage
 
{{GeneratedManpage
 
|name=btrfs-quota}}
 
|name=btrfs-quota}}
 
==NAME==
 
btrfs-quota - control the global quota status of a btrfs filesystem
 
 
==SYNOPSIS==
 
 
<p><b>btrfs quota</b> <em>&lt;subcommand&gt;</em> <em>&lt;args&gt;</em></p>
 
==DESCRIPTION==
 
 
<p>The commands under <b>btrfs quota</b> are used to affect the global status of quotas
 
of a btrfs filesystem. The quota groups (qgroups) are managed by the subcommand
 
<tt>btrfs qgroup</tt>(8).</p>
 
<blockquote><b>Note:</b>
 
Qgroups are different than the traditional user quotas and designed
 
to track shared and exclusive data per-subvolume.  Please refer to the section
 
<em>HIERARCHICAL QUOTA GROUP CONCEPTS</em> for a detailed description.</blockquote>
 
===PERFORMANCE IMPLICATIONS===
 
 
<p>When quotas are activated, they affect all extent processing, which takes a
 
performance hit. Activation of qgroups is not recommended unless the user
 
intends to actually use them.</p>
 
===STABILITY STATUS===
 
 
<p>The qgroup implementation has turned out to be quite difficult as it affects
 
the core of the filesystem operation. Qgroup users have hit various corner cases
 
over time, such as incorrect accounting or system instability. The situation is
 
gradually improving and issues found and fixed.</p>
 
==HIERARCHICAL QUOTA GROUP CONCEPTS==
 
 
<p>The concept of quota has a long-standing tradition in the Unix world.  Ever
 
since computers allow multiple users to work simultaneously in one filesystem,
 
there is the need to prevent one user from using up the entire space.  Every
 
user should get his fair share of the available resources.</p>
 
<p>In case of files, the solution is quite straightforward.  Each file has an
 
<em>owner</em> recorded along with it, and it has a size.  Traditional quota just
 
restricts the total size of all files that are owned by a user.  The concept is
 
quite flexible: if a user hits his quota limit, the administrator can raise it
 
on the fly.</p>
 
<p>On the other hand, the traditional approach has only a poor solution to
 
restrict directories.
 
At installation time, the harddisk can be partitioned so that every directory
 
(eg. /usr, /var/, &#8230;) that needs a limit gets its own partition.  The obvious
 
problem is that those limits cannot be changed without a reinstallation.  The
 
btrfs subvolume feature builds a bridge.  Subvolumes correspond in many ways to
 
partitions, as every subvolume looks like its own filesystem.  With subvolume
 
quota, it is now possible to restrict each subvolume like a partition, but keep
 
the flexibility of quota.  The space for each subvolume can be expanded or
 
restricted on the fly.</p>
 
<p>As subvolumes are the basis for snapshots, interesting questions arise as to
 
how to account used space in the presence of snapshots.  If you have a file
 
shared between a subvolume and a snapshot, whom to account the file to? The
 
creator? Both? What if the file gets modified in the snapshot, should only
 
these changes be accounted to it? But wait, both the snapshot and the subvolume
 
belong to the same user home.  I just want to limit the total space used by
 
both! But somebody else might not want to charge the snapshots to the users.</p>
 
<p>Btrfs subvolume quota solves these problems by introducing groups of subvolumes
 
and let the user put limits on them.  It is even possible to have groups of
 
groups.  In the following, we refer to them as <em>qgroups</em>.</p>
 
<p>Each qgroup primarily tracks two numbers, the amount of total referenced
 
space and the amount of exclusively referenced space.</p>
 
<dl>
 
<dt>
 
referenced
 
<dd>
 
<p>
 
space is the amount of data that can be reached from any of the subvolumes
 
contained in the qgroup, while
 
</p>
 
 
<dt>
 
exclusive
 
<dd>
 
<p>
 
is the amount of data where all references to this data can be reached
 
from within this qgroup.
 
</p>
 
 
</dl>
 
===SUBVOLUME QUOTA GROUPS===
 
 
<p>The basic notion of the Subvolume Quota feature is the quota group, short
 
qgroup.  Qgroups are notated as <em>level/id</em>, eg.  the qgroup 3/2 is a qgroup of
 
level 3. For level 0, the leading <em>0/</em> can be omitted.
 
Qgroups of level 0 get created automatically when a subvolume/snapshot gets
 
created.  The ID of the qgroup corresponds to the ID of the subvolume, so 0/5
 
is the qgroup for the root subvolume.
 
For the <b>btrfs qgroup</b> command, the path to the subvolume can also be used
 
instead of <em>0/ID</em>.  For all higher levels, the ID can be chosen freely.</p>
 
<p>Each qgroup can contain a set of lower level qgroups, thus creating a hierarchy
 
of qgroups. Figure 1 shows an example qgroup tree.</p>
 
<pre>                          +---+
 
                          |2/1|
 
                          +---+
 
                        /    \
 
                  +---+/      \+---+
 
                  |1/1|        |1/2|
 
                  +---+        +---+
 
                  /    \      /    \
 
            +---+/      \+---+/      \+---+
 
qgroups    |0/1|        |0/2|        |0/3|
 
            +-+-+        +---+        +---+
 
              |          /    \      /    \
 
              |        /      \    /      \
 
              |        /        \  /        \
 
extents      1      2            3            4</pre>
 
<p>Figure1: Sample qgroup hierarchy</p>
 
<p>At the bottom, some extents are depicted showing which qgroups reference which
 
extents.  It is important to understand the notion of <em>referenced</em> vs
 
<em>exclusive</em>.  In the example, qgroup 0/2 references extents 2 and 3, while 1/2
 
references extents 2-4, 2/1 references all extents.</p>
 
<p>On the other hand, extent 1 is exclusive to 0/1, extent 2 is exclusive to 0/2,
 
while extent 3 is neither exclusive to 0/2 nor to 0/3.  But because both
 
references can be reached from 1/2, extent 3 is exclusive to 1/2.  All extents
 
are exclusive to 2/1.</p>
 
<p>So exclusive does not mean there is no other way to reach the extent, but it
 
does mean that if you delete all subvolumes contained in a qgroup, the extent
 
will get deleted.</p>
 
<p>Exclusive of a qgroup conveys the useful information how much space will be
 
freed in case all subvolumes of the qgroup get deleted.</p>
 
<p>All data extents are accounted this way.  Metadata that belongs to a specific
 
subvolume (i.e.  its filesystem tree) is also accounted.  Checksums and extent
 
allocation information are not accounted.</p>
 
<p>In turn, the referenced count of a qgroup can be limited.  All writes beyond
 
this limit will lead to a <em>Quota Exceeded</em> error.</p>
 
===INHERITANCE===
 
 
<p>Things get a bit more complicated when new subvolumes or snapshots are created.
 
The case of (empty) subvolumes is still quite easy.  If a subvolume should be
 
part of a qgroup, it has to be added to the qgroup at creation time.  To add it
 
at a later time, it would be necessary to at least rescan the full subvolume
 
for a proper accounting.</p>
 
<p>Creation of a snapshot is the hard case.  Obviously, the snapshot will
 
reference the exact amount of space as its source, and both source and
 
destination now have an exclusive count of 0 (the filesystem nodesize to be
 
precise, as the roots of the trees are not shared).  But what about qgroups of
 
higher levels? If the qgroup contains both the source and the destination,
 
nothing changes.  If the qgroup contains only the source, it might lose some
 
exclusive.</p>
 
<p>But how much? The tempting answer is, subtract all exclusive of the source from
 
the qgroup, but that is wrong, or at least not enough.  There could have been
 
an extent that is referenced from the source and another subvolume from that
 
qgroup.  This extent would have been exclusive to the qgroup, but not to the
 
source subvolume.  With the creation of the snapshot, the qgroup would also
 
lose this extent from its exclusive set.</p>
 
<p>So how can this problem be solved? In the instant the snapshot gets created, we
 
already have to know the correct exclusive count.  We need to have a second
 
qgroup that contains all the subvolumes as the first qgroup, except the
 
subvolume we want to snapshot.  The moment we create the snapshot, the
 
exclusive count from the second qgroup needs to be copied to the first qgroup,
 
as it represents the correct value.  The second qgroup is called a tracking
 
qgroup.  It is only there in case a snapshot is needed.</p>
 
===USE CASES===
 
 
<p>Below are some usecases that do not mean to be extensive. You can find your
 
own way how to integrate qgroups.</p>
 
====SINGLE-USER MACHINE====
 
 
<p><tt>Replacement for partitions</tt></p>
 
<p>The simplest use case is to use qgroups as simple replacement for partitions.
 
Btrfs takes the disk as a whole, and /, /usr, /var, etc. are created as
 
subvolumes.  As each subvolume gets it own qgroup automatically, they can
 
simply be restricted.  No hierarchy is needed for that.</p>
 
<p><tt>Track usage of snapshots</tt></p>
 
<p>When a snapshot is taken, a qgroup for it will automatically be created with
 
the correct values.  <em>Referenced</em> will show how much is in it, possibly shared
 
with other subvolumes.  <em>Exclusive</em> will be the amount of space that gets freed
 
when the subvolume is deleted.</p>
 
====MULTI-USER MACHINE====
 
 
<p><tt>Restricting homes</tt></p>
 
<p>When you have several users on a machine, with home directories probably under
 
/home, you might want to restrict /home as a whole, while restricting every
 
user to an individual limit as well.  This is easily accomplished by creating a
 
qgroup for /home , eg. 1/1, and assigning all user subvolumes to it.
 
Restricting this qgroup will limit /home, while every user subvolume can get
 
its own (lower) limit.</p>
 
<p><tt>Accounting snapshots to the user</tt></p>
 
<p>Let&#8217;s say the user is allowed to create snapshots via some mechanism.  It would
 
only be fair to account space used by the snapshots to the user.  This does not
 
mean the user doubles his usage as soon as he takes a snapshot.  Of course,
 
files that are present in his home and the snapshot should only be accounted
 
once.  This can be accomplished by creating a qgroup for each user, say
 
<em>1/UID</em>.  The user home and all snapshots are assigned to this qgroup.
 
Limiting it will extend the limit to all snapshots, counting files only once.
 
To limit /home as a whole, a higher level group 2/1 replacing 1/1 from the
 
previous example is needed, with all user qgroups assigned to it.</p>
 
<p><tt>Do not account snapshots</tt></p>
 
<p>On the other hand, when the snapshots get created automatically, the user has
 
no chance to control them, so the space used by them should not be accounted to
 
him.  This is already the case when creating snapshots in the example from
 
the previous section.</p>
 
<p><tt>Snapshots for backup purposes</tt></p>
 
<p>This scenario is a mixture of the previous two.  The user can create snapshots,
 
but some snapshots for backup purposes are being created by the system.  The
 
user&#8217;s snapshots should be accounted to the user, not the system.  The solution
 
is similar to the one from section <em>Accounting snapshots to the user</em>, but do
 
not assign system snapshots to user&#8217;s qgroup.</p>
 
==SUBCOMMAND==
 
 
<dl>
 
<dt>
 
<b>disable</b> <em>&lt;path&gt;</em>
 
<dd>
 
<p>
 
Disable subvolume quota support for a filesystem.
 
</p>
 
 
<dt>
 
<b>enable</b> <em>&lt;path&gt;</em>
 
<dd>
 
<p>
 
Enable subvolume quota support for a filesystem.
 
</p>
 
 
<dt>
 
<b>rescan</b> [-s] <em>&lt;path&gt;</em>
 
<dd>
 
<p>
 
Trash all qgroup numbers and scan the metadata again with the current config.
 
</p>
 
<p><tt>Options</tt></p>
 
<dl>
 
<dt>
 
-s
 
<dd>
 
<p>
 
show status of a running rescan operation.
 
</p>
 
 
<dt>
 
-w
 
<dd>
 
<p>
 
wait for rescan operation to finish(can be already in progress).
 
</p>
 
 
</dl>
 
 
</dl>
 
==EXIT STATUS==
 
 
<p><b>btrfs quota</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-qgroup|btrfs-qgroup(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