Debian Codegraph @

upstream/debian-trixie/man8/btrfs-quota.8

raw
1 .\" Man page generated from reStructuredText.
2 .
3 .
4 .nr rst2man-indent-level 0
5 .
6 .de1 rstReportMargin
7 \\$1 \\n[an-margin]
8 level \\n[rst2man-indent-level]
9 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
10 -
11 \\n[rst2man-indent0]
12 \\n[rst2man-indent1]
13 \\n[rst2man-indent2]
14 ..
15 .de1 INDENT
16 .\" .rstReportMargin pre:
17 . RS \\$1
18 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
19 . nr rst2man-indent-level +1
20 .\" .rstReportMargin post:
21 ..
22 .de UNINDENT
23 . RE
24 .\" indent \\n[an-margin]
25 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
26 .nr rst2man-indent-level -1
27 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
28 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
29 ..
30 .TH "BTRFS-QUOTA" "8" "May 18, 2026" "7.0" "BTRFS"
31 .SH NAME
32 btrfs-quota \- control the global quota status of a btrfs filesystem
33 .SH SYNOPSIS
34 .sp
35 \fBbtrfs quota\fP <subcommand> <args>
36 .SH DESCRIPTION
37 .sp
38 The commands under \fBbtrfs quota\fP are used to affect the global status of quotas
39 of a btrfs filesystem. The quota groups (qgroups) are managed by the subcommand
40 \fI\%btrfs\-qgroup(8)\fP\&.
41 .sp
42 \fBNOTE:\fP
43 .INDENT 0.0
44 .INDENT 3.5
45 Qgroups are different than the traditional user quotas and designed
46 to track shared and exclusive data per\-subvolume. Please refer to the section
47 \fI\%HIERARCHICAL QUOTA GROUP CONCEPTS\fP
48 for a detailed description.
49 .UNINDENT
50 .UNINDENT
51 .SS STABILITY AND PERFORMANCE IMPLICATIONS
52 .sp
53 The qgroup implementation is considered reasonably stable for daily use and has
54 been enabled in various distributions.
55 .sp
56 When quotas are activated, they affect all extent processing, which takes a
57 performance hit. Activation of qgroups is not recommended unless the user
58 intends to actually use them.
59 .SH HIERARCHICAL QUOTA GROUP CONCEPTS
60 .sp
61 The concept of quota has a long\-standing tradition in the Unix world. Ever
62 since computers allow multiple users to work simultaneously in one filesystem,
63 there is the need to prevent one user from using up the entire space. Every
64 user should get his fair share of the available resources.
65 .sp
66 In case of files, the solution is quite straightforward. Each file has an
67 \fIowner\fP recorded along with it, and it has a size. Traditional quota just
68 restricts the total size of all files that are owned by a user. The concept is
69 quite flexible: if a user hits his quota limit, the administrator can raise it
70 on the fly.
71 .sp
72 On the other hand, the traditional approach has only a poor solution to
73 restrict directories.
74 At installation time, the storage device can be partitioned so that every directory
75 (e.g. \fB/usr\fP, \fB/var\fP, ...) that needs a limit gets its own partition. The obvious
76 problem is that those limits cannot be changed without a reinstallation. The
77 btrfs subvolume feature builds a bridge. Subvolumes correspond in many ways to
78 partitions, as every subvolume looks like its own filesystem. With subvolume
79 quota, it is now possible to restrict each subvolume like a partition, but keep
80 the flexibility of quota. The space for each subvolume can be expanded or
81 restricted on the fly.
82 .sp
83 As subvolumes are the basis for snapshots, interesting questions arise as to
84 how to account used space in the presence of snapshots. If you have a file
85 shared between a subvolume and a snapshot, whom to account the file to? The
86 creator? Both? What if the file gets modified in the snapshot, should only
87 these changes be accounted to it? But wait, both the snapshot and the subvolume
88 belong to the same user home. I just want to limit the total space used by
89 both! But somebody else might not want to charge the snapshots to the users.
90 .sp
91 Btrfs subvolume quota solves these problems by introducing groups of subvolumes
92 and let the user put limits on them. It is even possible to have groups of
93 groups. In the following, we refer to them as \fIqgroups\fP\&.
94 .sp
95 Each qgroup primarily tracks two numbers, the amount of total referenced
96 space and the amount of exclusively referenced space.
97 .INDENT 0.0
98 .TP
99 .B referenced
100 space is the amount of data that can be reached from any of the
101 subvolumes contained in the qgroup
102 .TP
103 .B exclusive
104 is the amount of data where all references to this data can be reached
105 from within this qgroup.
106 .UNINDENT
107 .SS Subvolume quota groups
108 .sp
109 The basic notion of the Subvolume Quota feature is the quota group, short
110 qgroup. Qgroups are notated as \fIlevel/id\fP, e.g. the qgroup 3/2 is a qgroup of
111 level 3. For level 0, the leading \fI0/\fP can be omitted.
112 Qgroups of level 0 get created automatically when a subvolume/snapshot gets
113 created. The ID of the qgroup corresponds to the ID of the subvolume, so 0/5
114 is the qgroup for the toplevel subvolume.
115 For the \fBbtrfs qgroup\fP command, the path to the subvolume can also be used
116 instead of \fI0/ID\fP\&. For all higher levels, the ID can be chosen freely.
117 .sp
118 Each qgroup can contain a set of lower level qgroups, thus creating a hierarchy
119 of qgroups. Here\(aqs an example of qgroup tree:
120 .INDENT 0.0
121 .INDENT 3.5
122 .sp
123 .EX
124 +\-\-\-+
125 |2/1|
126 +\-\-\-+
127 / \e
128 +\-\-\-+/ \e+\-\-\-+
129 |1/1| |1/2|
130 +\-\-\-+ +\-\-\-+
131 / \e / \e
132 +\-\-\-+/ \e+\-\-\-+/ \e+\-\-\-+
133 qgroups |0/1| |0/2| |0/3|
134 +\-+\-+ +\-\-\-+ +\-\-\-+
135 | / \e / \e
136 | / \e / \e
137 | / \e / \e
138 extents 1 2 3 4
139 .EE
140 .UNINDENT
141 .UNINDENT
142 .sp
143 At the bottom, some extents are depicted showing which qgroups reference which
144 extents. It is important to understand the notion of \fIreferenced\fP vs
145 \fIexclusive\fP\&. In the example, qgroup 0/2 references extents 2 and 3, while 1/2
146 references extents 2\-4, 2/1 references all extents.
147 .sp
148 On the other hand, extent 1 is exclusive to 0/1, extent 2 is exclusive to 0/2,
149 while extent 3 is neither exclusive to 0/2 nor to 0/3. But because both
150 references can be reached from 1/2, extent 3 is exclusive to 1/2. All extents
151 are exclusive to 2/1.
152 .sp
153 So exclusive does not mean there is no other way to reach the extent, but it
154 does mean that if you delete all subvolumes contained in a qgroup, the extent
155 will get deleted.
156 .sp
157 Exclusive of a qgroup conveys the useful information how much space will be
158 freed in case all subvolumes of the qgroup get deleted.
159 .sp
160 All data extents are accounted this way. Metadata that belongs to a specific
161 subvolume (i.e. its filesystem tree) is also accounted. Checksums and extent
162 allocation information are not accounted.
163 .sp
164 In turn, the referenced count of a qgroup can be limited. All writes beyond
165 this limit will lead to a \(aqQuota Exceeded\(aq error.
166 .SS Inheritance
167 .sp
168 Things get a bit more complicated when new subvolumes or snapshots are created.
169 The case of (empty) subvolumes is still quite easy. If a subvolume should be
170 part of a qgroup, it has to be added to the qgroup at creation time. To add it
171 at a later time, it would be necessary to at least rescan the full subvolume
172 for a proper accounting.
173 .sp
174 Creation of a snapshot is the hard case. Obviously, the snapshot will
175 reference the exact amount of space as its source, and both source and
176 destination now have an exclusive count of 0 (the filesystem nodesize to be
177 precise, as the roots of the trees are not shared). But what about qgroups of
178 higher levels? If the qgroup contains both the source and the destination,
179 nothing changes. If the qgroup contains only the source, it might lose some
180 exclusive.
181 .sp
182 But how much? The tempting answer is, subtract all exclusive of the source from
183 the qgroup, but that is wrong, or at least not enough. There could have been
184 an extent that is referenced from the source and another subvolume from that
185 qgroup. This extent would have been exclusive to the qgroup, but not to the
186 source subvolume. With the creation of the snapshot, the qgroup would also
187 lose this extent from its exclusive set.
188 .sp
189 So how can this problem be solved? In the instant the snapshot gets created, we
190 already have to know the correct exclusive count. We need to have a second
191 qgroup that contains all the subvolumes as the first qgroup, except the
192 subvolume we want to snapshot. The moment we create the snapshot, the
193 exclusive count from the second qgroup needs to be copied to the first qgroup,
194 as it represents the correct value. The second qgroup is called a tracking
195 qgroup. It is only there in case a snapshot is needed.
196 .SS Use cases
197 .sp
198 Below are some use cases that do not mean to be extensive. You can find your
199 own way how to integrate qgroups.
200 .SS Single\-user machine
201 .sp
202 \fBReplacement for partitions.\fP
203 The simplest use case is to use qgroups as simple replacement for partitions.
204 Btrfs takes the disk as a whole, and \fB/\fP, \fB/usr\fP, \fB/var\fP, etc. are created as
205 subvolumes. As each subvolume gets it own qgroup automatically, they can
206 simply be restricted. No hierarchy is needed for that.
207 .sp
208 \fBTrack usage of snapshots.\fP
209 When a snapshot is taken, a qgroup for it will automatically be created with
210 the correct values. \fIReferenced\fP will show how much is in it, possibly shared
211 with other subvolumes. \fIExclusive\fP will be the amount of space that gets freed
212 when the subvolume is deleted.
213 .SS Multi\-user machine
214 .sp
215 \fBRestricting homes.\fP
216 When you have several users on a machine, with home directories probably under
217 \fB/home\fP, you might want to restrict \fB/home\fP as a whole, while restricting every
218 user to an individual limit as well. This is easily accomplished by creating a
219 qgroup for \fB/home\fP , e.g. 1/1, and assigning all user subvolumes to it.
220 Restricting this qgroup will limit /home, while every user subvolume can get
221 its own (lower) limit.
222 .sp
223 \fBAccounting snapshots to the user.\fP
224 Let\(aqs say the user is allowed to create snapshots via some mechanism. It would
225 only be fair to account space used by the snapshots to the user. This does not
226 mean the user doubles his usage as soon as he takes a snapshot. Of course,
227 files that are present in his home and the snapshot should only be accounted
228 once. This can be accomplished by creating a qgroup for each user, say
229 \fI1/UID\fP\&. The user home and all snapshots are assigned to this qgroup.
230 Limiting it will extend the limit to all snapshots, counting files only once.
231 To limit \fB/home\fP as a whole, a higher level group 2/1 replacing 1/1 from the
232 previous example is needed, with all user qgroups assigned to it.
233 .sp
234 \fBDo not account snapshots.\fP
235 On the other hand, when the snapshots get created automatically, the user has
236 no chance to control them, so the space used by them should not be accounted to
237 him. This is already the case when creating snapshots in the example from
238 the previous section.
239 .sp
240 \fBSnapshots for backup purposes.\fP
241 This scenario is a mixture of the previous two. The user can create snapshots,
242 but some snapshots for backup purposes are being created by the system. The
243 user\(aqs snapshots should be accounted to the user, not the system. The solution
244 is similar to the one from section \fIAccounting snapshots to the user\fP, but do
245 not assign system snapshots to user\(aqs qgroup.
246 .SS Simple quotas (squota)
247 .sp
248 As detailed in this document, qgroups can handle many complex extent sharing
249 and unsharing scenarios while maintaining an accurate count of exclusive and
250 shared usage. However, this flexibility comes at a cost: many of the
251 computations are global, in the sense that we must count up the number of trees
252 referring to an extent after its references change. This can slow down
253 transaction commits and lead to unacceptable latencies, especially in cases
254 where snapshots scale up.
255 .sp
256 To work around this limitation of qgroups, btrfs also supports a second set of
257 quota semantics: \fIsimple quotas\fP or \fIsquotas\fP\&. Squotas fully share the qgroups API
258 and hierarchical model, but do not track shared vs. exclusive usage. Instead,
259 they account all extents to the subvolume that first allocated it. With a bit
260 of new bookkeeping, this allows all accounting decisions to be local to the
261 allocation or freeing operation that deals with the extents themselves, and
262 fully avoids the complex and costly back\-reference resolutions.
263 .sp
264 \fBExample\fP
265 .sp
266 To illustrate the difference between squotas and qgroups, consider the following
267 basic example assuming a nodesize of 16KiB.
268 .INDENT 0.0
269 .IP 1. 3
270 create subvolume 256
271 .IP 2. 3
272 rack up 1GiB of data and metadata usage in 256
273 .IP 3. 3
274 snapshot 256, creating subvolume 257
275 .IP 4. 3
276 COW 512MiB of the data and metadata in 257
277 .IP 5. 3
278 delete everything in 256
279 .UNINDENT
280 .sp
281 At each step, qgroups would have the following accounting:
282 .INDENT 0.0
283 .IP 1. 3
284 0/256: 16KiB excl 0 shared
285 .IP 2. 3
286 0/256: 1GiB excl 0 shared
287 .IP 3. 3
288 0/256: 0 excl 1GiB shared; 0/257: 0 excl 1GiB shared
289 .IP 4. 3
290 0/256: 512MiB excl 512MiB shared; 0/257: 512MiB excl 512MiB shared
291 .IP 5. 3
292 0/256: 16KiB excl 0 shared; 0/257: 1GiB excl 0 shared
293 .UNINDENT
294 .sp
295 Whereas under squotas, the accounting would look like:
296 .INDENT 0.0
297 .IP 1. 3
298 0/256: 16KiB excl 16KiB shared
299 .IP 2. 3
300 0/256: 1GiB excl 1GiB shared
301 .IP 3. 3
302 0/256: 1GiB excl 1GiB shared; 0/257: 16KiB excl 16KiB shared
303 .IP 4. 3
304 0/256: 1GiB excl 1GiB shared; 0/257: 512MiB excl 512MiB shared
305 .IP 5. 3
306 0/256: 512MiB excl 512MiB shared; 0/257: 512MiB excl 512MiB shared
307 .UNINDENT
308 .sp
309 Note that since the original snapshotted 512MiB are still referenced by 257,
310 they cannot be freed from 256, even after 256 is emptied, or even deleted.
311 .sp
312 \fBSummary\fP
313 .sp
314 If you want some of power and flexibility of quotas for tracking and limiting
315 subvolume usage, but want to avoid the performance penalty of accurately
316 tracking extent ownership life cycles, then squotas can be a useful option.
317 .sp
318 Furthermore, squotas is targeted at use cases where the original extent is
319 immutable, like image snapshotting for container startup, in which case we avoid
320 these awkward scenarios where a subvolume is empty or deleted but still has
321 significant extents accounted to it. However, as long as you are aware of the
322 accounting semantics, they can handle mutable original extents.
323 .SH SUBCOMMAND
324 .INDENT 0.0
325 .TP
326 .B disable <path>
327 Disable subvolume quota support for a filesystem.
328 .TP
329 .B enable [options] <path>
330 Enable subvolume quota support for a filesystem. At this point it\(aqs
331 possible the two modes of accounting. The \fIfull\fP means that extent
332 ownership by subvolumes will be tracked all the time, \fIsimple\fP will
333 account everything to the first owner. See the section for more details.
334 .sp
335 \fBOptions\fP
336 .INDENT 7.0
337 .TP
338 .B \-s|\-\-simple
339 use simple quotas (squotas) instead of full qgroup accounting
340 .UNINDENT
341 .TP
342 .B rescan [options] <path>
343 Trash all qgroup numbers and scan the metadata again with the current config.
344 .sp
345 \fBOptions\fP
346 .INDENT 7.0
347 .TP
348 .B \-s|\-\-status
349 show status of a running rescan operation.
350 .TP
351 .B \-w|\-\-wait
352 start rescan and wait for it to finish (can be already in progress)
353 .TP
354 .B \-W|\-\-wait\-norescan
355 wait for rescan to finish without starting it
356 .UNINDENT
357 .TP
358 .B status [options] <path>
359 Print status information about quotas if enabled on \fIpath\fP\&. The information
360 is read from \fB/sys/fs/btrfs/FSID/qgroups\fP and root privileges are
361 not needed.
362 .sp
363 Example output for quotas enabled by \fBbtrfs quota enable /mnt\fP:
364 .INDENT 7.0
365 .INDENT 3.5
366 .sp
367 .EX
368 Quotas on /mnt:
369 Enabled: yes
370 Mode: qgroup (full accounting)
371 Inconsistent: no
372 Override limits: no
373 Drop subtree threshold: 3
374 Total count: 1
375 Level 0: 1
376 .EE
377 .UNINDENT
378 .UNINDENT
379 .sp
380 \fBOptions\fP
381 .INDENT 7.0
382 .TP
383 .B \-\-is\-enabled
384 only check if quotas are enabled, not not print anything
385 .UNINDENT
386 .UNINDENT
387 .SH EXIT STATUS
388 .sp
389 \fBbtrfs quota\fP returns a zero exit status if it succeeds. Non zero is
390 returned in case of failure.
391 .SH AVAILABILITY
392 .sp
393 \fBbtrfs\fP is part of btrfs\-progs. Please refer to the documentation at
394 \X'tty: link https://btrfs.readthedocs.io'\fI\%https://btrfs.readthedocs.io\fP\X'tty: link'\&.
395 .SH SEE ALSO
396 .sp
397 \fI\%btrfs\-qgroup(8)\fP,
398 \fI\%btrfs\-subvolume(8)\fP,
399 \fI\%mkfs.btrfs(8)\fP
400 .\" Generated by docutils manpage writer.
401 .