btrfs-progs: docs: add section about filesystem limits to btrfs(5)

[platform/upstream/btrfs-progs.git] / Documentation / btrfs-quota.asciidoc

diff --git a/Documentation/btrfs-quota.asciidoc b/Documentation/btrfs-quota.asciidoc
index 71602fb..85ebf72 100644 (file)
--- a/Documentation/btrfs-quota.asciidoc
+++ b/Documentation/btrfs-quota.asciidoc
@@ -15,8 +15,24 @@ The commands under *btrfs quota* are used to affect the global status of quotas
 of a btrfs filesystem. The quota groups (qgroups) are managed by the subcommand
 `btrfs qgroup`(8).
 
-NOTE: the qgroups are different than the traditional user quotas and designed
-to track shared and exlusive data per-subvolume.
+NOTE: Qgroups are different than the traditional user quotas and designed
+to track shared and exclusive data per-subvolume.  Please refer to the section
+'HIERARCHICAL QUOTA GROUP CONCEPTS' for a detailed description.
+
+PERFORMANCE IMPLICATIONS
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+When quotas are activated, they affect all extent processing, which takes a
+performance hit. Activation of qgroups is not recommended unless the user
+intends to actually use them.
+
+STABILITY STATUS
+~~~~~~~~~~~~~~~~
+
+The qgroup implementation has turned out to be quite difficult as it affects
+the core of the filesystem operation. Qgroup users have hit various corner cases
+over time, such as incorrect accounting or system instability. The situation is
+gradually improving and issues found and fixed.
 
 HIERARCHICAL QUOTA GROUP CONCEPTS
 ---------------------------------
@@ -36,7 +52,7 @@ On the other hand, the traditional approach has only a poor solution to
 restrict directories.
 At installation time, the harddisk can be partitioned so that every directory
 (eg. /usr, /var/, ...) that needs a limit gets its own partition.  The obvious
-problem is, that those limits cannot be changed without a reinstall ation.  The
+problem is that those limits cannot be changed without a reinstallation.  The
 btrfs subvolume feature builds a bridge.  Subvolumes correspond in many ways to
 partitions, as every subvolume looks like its own filesystem.  With subvolume
 quota, it is now possible to restrict each subvolume like a partition, but keep
@@ -53,7 +69,7 @@ both! But somebody else might not want to charge the snapshots to the users.
 
 Btrfs subvolume quota solves these problems by introducing groups of subvolumes
 and let the user put limits on them.  It is even possible to have groups of
-groups.  In the following, we refer to them as 'qgruops'.
+groups.  In the following, we refer to them as 'qgroups'.
 
 Each qgroup primarily tracks two numbers, the amount of total referenced
 space and the amount of exclusively referenced space.
@@ -68,19 +84,35 @@ from within this qgroup.
 SUBVOLUME QUOTA GROUPS
 ~~~~~~~~~~~~~~~~~~~~~~
 
-The basic notion of the Subvolume Quota feature is the qouta group, short
+The basic notion of the Subvolume Quota feature is the quota group, short
 qgroup.  Qgroups are notated as 'level/id', eg.  the qgroup 3/2 is a qgroup of
 level 3. For level 0, the leading '0/' 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 *btrfs qgroup* command, the path to the subvolume can also be used
-instead of '0/ID'.  For all higher levels, the ID can be choosen freely.
+instead of '0/ID'.  For all higher levels, the ID can be chosen freely.
 
 Each qgroup can contain a set of lower level qgroups, thus creating a hierarchy
 of qgroups. Figure 1 shows an example qgroup tree.
 
-// TODO: insert Figure 1
+                          +---+
+                          |2/1|
+                          +---+
+                         /     \
+                   +---+/       \+---+
+                   |1/1|         |1/2|
+                   +---+         +---+
+                  /     \       /     \
+            +---+/       \+---+/       \+---+
+qgroups     |0/1|         |0/2|         |0/3|
+            +-+-+         +---+         +---+
+              |          /     \       /     \
+              |         /       \     /       \
+              |        /         \   /         \
+extents       1       2            3            4
+
+Figure1: Sample qgroup hierarchy
 
 At the bottom, some extents are depicted showing which qgroups reference which
 extents.  It is important to understand the notion of 'referenced' vs
@@ -149,7 +181,7 @@ own way how to integrate qgroups.
 `Replacement for partitions`
 
 The simplest use case is to use qgroups as simple replacement for partitions.
-Btrfs takes the disk as a whole, and /, /usr, /var etc.  are created as
+Btrfs takes the disk as a whole, and /, /usr, /var, etc. are created as
 subvolumes.  As each subvolume gets it own qgroup automatically, they can
 simply be restricted.  No hierarchy is needed for that.
 
@@ -166,7 +198,7 @@ when the subvolume is deleted.
 
 When you have several users on a machine, with home directories probably under
 /home, you might want to restrict /home as a whole, while restricting every
-user to an indiviual limit as well.  This is easily accomplished by creating a
+user to an individual limit as well.  This is easily accomplished by creating a
 qgroup for /home , eg. 1/1, and assigning all user subvolumes to it.
 Restricting this qgroup will limit /home, while every user subvolume can get
 its own (lower) limit.