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       limit [options] <size>|none [<qgroupid>] <path>
76              Limit the size of a qgroup to size or  no  limit  in  the  btrfs
77              filesystem identified by path.
78
79              If  qgroupid is not given, qgroup of the subvolume identified by
80              path is used if possible.
81
82              Options
83
84              -c     limit amount of data after compression. This is  the  de‐
85                     fault,  it is currently not possible to turn off this op‐
86                     tion.
87
88              -e     limit space exclusively assigned to this qgroup.
89
90       remove <src> <dst> <path>
91              Remove the relationship between  child  qgroup  src  and  parent
92              qgroup dst in the btrfs filesystem identified by path.
93
94              Options
95
96              --rescan
97                     (default since: 4.19) Automatically schedule quota rescan
98                     if the removed qgroup relation would lead to quota incon‐
99                     sistency. See QUOTA RESCAN for more information.
100
101              --no-rescan
102                     Explicitly  ask  not  to do a rescan, even if the removal
103                     will make the quotas inconsistent. This may be useful for
104                     repeated  calls  where  the  rescan would add unnecessary
105                     overhead.
106
107       show [options] <path>
108              Show all qgroups in the btrfs filesystem identified by <path>.
109
110              Options
111
112              -p     print parent qgroup id.
113
114              -c     print child qgroup id.
115
116              -r     print limit of referenced size of qgroup.
117
118              -e     print limit of exclusive size of qgroup.
119
120              -F     list all qgroups which impact the given path(include  an‐
121                     cestral qgroups)
122
123              -f     list  all qgroups which impact the given path(exclude an‐
124                     cestral qgroups)
125
126              --raw  raw numbers in bytes, without the B suffix.
127
128              --human-readable
129                     print human friendly numbers, base 1024, this is the  de‐
130                     fault
131
132              --iec  select the 1024 base for the following options, according
133                     to the IEC standard.
134
135              --si   select the 1000 base for the following options, according
136                     to the SI standard.
137
138              --kbytes
139                     show sizes in KiB, or kB with --si.
140
141              --mbytes
142                     show sizes in MiB, or MB with --si.
143
144              --gbytes
145                     show sizes in GiB, or GB with --si.
146
147              --tbytes
148                     show sizes in TiB, or TB with --si.
149
150              --sort=[+/-]<attr>[,[+/-]<attr>]...
151                     list qgroups in order of <attr>.
152
153                     <attr>      can      be      one      or      more     of
154                     qgroupid,rfer,excl,max_rfer,max_excl.
155
156                     Prefix + means ascending order and - means descending or‐
157                     der  of attr.  If no prefix is given, use ascending order
158                     by default.
159
160                     If multiple attr values are given, use comma to separate.
161
162              --sync To retrieve  information  after  updating  the  state  of
163                     qgroups,  force sync of the filesystem identified by path
164                     before getting information.
165

QUOTA RESCAN

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

EXAMPLES

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

EXIT STATUS

220       btrfs qgroup returns a zero exit status if it succeeds. Non zero is re‐
221       turned in case of failure.
222

AVAILABILITY

224       btrfs  is  part  of  btrfs-progs.   Please  refer  to  the  btrfs  wiki
225       http://btrfs.wiki.kernel.org for further details.
226

SEE ALSO

228       mkfs.btrfs(8), btrfs-subvolume(8), btrfs-quota(8),
229
231       2022
232
233
234
235
2365.18                             May 25, 2022                  BTRFS-QGROUP(8)
Impressum