Debian Codegraph @

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

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