Documentation/btrfs-quota.asciidoc

   1 btrfs-quota(8)
   2 ==============
   3
   4 NAME
   5 ----
   6 btrfs-quota - control the global quota status of a btrfs filesystem
   7
   8 SYNOPSIS
   9 --------
  10 *btrfs quota* <subcommand> <args>
  11
  12 DESCRIPTION
  13 -----------
  14 The commands under *btrfs quota* are used to affect the global status of quotas
  15 of a btrfs filesystem. The quota groups (qgroups) are managed by the subcommand
  16 `btrfs qgroup`(8).
  17
  18 NOTE: the qgroups are different than the traditional user quotas and designed
  19 to track shared and exlusive data per-subvolume.
  20
  21 HIERARCHICAL QUOTA GROUP CONCEPTS
  22 ---------------------------------
  23
  24 The concept of quota has a long-standing tradition in the Unix world.  Ever
  25 since computers allow multiple users to work simultaneously in one filesystem,
  26 there is the need to prevent one user from using up the entire space.  Every
  27 user should get his fair share of the available resources.
  28
  29 In case of files, the solution is quite straightforward.  Each file has an
  30 'owner' recorded along with it, and it has a size.  Traditional quota just
  31 restricts the total size of all files that are owned by a user.  The concept is
  32 quite flexible: if a user hits his quota limit, the administrator can raise it
  33 on the fly.
  34
  35 On the other hand, the traditional approach has only a poor solution to
  36 restrict directories.
  37 At installation time, the harddisk can be partitioned so that every directory
  38 (eg. /usr, /var/, ...) that needs a limit gets its own partition.  The obvious
  39 problem is, that those limits cannot be changed without a reinstall ation.  The
  40 btrfs subvolume feature builds a bridge.  Subvolumes correspond in many ways to
  41 partitions, as every subvolume looks like its own filesystem.  With subvolume
  42 quota, it is now possible to restrict each subvolume like a partition, but keep
  43 the flexibility of quota.  The space for each subvolume can be expanded or
  44 restricted on the fly.
  45
  46 As subvolumes are the basis for snapshots, interesting questions arise as to
  47 how to account used space in the presence of snapshots.  If you have a file
  48 shared between a subvolume and a snapshot, whom to account the file to? The
  49 creator? Both? What if the file gets modified in the snapshot, should only
  50 these changes be accounted to it? But wait, both the snapshot and the subvolume
  51 belong to the same user home.  I just want to limit the total space used by
  52 both! But somebody else might not want to charge the snapshots to the users.
  53
  54 Btrfs subvolume quota solves these problems by introducing groups of subvolumes
  55 and let the user put limits on them.  It is even possible to have groups of
  56 groups.  In the following, we refer to them as 'qgruops'.
  57
  58 Each qgroup primarily tracks two numbers, the amount of total referenced
  59 space and the amount of exclusively referenced space.
  60
  61 referenced::
  62 space is the amount of data that can be reached from any of the subvolumes
  63 contained in the qgroup, while
  64 exclusive::
  65 is the amount of data where all references to this data can be reached
  66 from within this qgroup.
  67
  68 SUBVOLUME QUOTA GROUPS
  69 ~~~~~~~~~~~~~~~~~~~~~~
  70
  71 The basic notion of the Subvolume Quota feature is the qouta group, short
  72 qgroup.  Qgroups are notated as 'level/id', eg.  the qgroup 3/2 is a qgroup of
  73 level 3. For level 0, the leading '0/' can be omitted.
  74 Qgroups of level 0 get created automatically when a subvolume/snapshot gets
  75 created.  The ID of the qgroup corresponds to the ID of the subvolume, so 0/5
  76 is the qgroup for the root subvolume.
  77 For the *btrfs qgroup* command, the path to the subvolume can also be used
  78 instead of '0/ID'.  For all higher levels, the ID can be choosen freely.
  79
  80 Each qgroup can contain a set of lower level qgroups, thus creating a hierarchy
  81 of qgroups. Figure 1 shows an example qgroup tree.
  82
  83 // TODO: insert Figure 1
  84
  85 At the bottom, some extents are depicted showing which qgroups reference which
  86 extents.  It is important to understand the notion of 'referenced' vs
  87 'exclusive'.  In the example, qgroup 0/2 references extents 2 and 3, while 1/2
  88 references extents 2-4, 2/1 references all extents.
  89
  90 On the other hand, extent 1 is exclusive to 0/1, extent 2 is exclusive to 0/2,
  91 while extent 3 is neither exclusive to 0/2 nor to 0/3.  But because both
  92 references can be reached from 1/2, extent 3 is exclusive to 1/2.  All extents
  93 are exclusive to 2/1.
  94
  95 So exclusive does not mean there is no other way to reach the extent, but it
  96 does mean that if you delete all subvolumes contained in a qgroup, the extent
  97 will get deleted.
  98
  99 Exclusive of a qgroup conveys the useful information how much space will be
 100 freed in case all subvolumes of the qgroup get deleted.
 101
 102 All data extents are accounted this way.  Metadata that belongs to a specific
 103 subvolume (i.e.  its filesystem tree) is also accounted.  Checksums and extent
 104 allocation information are not accounted.
 105
 106 In turn, the referenced count of a qgroup can be limited.  All writes beyond
 107 this limit will lead to a 'Quota Exceeded' error.
 108
 109 INHERITANCE
 110 ~~~~~~~~~~~
 111
 112 Things get a bit more complicated when new subvolumes or snapshots are created.
 113 The case of (empty) subvolumes is still quite easy.  If a subvolume should be
 114 part of a qgroup, it has to be added to the qgroup at creation time.  To add it
 115 at a later time, it would be necessary to at least rescan the full subvolume
 116 for a proper accounting.
 117
 118 Creation of a snapshot is the hard case.  Obviously, the snapshot will
 119 reference the exact amount of space as its source, and both source and
 120 destination now have an exclusive count of 0 (the filesystem nodesize to be
 121 precise, as the roots of the trees are not shared).  But what about qgroups of
 122 higher levels? If the qgroup contains both the source and the destination,
 123 nothing changes.  If the qgroup contains only the source, it might lose some
 124 exclusive.
 125
 126 But how much? The tempting answer is, subtract all exclusive of the source from
 127 the qgroup, but that is wrong, or at least not enough.  There could have been
 128 an extent that is referenced from the source and another subvolume from that
 129 qgroup.  This extent would have been exclusive to the qgroup, but not to the
 130 source subvolume.  With the creation of the snapshot, the qgroup would also
 131 lose this extent from its exclusive set.
 132
 133 So how can this problem be solved? In the instant the snapshot gets created, we
 134 already have to know the correct exclusive count.  We need to have a second
 135 qgroup that contains all the subvolumes as the first qgroup, except the
 136 subvolume we want to snapshot.  The moment we create the snapshot, the
 137 exclusive count from the second qgroup needs to be copied to the first qgroup,
 138 as it represents the correct value.  The second qgroup is called a tracking
 139 qgroup.  It is only there in case a snapshot is needed.
 140
 141 USE CASES
 142 ~~~~~~~~~
 143
 144 Below are some usecases that do not mean to be extensive. You can find your
 145 own way how to integrate qgroups.
 146
 147 ==== SINGLE-USER MACHINE ====
 148
 149 `Replacement for partitions`
 150
 151 The simplest use case is to use qgroups as simple replacement for partitions.
 152 Btrfs takes the disk as a whole, and /, /usr, /var etc.  are created as
 153 subvolumes.  As each subvolume gets it own qgroup automatically, they can
 154 simply be restricted.  No hierarchy is needed for that.
 155
 156 `Track usage of snapshots`
 157
 158 When a snapshot is taken, a qgroup for it will automatically be created with
 159 the correct values.  'Referenced' will show how much is in it, possibly shared
 160 with other subvolumes.  'Exclusive' will be the amount of space that gets freed
 161 when the subvolume is deleted.
 162
 163 ==== MULTI-USER MACHINE ====
 164
 165 `Restricting homes`
 166
 167 When you have several users on a machine, with home directories probably under
 168 /home, you might want to restrict /home as a whole, while restricting every
 169 user to an indiviual limit as well.  This is easily accomplished by creating a
 170 qgroup for /home , eg. 1/1, and assigning all user subvolumes to it.
 171 Restricting this qgroup will limit /home, while every user subvolume can get
 172 its own (lower) limit.
 173
 174 `Accounting snapshots to the user`
 175
 176 Let's say the user is allowed to create snapshots via some mechanism.  It would
 177 only be fair to account space used by the snapshots to the user.  This does not
 178 mean the user doubles his usage as soon as he takes a snapshot.  Of course,
 179 files that are present in his home and the snapshot should only be accounted
 180 once.  This can be accomplished by creating a qgroup for each user, say
 181 '1/UID'.  The user home and all snapshots are assigned to this qgroup.
 182 Limiting it will extend the limit to all snapshots, counting files only once.
 183 To limit /home as a whole, a higher level group 2/1 replacing 1/1 from the
 184 previous example is needed, with all user qgroups assigned to it.
 185
 186 `Do not account snapshots`
 187
 188 On the other hand, when the snapshots get created automatically, the user has
 189 no chance to control them, so the space used by them should not be accounted to
 190 him.  This is already the case when creating snapshots in the example from
 191 the previous section.
 192
 193 `Snapshots for backup purposes`
 194
 195 This scenario is a mixture of the previous two.  The user can create snapshots,
 196 but some snapshots for backup purposes are being created by the system.  The
 197 user's snapshots should be accounted to the user, not the system.  The solution
 198 is similar to the one from section 'Accounting snapshots to the user', but do
 199 not assign system snapshots to user's qgroup.
 200
 201 SUBCOMMAND
 202 ----------
 203 *disable* <path>::
 204 Disable subvolume quota support for a filesystem.
 205
 206 *enable* <path>::
 207 Enable subvolume quota support for a filesystem.
 208
 209 *rescan* [-s] <path>::
 210 Trash all qgroup numbers and scan the metadata again with the current config.
 211 +
 212 `Options`
 213 +
 214 -s::::
 215 show status of a running rescan operation.
 216 -w::::
 217 wait for rescan operation to finish(can be already in progress).
 218
 219 EXIT STATUS
 220 -----------
 221 *btrfs quota* returns a zero exit status if it succeeds. Non zero is
 222 returned in case of failure.
 223
 224 AVAILABILITY
 225 ------------
 226 *btrfs* is part of btrfs-progs.
 227 Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
 228 further details.
 229
 230 SEE ALSO
 231 --------
 232 `mkfs.btrfs`(8),
 233 `btrfs-subvolume`(8),
 234 `btrfs-qgroup`(8)