1BTRFS-QUOTA(8)                       BTRFS                      BTRFS-QUOTA(8)
2
3
4

NAME

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

SYNOPSIS

9       btrfs quota <subcommand> <args>
10

DESCRIPTION

12       The  commands under btrfs quota are used to affect the global status of
13       quotas of a btrfs filesystem. The quota groups (qgroups) are managed by
14       the subcommand btrfs-qgroup(8).
15
16       NOTE:
17          Qgroups  are different than the traditional user quotas and designed
18          to track shared and exclusive data per-subvolume.  Please  refer  to
19          the  section  HIERARCHICAL  QUOTA  GROUP CONCEPTS for a detailed de‐
20          scription.
21
22   PERFORMANCE IMPLICATIONS
23       When quotas are activated, they affect  all  extent  processing,  which
24       takes  a  performance hit. Activation of qgroups is not recommended un‐
25       less the user intends to actually use them.
26
27   STABILITY STATUS
28       The qgroup implementation has turned out to be quite  difficult  as  it
29       affects  the  core  of  the filesystem operation. Qgroup users have hit
30       various corner cases over time, such as incorrect accounting or  system
31       instability.  The situation is gradually improving and issues found and
32       fixed.
33

HIERARCHICAL QUOTA GROUP CONCEPTS

