Provided by: btrfs-progs_6.2-1_amd64 bug

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

   STABILITY STATUS
       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.

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  (e.g. /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, e.g.  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.

                                    +---+
                                    |2/1|
                                    +---+
                                   /     \
                             +---+/       \+---+
                             |1/1|         |1/2|
                             +---+         +---+
                            /     \       /     \
                      +---+/       \+---+/       \+---+
          qgroups     |0/1|         |0/2|         |0/3|
                      +-+-+         +---+         +---+
                        |          /     \       /     \
                        |         /       \     /       \
                        |        /         \   /         \
          extents       1       2            3            4

          Figure 1: Sample qgroup hierarchy

       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 use cases 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 , e.g. 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 [options] <path>
              Trash all qgroup numbers and scan the metadata again with the current config.

              Options

              -s|--status
                     show status of a running rescan operation.

              -w|--wait
                     start rescan and wait for it to finish (can be already in progress)

              -W|--wait-norescan
                     wait for rescan to finish without starting it

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   documentation   at
       https://btrfs.readthedocs.io or wiki http://btrfs.wiki.kernel.org for further information.

SEE ALSO

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