|
|
| 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><subcommand></em> <em><args></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/, …) 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’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’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’s qgroup.</p>
| |
| − | ==SUBCOMMAND==
| |
| − |
| |
| − | <dl>
| |
| − | <dt>
| |
| − | <b>disable</b> <em><path></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | Disable subvolume quota support for a filesystem.
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | <b>enable</b> <em><path></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | Enable subvolume quota support for a filesystem.
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | <b>rescan</b> [-s] <em><path></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]]
| |