35       The concept of quota has a long-standing tradition in the  Unix  world.
36       Ever since computers allow multiple users to work simultaneously in one
37       filesystem, there is the need to prevent one user from using up the en‐
38       tire  space.  Every user should get his fair share of the available re‐
39       sources.
40
41       In case of files, the solution is quite straightforward.  Each file has
42       an  owner recorded along with it, and it has a size.  Traditional quota
43       just restricts the total size of all files that are owned  by  a  user.
44       The  concept is quite flexible: if a user hits his quota limit, the ad‐
45       ministrator can raise it on the fly.
46
47       On the other hand, the traditional approach has only a poor solution to
48       restrict directories.  At installation time, the harddisk can be parti‐
49       tioned so that every directory (e.g. /usr, /var/,  ...)  that  needs  a
50       limit gets its own partition.  The obvious problem is that those limits
51       cannot be changed without a reinstallation.  The btrfs  subvolume  fea‐
52       ture  builds  a  bridge.   Subvolumes correspond in many ways to parti‐
53       tions, as every subvolume looks like its own filesystem.  With  subvol‐
54       ume  quota, it is now possible to restrict each subvolume like a parti‐
55       tion, but keep the flexibility of quota.  The space for each  subvolume
56       can be expanded or restricted on the fly.
57
58       As  subvolumes are the basis for snapshots, interesting questions arise
59       as to how to account used space in the presence of snapshots.   If  you
60       have  a file shared between a subvolume and a snapshot, whom to account
61       the file to? The creator? Both? What if the file gets modified  in  the
62       snapshot,  should only these changes be accounted to it? But wait, both
63       the snapshot and the subvolume belong to the same user  home.   I  just
64       want to limit the total space used by both! But somebody else might not
65       want to charge the snapshots to the users.
66
67       Btrfs subvolume quota solves these problems by  introducing  groups  of
68       subvolumes and let the user put limits on them.  It is even possible to
69       have groups of groups.  In the following, we refer to them as qgroups.
70
71       Each qgroup primarily tracks two numbers, the amount  of  total  refer‐
72       enced space and the amount of exclusively referenced space.
73
74       referenced
75              space  is the amount of data that can be reached from any of the
76              subvolumes contained in the qgroup, while
77
78       exclusive
79              is the amount of data where all references to this data  can  be
80              reached from within this qgroup.
81
82   Subvolume quota groups
83       The  basic  notion  of  the Subvolume Quota feature is the quota group,
84       short qgroup.  Qgroups are notated as level/id, e.g.  the qgroup 3/2 is
85       a  qgroup  of  level  3.  For level 0, the leading '0/' can be omitted.
86       Qgroups of level 0 get created automatically when a  subvolume/snapshot
87       gets  created.   The ID of the qgroup corresponds to the ID of the sub‐
88       volume, so 0/5 is the qgroup for the root  subvolume.   For  the  btrfs
89       qgroup  command,  the path to the subvolume can also be used instead of
90       0/ID.  For all higher levels, the ID can be chosen freely.
91
92       Each qgroup can contain a set of lower level qgroups, thus  creating  a
93       hierarchy of qgroups. Figure 1 shows an example qgroup tree.
94
95                                    +---+
96                                    |2/1|
97                                    +---+
98                                   /     \
99                             +---+/       \+---+
100                             |1/1|         |1/2|
101                             +---+         +---+
102                            /     \       /     \
103                      +---+/       \+---+/       \+---+
104          qgroups     |0/1|         |0/2|         |0/3|
105                      +-+-+         +---+         +---+
106                        |          /     \       /     \
107                        |         /       \     /       \
108                        |        /         \   /         \
109          extents       1       2            3            4
110
111          Figure 1: Sample qgroup hierarchy
112
113       At  the  bottom, some extents are depicted showing which qgroups refer‐
114       ence which extents.  It is important to understand the notion of refer‐
115       enced  vs  exclusive.   In the example, qgroup 0/2 references extents 2
116       and 3, while 1/2 references extents 2-4, 2/1 references all extents.
117
118       On the other hand, extent 1 is exclusive to 0/1, extent 2 is  exclusive
119       to 0/2, while extent 3 is neither exclusive to 0/2 nor to 0/3.  But be‐
120       cause both references can be reached from 1/2, extent 3 is exclusive to
121       1/2.  All extents are exclusive to 2/1.
122
123       So  exclusive  does not mean there is no other way to reach the extent,
124       but it does mean that if you  delete  all  subvolumes  contained  in  a
125       qgroup, the extent will get deleted.
126
127       Exclusive  of  a  qgroup  conveys the useful information how much space
128       will be freed in case all subvolumes of the qgroup get deleted.
129
130       All data extents are accounted this way.  Metadata that  belongs  to  a
131       specific  subvolume  (i.e.   its  filesystem  tree)  is also accounted.
132       Checksums and extent allocation information are not accounted.
133
134       In turn, the referenced count of a qgroup can be limited.   All  writes
135       beyond this limit will lead to a 'Quota Exceeded' error.
136
137   Inheritance
138       Things  get a bit more complicated when new subvolumes or snapshots are
139       created.  The case of (empty) subvolumes is still  quite  easy.   If  a
140       subvolume  should be part of a qgroup, it has to be added to the qgroup
141       at creation time.  To add it at a later time, it would be necessary  to
142       at least rescan the full subvolume for a proper accounting.
143
144       Creation  of a snapshot is the hard case.  Obviously, the snapshot will
145       reference the exact amount of space as its source, and both source  and
146       destination  now  have an exclusive count of 0 (the filesystem nodesize
147       to be precise, as the roots of the trees are  not  shared).   But  what
148       about  qgroups of higher levels? If the qgroup contains both the source
149       and the destination, nothing changes.  If the qgroup contains only  the
150       source, it might lose some exclusive.
151
152       But  how  much?  The  tempting answer is, subtract all exclusive of the
153       source from the qgroup, but that is wrong,  or  at  least  not  enough.
154       There  could have been an extent that is referenced from the source and
155       another subvolume from that qgroup.  This extent would have been exclu‐
156       sive to the qgroup, but not to the source subvolume.  With the creation
157       of the snapshot, the qgroup would also lose this extent from its exclu‐
158       sive set.
159
160       So  how  can  this  problem be solved? In the instant the snapshot gets
161       created, we already have to know the correct exclusive count.  We  need
162       to  have  a second qgroup that contains all the subvolumes as the first
163       qgroup, except the subvolume we want to snapshot.  The moment we create
164       the  snapshot,  the  exclusive count from the second qgroup needs to be
165       copied to the first qgroup, as it represents the  correct  value.   The
166       second  qgroup is called a tracking qgroup.  It is only there in case a
167       snapshot is needed.
168
169   Use cases
170       Below are some use cases that do not mean to be extensive. You can find
171       your own way how to integrate qgroups.
172
173   Single-user machine
174       Replacement for partitions
175
176       The  simplest use case is to use qgroups as simple replacement for par‐
177       titions.  Btrfs takes the disk as a whole, and /, /usr, /var, etc.  are
178       created  as subvolumes.  As each subvolume gets it own qgroup automati‐
179       cally, they can simply be restricted.  No hierarchy is needed for that.
180
181       Track usage of snapshots
182
183       When a snapshot is taken, a qgroup for it will automatically be created
184       with  the  correct  values.   'Referenced' will show how much is in it,
185       possibly shared with other subvolumes.  'Exclusive' will be the  amount
186       of space that gets freed when the subvolume is deleted.
187
188   Multi-user machine
189       Restricting homes
190
191       When  you have several users on a machine, with home directories proba‐
192       bly under /home, you might want to restrict /home as a whole, while re‐
193       stricting  every  user  to an individual limit as well.  This is easily
194       accomplished by creating a qgroup for /home , e.g. 1/1,  and  assigning
195       all  user  subvolumes to it.  Restricting this qgroup will limit /home,
196       while every user subvolume can get its own (lower) limit.
197
198       Accounting snapshots to the user
199
200       Let's say the user is allowed to create snapshots via  some  mechanism.
201       It  would  only  be  fair to account space used by the snapshots to the
202       user.  This does not mean the user doubles his  usage  as  soon  as  he
203       takes  a  snapshot.   Of course, files that are present in his home and
204       the snapshot should only be accounted once.  This can  be  accomplished
205       by creating a qgroup for each user, say '1/UID'.  The user home and all
206       snapshots are assigned to this qgroup.  Limiting  it  will  extend  the
207       limit  to all snapshots, counting files only once.  To limit /home as a
208       whole, a higher level group 2/1 replacing 1/1 from the previous example
209       is needed, with all user qgroups assigned to it.
210
211       Do not account snapshots
212
213       On  the  other  hand, when the snapshots get created automatically, the
214       user has no chance to control them, so the space used  by  them  should
215       not  be accounted to him.  This is already the case when creating snap‐
216       shots in the example from the previous section.
217
218       Snapshots for backup purposes
219
220       This scenario is a mixture of the previous two.  The  user  can  create
221       snapshots,  but some snapshots for backup purposes are being created by
222       the system.  The user's snapshots should be accounted to the user,  not
223       the  system.  The solution is similar to the one from section 'Account‐
224       ing snapshots to the user', but  do  not  assign  system  snapshots  to
225       user's qgroup.
226

SUBCOMMAND

228       disable <path>
229              Disable subvolume quota support for a filesystem.
230
231       enable <path>
232              Enable subvolume quota support for a filesystem.
233
234       rescan [options] <path>
235              Trash  all  qgroup  numbers and scan the metadata again with the
236              current config.
237
238              Options
239
240              -s|--status
241                     show status of a running rescan operation.
242
243              -w|--wait
244                     start rescan and wait for it to finish (can be already in
245                     progress)
246
247              -W|--wait-norescan
248                     wait for rescan to finish without starting it
249

EXIT STATUS

251       btrfs  quota returns a zero exit status if it succeeds. Non zero is re‐
252       turned in case of failure.
253

AVAILABILITY

255       btrfs is part of btrfs-progs.  Please refer  to  the  documentation  at
256       https://btrfs.readthedocs.io  or  wiki http://btrfs.wiki.kernel.org for
257       further information.
258

SEE ALSO

260       btrfs-qgroup(8), btrfs-subvolume(8), mkfs.btrfs(8)
261
262
263
264
2656.1.3                            Jan 25, 2023                   BTRFS-QUOTA(8)
Impressum