1BTRFS-QUOTA(8)                   Btrfs Manual                   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
20           description.
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
25       unless 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
38       entire space. Every user should get his fair share of the available
39       resources.
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
45       administrator 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
49       partitioned so that every directory (eg. /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 feature
52       builds a bridge. Subvolumes correspond in many ways to partitions, as
53       every subvolume looks like its own filesystem. With subvolume quota, it
54       is now possible to restrict each subvolume like a partition, but keep
55       the flexibility of quota. The space for each subvolume can be expanded
56       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
72       referenced 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, eg. the qgroup 3/2 is a
85       qgroup of level 3. For level 0, the leading 0/ can be omitted. Qgroups
86       of level 0 get created automatically when a subvolume/snapshot gets
87       created. The ID of the qgroup corresponds to the ID of the subvolume,
88       so 0/5 is the qgroup for the root subvolume. For the btrfs qgroup
89       command, the path to the subvolume can also be used instead of 0/ID.
90       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       Figure1: Sample qgroup hierarchy
112
113       At the bottom, some extents are depicted showing which qgroups
114       reference which extents. It is important to understand the notion of
115       referenced vs exclusive. In the example, qgroup 0/2 references extents
116       2 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
120       because both references can be reached from 1/2, extent 3 is exclusive
121       to 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
156       exclusive to the qgroup, but not to the source subvolume. With the
157       creation of the snapshot, the qgroup would also lose this extent from
158       its exclusive 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 usecases 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
177           partitions. Btrfs takes the disk as a whole, and /, /usr, /var,
178           etc. are created as subvolumes. As each subvolume gets it own
179           qgroup automatically, they can simply be restricted. No hierarchy
180           is needed for that.
181
182           Track usage of snapshots
183
184           When a snapshot is taken, a qgroup for it will automatically be
185           created with the correct values. Referenced will show how much is
186           in it, possibly shared with other subvolumes. Exclusive will be the
187           amount of space that gets freed when the subvolume is deleted.
188
189       MULTI-USER MACHINE
190           Restricting homes
191
192           When you have several users on a machine, with home directories
193           probably under /home, you might want to restrict /home as a whole,
194           while restricting every user to an individual limit as well. This
195           is easily accomplished by creating a qgroup for /home , eg. 1/1,
196           and assigning all user subvolumes to it. Restricting this qgroup
197           will limit /home, while every user subvolume can get its own
198           (lower) limit.
199
200           Accounting snapshots to the user
201
202           Let’s say the user is allowed to create snapshots via some
203           mechanism. It would only be fair to account space used by the
204           snapshots to the user. This does not mean the user doubles his
205           usage as soon as he takes a snapshot. Of course, files that are
206           present in his home and the snapshot should only be accounted once.
207           This can be accomplished by creating a qgroup for each user, say
208           1/UID. The user home and all snapshots are assigned to this qgroup.
209           Limiting it will extend the limit to all snapshots, counting files
210           only once. To limit /home as a whole, a higher level group 2/1
211           replacing 1/1 from the previous example is needed, with all user
212           qgroups assigned to it.
213
214           Do not account snapshots
215
216           On the other hand, when the snapshots get created automatically,
217           the user has no chance to control them, so the space used by them
218           should not be accounted to him. This is already the case when
219           creating snapshots in the example from the previous section.
220
221           Snapshots for backup purposes
222
223           This scenario is a mixture of the previous two. The user can create
224           snapshots, but some snapshots for backup purposes are being created
225           by the system. The user’s snapshots should be accounted to the
226           user, not the system. The solution is similar to the one from
227           section Accounting snapshots to the user, but do not assign system
228           snapshots to user’s qgroup.
229

SUBCOMMAND

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

EXIT STATUS

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

AVAILABILITY

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

SEE ALSO

259       mkfs.btrfs(8), btrfs-subvolume(8), btrfs-qgroup(8)
260
261
262
263Btrfs v5.6                        04/05/2020                    BTRFS-QUOTA(8)
Impressum