NAME | SYNOPSIS | DESCRIPTION | HIERARCHICAL QUOTA GROUP CONCEPTS | SUBCOMMAND | EXIT STATUS | AVAILABILITY | SEE ALSO | COLOPHON

BTRFS-QUOTA(8)                  Btrfs Manual                  BTRFS-QUOTA(8)

NAME         top

       btrfs-quota - control the global quota status of a btrfs filesystem

SYNOPSIS         top

       btrfs quota <subcommand> <args>

DESCRIPTION         top

       The commands under btrfs quota are used to affect the global status
       of quotas of a btrfs filesystem. The quota groups (qgroups) are
       managed by the subcommand btrfs qgroup(8).

           Note
           the qgroups are different than the traditional user quotas and
           designed to track shared and exclusive data per-subvolume. Please
           refer to the section HIERARCHICAL QUOTA GROUP CONCEPTS for a
           detailed description.

   PERFORMANCE IMPLICATIONS
       When the quotas are turned on, they affect all extent processing,
       taking a performance hit. It is not recommended to turn on qgroups
       unless the user intends to actually use them.

   STABILITY STATUS
       The qgroup implementation has turned out to be quite difficult as it
       affects the core of the filesystem operation. The users have hit
       various corner cases over time, eg. wrong accounting or system
       instability. The situation is gradually improving but currently (4.7)
       there are still issues found and fixed.

HIERARCHICAL QUOTA GROUP CONCEPTS         top

       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.

       In case of files, the solution is quite straightforward. Each file
       has an owner 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.

       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.

       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.

       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
       qgroups.

       Each qgroup primarily tracks two numbers, the amount of total
       referenced space and the amount of exclusively referenced space.

       referenced
           space is the amount of data that can be reached from any of the
           subvolumes contained in the qgroup, while

       exclusive
           is the amount of data where all references to this data can be
           reached from within this qgroup.

   SUBVOLUME QUOTA GROUPS
       The basic notion of the Subvolume Quota feature is the quota group,
       short qgroup. Qgroups are notated as level/id, eg. the qgroup 3/2 is
       a qgroup of level 3. For level 0, the leading 0/ 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 btrfs qgroup command, the path to the subvolume can also be
       used instead of 0/ID. For all higher levels, the ID can be chosen
       freely.

       Each qgroup can contain a set of lower level qgroups, thus creating a
       hierarchy of qgroups. Figure 1 shows an example qgroup tree.

       At the bottom, some extents are depicted showing which qgroups
       reference which extents. It is important to understand the notion of
       referenced vs exclusive. In the example, qgroup 0/2 references
       extents 2 and 3, while 1/2 references extents 2-4, 2/1 references all
       extents.

       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.

       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.

       Exclusive of a qgroup conveys the useful information how much space
       will be freed in case all subvolumes of the qgroup get deleted.

       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.

       In turn, the referenced count of a qgroup can be limited. All writes
       beyond this limit will lead to a Quota Exceeded error.

   INHERITANCE
       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.

       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.

       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.

       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.

   USE CASES
       Below are some usecases that do not mean to be extensive. You can
       find your own way how to integrate qgroups.

       SINGLE-USER MACHINE
           Replacement for partitions

           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.

           Track usage of snapshots

           When a snapshot is taken, a qgroup for it will automatically be
           created with the correct values. Referenced will show how much is
           in it, possibly shared with other subvolumes. Exclusive will be
           the amount of space that gets freed when the subvolume is
           deleted.

       MULTI-USER MACHINE
           Restricting homes

           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.

           Accounting snapshots to the user

           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 1/UID. 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.

           Do not account snapshots

           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.

           Snapshots for backup purposes

           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 Accounting snapshots to the user, but do not
           assign system snapshots to user’s qgroup.

SUBCOMMAND         top

       disable <path>
           Disable subvolume quota support for a filesystem.

       enable <path>
           Enable subvolume quota support for a filesystem.

       rescan [-s] <path>
           Trash all qgroup numbers and scan the metadata again with the
           current config.

           Options

           -s
               show status of a running rescan operation.

           -w
               wait for rescan operation to finish(can be already in
               progress).

EXIT STATUS         top

       btrfs quota returns a zero exit status if it succeeds. Non zero is
       returned in case of failure.

AVAILABILITY         top

       btrfs is part of btrfs-progs. Please refer to the btrfs wiki
       http://btrfs.wiki.kernel.org for further details.

SEE ALSO         top

       mkfs.btrfs(8), btrfs-subvolume(8), btrfs-qgroup(8)

COLOPHON         top

       This page is part of the btrfs-progs (btrfs filesystem tools)
       project.  Information about the project can be found at 
       ⟨https://btrfs.wiki.kernel.org/index.php/Btrfs_source_repositories⟩.
       If you have a bug report for this manual page, see 
       ⟨https://btrfs.wiki.kernel.org/index.php/Problem_FAQ#How_do_I_report_bugs_and_issues.3F⟩.
       This page was obtained from the project's upstream Git repository 
       ⟨git://git.kernel.org/pub/scm/linux/kernel/git/kdave/btrfs-progs.git⟩
       on 2017-03-13.  If you discover any rendering problems in this HTML
       version of the page, or you believe there is a better or more up-to-
       date source for the page, or you have corrections or improvements to
       the information in this COLOPHON (which is not part of the original
       manual page), send a mail to man-pages@man7.org

Btrfs v4.6.1                     03/12/2017                   BTRFS-QUOTA(8)