path: root/Documentation/btrfs-qgroup.asciidoc
diff options
Diffstat (limited to 'Documentation/btrfs-qgroup.asciidoc')
1 files changed, 145 insertions, 0 deletions
diff --git a/Documentation/btrfs-qgroup.asciidoc b/Documentation/btrfs-qgroup.asciidoc
new file mode 100644
index 00000000..438dbc7d
--- /dev/null
+++ b/Documentation/btrfs-qgroup.asciidoc
@@ -0,0 +1,145 @@
+btrfs-qgroup - control the quota group of a btrfs filesystem
+*btrfs qgroup* <subcommand> <args>
+*btrfs qgroup* is used to control quota group (qgroup) of a btrfs filesystem.
+NOTE: To use qgroup you need to enable quota first using *btrfs quota enable*
+WARNING: Qgroup is not stable yet and will impact performance in current mainline
+kernel (v3.14 so far).
+Quota groups or qgroup in btrfs make a tree hierarchy, the leaf qgroups are
+attached to subvolumes. The size limits are set per qgroup and apply when any
+limit is reached in tree that contains a given subvolume.
+The limits are separated between shared and exclusive and reflect the extent
+ownership. For example a fresh snapshot shares almost all the blocks with the
+original subvolume, new writes to either subvolume will raise towards the
+exclusive limit.
+The qgroup identifiers conform to 'level/id' where level 0 is reserved to the
+qgroups associated with subvolumes. Such qgroups are created automatically.
+The qgroup hierarchy is built by commands *create* and *assign*.
+NOTE: If the qgroup of a subvolume is destroyed, quota about the subvolume
+will not be functional until qgroup '0/<subvolume id>' is created again.
+*assign* [options] <src> <dst> <path>::
+Assign qgroup <src> as the child qgroup of <dst> in the btrfs filesystem
+identified by <path>.
+Automatically schedule quota rescan if the new qgroup assignment leads to
+quota inconsistency.
+Explicitly ask not to do a rescan.
+*create* <qgroupid> <path>::
+Create a subvolume quota group.
+For the '0/<subvolume id>' qgroup, a qgroup can be created even before the
+subvolume created.
+*destroy* <qgroupid> <path>::
+Destroy a qgroup.
+If a qgroup is no isolated,which means it is a parent or child qgroup, it
+can't be destroyed.
+*limit* [options] <size>|none [<qgroupid>] <path>::
+Limit the size of a qgroup to <size> or no limit in the btrfs filesystem
+identified by <path>.
+If <qgroupid> is not given, qgroup of the subvolume identified by <path>
+is used if possible.
+limit amount of data after compression. This is the default, it is currently not
+possible to turn off this option.
+limit space exclusively assigned to this qgroup.
+*remove* <src> <dst> <path>::
+Remove the relationship between child qgroup <src> and parent qgroup <dst> in
+the btrfs filesystem identified by <path>.
+*show* [options] <path>::
+Show all qgroups in the btrfs filesystem identified by <path>.
+print parent qgroup id.
+print child qgroup id.
+print limit of referenced size of qgroup.
+print limit of exclusive size of qgroup.
+list all qgroups which impact the given path(include ancestral qgroups)
+list all qgroups which impact the given path(exclude ancestral qgroups)
+raw numbers in bytes, without the 'B' suffix.
+print human friendly numbers, base 1024, this is the default
+select the 1024 base for the following options, according to the IEC standard.
+select the 1000 base for the following options, according to the SI standard.
+show sizes in KiB, or kB with --si.
+show sizes in MiB, or MB with --si.
+show sizes in GiB, or GB with --si.
+show sizes in TiB, or TB with --si.
+list qgroups in order of <attr>.
+<attr> can be one or more of qgroupid,rfer,excl,max_rfer,max_excl.
+Prefix \'+' means ascending order and \'-' means descending order of <attr>.
+If no prefix is given, use ascending order by default.
+If multiple <attr>s is given, use comma to separate.
+*btrfs qgroup* returns a zero exit status if it succeeds. Non zero is
+returned in case of failure.
+*btrfs* is part of btrfs-progs.
+Please refer to the btrfs wiki for
+further details.