qgroup/quota info for man page

index d7ece5b..3c72d0a 100644
@@ -184,6 +184,82 @@
  * the filesystem. Can be mixed with the \Bdevid\b filter to select
  * chunks in a given address range on a specific device.
  * 
+ * \h Subvolume Quota concept
+ * 
+ * \BSubvolume Quota Groups\b
+ * 
+ * The basic notion of the Subvolume Quota feature is the quota group, short
+ * qgroup. Qgroups are notated as <level>/<id>, e.g. the qgroup 3/2 is a qgroup
+ * of level 3. For level 0 the leading \I0/\i can be omitted. Qgroups of level 
+ * 0 get created automatically when a subvolume/snapshot gets created. The ID 
+ * of the qgroup corresponds to the ID of the subvolume, so 0/5 is the qgroup 
+ * for the root subvolume. For the \Ibtrfs qgroup\i command, the path to the 
+ * subvolume can also be used instead of 0/<ID>. For all higher levels, the ID 
+ * can be choosen freely.
+ * Each qgroup can contain a set of lower level qgroups, thus creating a 
+ * hierarchy of qgroups.
+ * 
+ *  
+ *                         /- {0/1} ------->[   1   ]
+ *                        /
+ *            /- {1/1} ->-+             /-->[   2   ]
+ *           /            \\\\            /
+ *   {2/1}->-+             +  {0/2} ->-+ 
+ *           \\\\            /            \\\\
+ *            \\\\- {1/2} ->-+             +-->[   3   ]
+ *                        \\\\            /
+ *                         \\\\- {0/3} ->-+
+ *                                     \\\\
+ *                                      \\\\-->[   4   ]
+ *  
+ * 
+ * At the bottom of the figure above some extents are depicted showing which 
+ * qgroups reference which extents. It is important to understand the notion 
+ * of referenced versus exclusive. 
+ * In the example qgroup 0/2 references extents 2 and 3, while 1/2 references 
+ * extents 2-4. 2/1 references all extents.
+ * On the other hand, extent 1 is exclusive to 0/1, extent 2 is exclusive to
+ * 0/2, while extent 3 is neither exclusive to 0/2 nor to 0/3.
+ * But because both references can be reached from 1/2, extent 3 is exclusive
+ * to 1/2.
+ * All extents are exclusive to 2/1. So exclusive doesn't mean there's no other
+ * way to reach the extent, but it does mean that if you delete all subvolumes
+ * contained in a qgroup, the extent will get deleted. Exclusive of a qgroup 
+ * conveys the useful information how much space will be freed in case all 
+ * subvolumes of the qgroup get deleted.
+ * All data extents are accounted this way. Metadata that belong to a specific
+ * subvolume (i.e. its fs tree) are also accounted. Checksums and extent 
+ * allocation information are not accounted.
+ * 
+ * In turn the referenced count of a qgroup can be limited. All writes beyond
+ * that limit will lead to a \IQuota Exceeded\i error.
+ * 
+ * \BQuota Inheritance\b
+ * 
+ * If a subvolume should be part of a qgroup, it has to be added to the qgroup
+ * at creation time. To add it at a later time, it would be necessary to at 
+ * least rescan the full subvolume for a proper accounting.
+ * A snapshot references the exact amount of space as its source, and both 
+ * source and destination now have an exclusive count of 0 (4k to be precise, 
+ * as the roots of the trees are not shared). Regarding the qgroups of higher 
+ * levels, if the qgroup contains both the source and the destination, nothing
+ * changes. If the qgroup contains only the source, it might lose some 
+ * exclusive. But how much? The tempting answer is, \Bsubtract all exclusive 
+ * of the source from the qgroup\b, but that's wrong, or at
+ * least not enough. There could have been an extent that's referenced from the
+ * source and another subvolume from that qgroup. This extent would have been
+ * exclusive to the qgroup, but not to the source subvolume. With the creation
+ * of the snapshot the qgroup would also lose this extent from its exclusive 
+ * set.
+ * So how can this problem be solved? In the instant the snapshot gets cre-
+ * ated we already have to know the correct exclusive count. We need to have a
+ * second qgroup that contains all the subvolumes as the first qgroup, except 
+ * the subvolume we want to snapshot. The moment we create the snapshot, the 
+ * exclusive count from the second qgroup needs to be copied to the first 
+ * qgroup, as it represents the correct value. The second qgroup is called a 
+ * tracking qgroup.
+ * It is only there in case a snapshot is needed.
+ * 
  * \h EXIT STATUS
  * \Bbtrfs\b returns a zero exist status if it succeeds. Non zero is returned in
  * case of failure.

@@ -204,9 +280,6 @@
  ****/
 
 
-
-
-
 typedef int (*CommandFunction)(int argc, char **argv);
 
 struct Command {

204 lines not on this page · raw message

91 lines not on this page · raw message

204 lines not on this page · raw message