1BTRFS-QUOTA(8) Btrfs Manual BTRFS-QUOTA(8)
2
6 btrfs-quota - control the global quota status of a btrfs filesystem
7
9 btrfs quota <subcommand> <args>
10
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 Note
17 the qgroups are different than the traditional user quotas and
18 designed to track shared and exclusive data per-subvolume. Please
19 refer to the section HIERARCHICAL QUOTA GROUP CONCEPTS for a
20 detailed description.
21 PERFORMANCE IMPLICATIONS
23 When the quotas are turned on, they affect all extent processing,
24 taking a performance hit. It is not recommended to turn on qgroups
25 unless the user intends to actually use them.
26 STABILITY STATUS
28 The qgroup implementation has turned out to be quite difficult as it
29 affects the core of the filesystem operation. The users have hit
30 various corner cases over time, eg. wrong accounting or system
31 instability. The situation is gradually improving but currently (4.7)
32 there are still issues found and fixed.
33
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 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 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 reinstall ation. The btrfs subvolume
52 feature builds a bridge. Subvolumes correspond in many ways to
53 partitions, as every subvolume looks like its own filesystem. With
54 subvolume quota, it is now possible to restrict each subvolume like a
55 partition, but keep the flexibility of quota. The space for each
56 subvolume can be expanded or restricted on the fly.
57 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 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 qgruops.
70 Each qgroup primarily tracks two numbers, the amount of total
72 referenced space and the amount of exclusively referenced space.
73 referenced
75 space is the amount of data that can be reached from any of the
76 subvolumes contained in the qgroup, while
77 exclusive
79 is the amount of data where all references to this data can be
80 reached from within this qgroup.
81 SUBVOLUME QUOTA GROUPS
83 The basic notion of the Subvolume Quota feature is the qouta 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 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 At the bottom, some extents are depicted showing which qgroups
96 reference which extents. It is important to understand the notion of
97 referenced vs exclusive. In the example, qgroup 0/2 references extents
98 2 and 3, while 1/2 references extents 2-4, 2/1 references all extents.
99 On the other hand, extent 1 is exclusive to 0/1, extent 2 is exclusive
101 to 0/2, while extent 3 is neither exclusive to 0/2 nor to 0/3. But
102 because both references can be reached from 1/2, extent 3 is exclusive
103 to 1/2. All extents are exclusive to 2/1.
104 So exclusive does not mean there is no other way to reach the extent,
106 but it does mean that if you delete all subvolumes contained in a
107 qgroup, the extent will get deleted.
108 Exclusive of a qgroup conveys the useful information how much space
110 will be freed in case all subvolumes of the qgroup get deleted.
111 All data extents are accounted this way. Metadata that belongs to a
113 specific subvolume (i.e. its filesystem tree) is also accounted.
114 Checksums and extent allocation information are not accounted.
115 In turn, the referenced count of a qgroup can be limited. All writes
117 beyond this limit will lead to a Quota Exceeded error.
118 INHERITANCE
120 Things get a bit more complicated when new subvolumes or snapshots are
121 created. The case of (empty) subvolumes is still quite easy. If a
122 subvolume should be part of a qgroup, it has to be added to the qgroup
123 at creation time. To add it at a later time, it would be necessary to
124 at least rescan the full subvolume for a proper accounting.
125 Creation of a snapshot is the hard case. Obviously, the snapshot will
127 reference the exact amount of space as its source, and both source and
128 destination now have an exclusive count of 0 (the filesystem nodesize
129 to be precise, as the roots of the trees are not shared). But what
130 about qgroups of higher levels? If the qgroup contains both the source
131 and the destination, nothing changes. If the qgroup contains only the
132 source, it might lose some exclusive.
133 But how much? The tempting answer is, subtract all exclusive of the
135 source from the qgroup, but that is wrong, or at least not enough.
136 There could have been an extent that is referenced from the source and
137 another subvolume from that qgroup. This extent would have been
138 exclusive to the qgroup, but not to the source subvolume. With the
139 creation of the snapshot, the qgroup would also lose this extent from
140 its exclusive set.
141 So how can this problem be solved? In the instant the snapshot gets
143 created, we already have to know the correct exclusive count. We need
144 to have a second qgroup that contains all the subvolumes as the first
145 qgroup, except the subvolume we want to snapshot. The moment we create
146 the snapshot, the exclusive count from the second qgroup needs to be
147 copied to the first qgroup, as it represents the correct value. The
148 second qgroup is called a tracking qgroup. It is only there in case a
149 snapshot is needed.
150 USE CASES
152 Below are some usecases that do not mean to be extensive. You can find
153 your own way how to integrate qgroups.
154 SINGLE-USER MACHINE
156 Replacement for partitions
157 The simplest use case is to use qgroups as simple replacement for
159 partitions. Btrfs takes the disk as a whole, and /, /usr, /var etc.
160 are created as subvolumes. As each subvolume gets it own qgroup
161 automatically, they can simply be restricted. No hierarchy is
162 needed for that.
163 Track usage of snapshots
165 When a snapshot is taken, a qgroup for it will automatically be
167 created with the correct values. Referenced will show how much is
168 in it, possibly shared with other subvolumes. Exclusive will be the
169 amount of space that gets freed when the subvolume is deleted.
170 MULTI-USER MACHINE
172 Restricting homes
173 When you have several users on a machine, with home directories
175 probably under /home, you might want to restrict /home as a whole,
176 while restricting every user to an indiviual limit as well. This is
177 easily accomplished by creating a qgroup for /home , eg. 1/1, and
178 assigning all user subvolumes to it. Restricting this qgroup will
179 limit /home, while every user subvolume can get its own (lower)
180 limit.
181 Accounting snapshots to the user
183 Let’s say the user is allowed to create snapshots via some
185 mechanism. It would only be fair to account space used by the
186 snapshots to the user. This does not mean the user doubles his
187 usage as soon as he takes a snapshot. Of course, files that are
188 present in his home and the snapshot should only be accounted once.
189 This can be accomplished by creating a qgroup for each user, say
190 1/UID. The user home and all snapshots are assigned to this qgroup.
191 Limiting it will extend the limit to all snapshots, counting files
192 only once. To limit /home as a whole, a higher level group 2/1
193 replacing 1/1 from the previous example is needed, with all user
194 qgroups assigned to it.
195 Do not account snapshots
197 On the other hand, when the snapshots get created automatically,
199 the user has no chance to control them, so the space used by them
200 should not be accounted to him. This is already the case when
201 creating snapshots in the example from the previous section.
202 Snapshots for backup purposes
204 This scenario is a mixture of the previous two. The user can create
206 snapshots, but some snapshots for backup purposes are being created
207 by the system. The user’s snapshots should be accounted to the
208 user, not the system. The solution is similar to the one from
209 section Accounting snapshots to the user, but do not assign system
210 snapshots to user’s qgroup.
211
213 disable <path>
214 Disable subvolume quota support for a filesystem.
215 enable <path>
217 Enable subvolume quota support for a filesystem.
218 rescan [-s] <path>
220 Trash all qgroup numbers and scan the metadata again with the
221 current config.
222 Options
224 -s
226 show status of a running rescan operation.
227 -w
229 wait for rescan operation to finish(can be already in
230 progress).
231
233 btrfs quota returns a zero exit status if it succeeds. Non zero is
234 returned in case of failure.
235
237 btrfs is part of btrfs-progs. Please refer to the btrfs wiki
238 http://btrfs.wiki.kernel.org for further details.
239
241 mkfs.btrfs(8), btrfs-subvolume(8), btrfs-qgroup(8)
242Btrfs v4.9.1 08/06/2017 BTRFS-QUOTA(8)