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