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

NAME

6       btrfs-qgroup - control the quota group of a btrfs filesystem
7

SYNOPSIS

9       btrfs qgroup <subcommand> <args>
10

DESCRIPTION

12       btrfs  qgroup  is  used  to  control  quota  group  (qgroup) of a btrfs
13       filesystem.
14
15       NOTE:
16          To use qgroup you need to enable quota first using btrfs  quota  en‐
17          able command.
18
19       WARNING:
20          Qgroup  is  not  stable  yet  and will impact performance in current
21          mainline kernel (v4.14).
22

QGROUP

24       Quota groups or qgroup in btrfs make a tree hierarchy, the leaf qgroups
25       are  attached to subvolumes. The size limits are set per qgroup and ap‐
26       ply when any limit is reached in tree that contains a given subvolume.
27
28       The limits are separated between shared and exclusive and  reflect  the
29       extent  ownership.  For  example a fresh snapshot shares almost all the
30       blocks with the original subvolume, new writes to either subvolume will
31       raise towards the exclusive limit.
32
33       The qgroup identifiers conform to level/id where level 0 is reserved to
34       the qgroups associated with subvolumes. Such qgroups are created  auto‐
35       matically.
36
37       The qgroup hierarchy is built by commands create and assign.
38
39       NOTE:
40          If the qgroup of a subvolume is destroyed, quota about the subvolume
41          will not be functional until  qgroup  0/<subvolume  id>  is  created
42          again.
43

SUBCOMMAND

45       assign [options] <src> <dst> <path>
46              Assign  qgroup  src  as  the  child  qgroup  of dst in the btrfs
47              filesystem identified by path.
48
49              Options
50
51              --rescan
52                     (default since: 4.19) Automatically schedule quota rescan
53                     if  the  new qgroup assignment would lead to quota incon‐
54                     sistency. See QUOTA RESCAN for more information.
55
56              --no-rescan
57                     Explicitly ask not to do a rescan, even if the assignment
58                     will make the quotas inconsistent. This may be useful for
59                     repeated calls where the  rescan  would  add  unnecessary
60                     overhead.
61
62       create <qgroupid> <path>
63              Create a subvolume quota group.
64
65              For  the  0/<subvolume  id> qgroup, a qgroup can be created even
66              before the subvolume is created.
67
68       destroy <qgroupid> <path>
69              Destroy a qgroup.
70
71              If a qgroup is not isolated, meaning it is  a  parent  or  child
72              qgroup,  then it can only be destroyed after the relationship is
73              removed.
74
75       clear-stale <path>
76              Clear all stale qgroups whose subvolume does not exist  anymore,
77              this is the level 0 qgroup like 0/subvolid. Higher level qgroups
78              are not deleted even if they don't have any child qgroups.
79
80       limit [options] <size>|none [<qgroupid>] <path>
81              Limit the size of a qgroup to size or  no  limit  in  the  btrfs
82              filesystem identified by path.
83
84              If  qgroupid is not given, qgroup of the subvolume identified by
85              path is used if possible.
86
87              Options
88
89              -c     limit amount of data after compression. This is  the  de‐
90                     fault,  it is currently not possible to turn off this op‐
91                     tion.
92
93              -e     limit space exclusively assigned to this qgroup.
94
95       remove <src> <dst> <path>
96              Remove the relationship between  child  qgroup  src  and  parent
97              qgroup dst in the btrfs filesystem identified by path.
98
99              Options
100
101              --rescan
102                     (default since: 4.19) Automatically schedule quota rescan
103                     if the removed qgroup relation would lead to quota incon‐
104                     sistency. See QUOTA RESCAN for more information.
105
106              --no-rescan
107                     Explicitly  ask  not  to do a rescan, even if the removal
108                     will make the quotas inconsistent. This may be useful for
109                     repeated  calls  where  the  rescan would add unnecessary
110                     overhead.
111
112       show [options] <path>
113              Show all qgroups in the btrfs filesystem identified by <path>.
114
115              Options
116
117              -p     print parent qgroup id.
118
119              -c     print child qgroup id.
120
121              -r     print limit of referenced size of qgroup.
122
123              -e     print limit of exclusive size of qgroup.
124
125              -F     list all qgroups which impact the given path(include  an‐
126                     cestral qgroups)
127
128              -f     list  all qgroups which impact the given path(exclude an‐
129                     cestral qgroups)
130
131              --raw  raw numbers in bytes, without the B suffix.
132
133              --human-readable
134                     print human friendly numbers, base 1024, this is the  de‐
135                     fault
136
137              --iec  select the 1024 base for the following options, according
138                     to the IEC standard.
139
140              --si   select the 1000 base for the following options, according
141                     to the SI standard.
142
143              --kbytes
144                     show sizes in KiB, or kB with --si.
145
146              --mbytes
147                     show sizes in MiB, or MB with --si.
148
149              --gbytes
150                     show sizes in GiB, or GB with --si.
151
152              --tbytes
153                     show sizes in TiB, or TB with --si.
154
155              --sort=[+/-]<attr>[,[+/-]<attr>]...
156                     list qgroups in order of <attr>.
157
158                     <attr>      can      be      one      or      more     of
159                     qgroupid,rfer,excl,max_rfer,max_excl.
160
161                     Prefix + means ascending order and - means descending or‐
162                     der  of attr.  If no prefix is given, use ascending order
163                     by default.
164
165                     If multiple attr values are given, use comma to separate.
166
167              --sync To retrieve  information  after  updating  the  state  of
168                     qgroups,  force sync of the filesystem identified by path
169                     before getting information.
170

