btrfs-quota(8)


NAME

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

SYNOPSIS

   btrfs quota <subcommand> <args>

DESCRIPTION

   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 exlusive data per-subvolume. Plese
       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

   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 reinstall ation. 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 qgruops.

   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 qouta 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 choosen 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 indiviual 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

   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

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

AVAILABILITY

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

SEE ALSO

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





Opportunity


Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.

Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.





Free Software


Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.


Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.





Free Books


The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.


Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.





Education


Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.


Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.