QUOTA RESCAN

172       The rescan reads all extent sharing metadata and updates the respective
173       qgroups accordingly.
174
175       The   information   consists  of  bytes  owned  exclusively  (excl)  or
176       shared/referred to (rfer). There's no explicit information about  which
177       extents  are shared or owned exclusively.  This means when qgroup rela‐
178       tionship changes, extent owners change and qgroup numbers are no longer
179       consistent unless we do a full rescan.
180
181       However  there are cases where we can avoid a full rescan, if a subvol‐
182       ume whose rfer number equals its excl number, which means all bytes are
183       exclusively owned, then assigning/removing this subvolume only needs to
184       add/subtract rfer number from its parent qgroup. This can speed up  the
185       rescan.
186

EXAMPLES

188   Make a parent group that has two quota group children
189       Given the following filesystem mounted at /mnt/my-vault
190
191          Label: none  uuid: 60d2ab3b-941a-4f22-8d1a-315f329797b2
192                 Total devices 1 FS bytes used 128.00KiB
193                 devid    1 size 5.00GiB used 536.00MiB path /dev/vdb
194
195       Enable quota and create subvolumes.  Check subvolume ids.
196
197          $ cd /mnt/my-vault
198          $ btrfs quota enable .
199          $ btrfs subvolume create a
200          $ btrfs subvolume create b
201          $ btrfs subvolume list .
202
203          ID 261 gen 61 top level 5 path a
204          ID 262 gen 62 top level 5 path b
205
206       Create qgroup and set limit to 10MiB.
207
208          $ btrfs qgroup create 1/100 .
209          $ btrfs qgroup limit 10M 1/100 .
210          $ btrfs qgroup assign 0/261 1/100 .
211          $ btrfs qgroup assign 0/262 1/100 .
212
213       And check qgroups.
214
215          $ btrfs qgroup show .
216
217          qgroupid         rfer         excl
218          --------         ----         ----
219          0/5          16.00KiB     16.00KiB
220          0/261        16.00KiB     16.00KiB
221          0/262        16.00KiB     16.00KiB
222          1/100        32.00KiB     32.00KiB
223

EXIT STATUS

225       btrfs qgroup returns a zero exit status if it succeeds. Non zero is re‐
226       turned in case of failure.
227

AVAILABILITY

229       btrfs is part of btrfs-progs.  Please refer  to  the  documentation  at
230       https://btrfs.readthedocs.io.
231

SEE ALSO

233       btrfs-quota(8), btrfs-subvolume(8), mkfs.btrfs(8)
234
235
236
237
2386.6.2                            Nov 24, 2023                  BTRFS-QGROUP(8)
Impressum