Documentation/btrfs-qgroup.asciidoc

   1 btrfs-qgroup(8)
   2 ===============
   3
   4 NAME
   5 ----
   6 btrfs-qgroup - control the quota group of a btrfs filesystem
   7
   8 SYNOPSIS
   9 --------
  10 *btrfs qgroup* <subcommand> <args>
  11
  12 DESCRIPTION
  13 -----------
  14 *btrfs qgroup* is used to control quota group (qgroup) of a btrfs filesystem.
  15
  16 NOTE: To use qgroup you need to enable quota first using *btrfs quota enable*
  17 command.
  18
  19 WARNING: Qgroup is not stable yet and will impact performance in current mainline
  20 kernel (v4.14).
  21
  22 QGROUP
  23 ------
  24 Quota groups or qgroup in btrfs make a tree hierarchy, the leaf qgroups are
  25 attached to subvolumes. The size limits are set per qgroup and apply when any
  26 limit is reached in tree that contains a given subvolume.
  27
  28 The limits are separated between shared and exclusive and reflect the extent
  29 ownership. For example a fresh snapshot shares almost all the blocks with the
  30 original subvolume, new writes to either subvolume will raise towards the
  31 exclusive limit.
  32
  33 The qgroup identifiers conform to 'level/id' where level 0 is reserved to the
  34 qgroups associated with subvolumes. Such qgroups are created automatically.
  35
  36 The qgroup hierarchy is built by commands *create* and *assign*.
  37
  38 NOTE: If the qgroup of a subvolume is destroyed, quota about the subvolume
  39 will not be functional until qgroup '0/<subvolume id>' is created again.
  40
  41 SUBCOMMAND
  42 ----------
  43 *assign* [options] <src> <dst> <path>::
  44 Assign qgroup <src> as the child qgroup of <dst> in the btrfs filesystem
  45 identified by <path>.
  46 +
  47 `Options`
  48 +
  49 --rescan::::
  50 Automatically schedule quota rescan if the new qgroup assignment leads to
  51 quota inconsistency.
  52 --no-rescan::::
  53 Explicitly ask not to do a rescan.
  54
  55 *create* <qgroupid> <path>::
  56 Create a subvolume quota group.
  57 +
  58 For the '0/<subvolume id>' qgroup, a qgroup can be created even before the
  59 subvolume is created.
  60
  61 *destroy* <qgroupid> <path>::
  62 Destroy a qgroup.
  63 +
  64 If a qgroup is not isolated, meaning it is a parent or child qgroup, then it
  65 can only be destroyed after the relationship is removed.
  66
  67 *limit* [options] <size>|none [<qgroupid>] <path>::
  68 Limit the size of a qgroup to <size> or no limit in the btrfs filesystem
  69 identified by <path>.
  70 +
  71 If <qgroupid> is not given, qgroup of the subvolume identified by <path>
  72 is used if possible.
  73 +
  74 `Options`
  75 +
  76 -c::::
  77 limit amount of data after compression. This is the default, it is currently not
  78 possible to turn off this option.
  79 +
  80 -e::::
  81 limit space exclusively assigned to this qgroup.
  82
  83 *remove* <src> <dst> <path>::
  84 Remove the relationship between child qgroup <src> and parent qgroup <dst> in
  85 the btrfs filesystem identified by <path>.
  86
  87 *show* [options] <path>::
  88 Show all qgroups in the btrfs filesystem identified by <path>.
  89 +
  90 `Options`
  91 +
  92 -p::::
  93 print parent qgroup id.
  94 -c::::
  95 print child qgroup id.
  96 -r::::
  97 print limit of referenced size of qgroup.
  98 -e::::
  99 print limit of exclusive size of qgroup.
 100 -F::::
 101 list all qgroups which impact the given path(include ancestral qgroups)
 102 -f::::
 103 list all qgroups which impact the given path(exclude ancestral qgroups)
 104 --raw::::
 105 raw numbers in bytes, without the 'B' suffix.
 106 --human-readable::::
 107 print human friendly numbers, base 1024, this is the default
 108 --iec::::
 109 select the 1024 base for the following options, according to the IEC standard.
 110 --si::::
 111 select the 1000 base for the following options, according to the SI standard.
 112 --kbytes::::
 113 show sizes in KiB, or kB with --si.
 114 --mbytes::::
 115 show sizes in MiB, or MB with --si.
 116 --gbytes::::
 117 show sizes in GiB, or GB with --si.
 118 --tbytes::::
 119 show sizes in TiB, or TB with --si.
 120 --sort=[\+/-]<attr>[,[+/-]<attr>]...::::
 121 list qgroups in order of <attr>.
 122 +
 123 <attr> can be one or more of qgroupid,rfer,excl,max_rfer,max_excl.
 124 +
 125 Prefix \'+' means ascending order and \'-' means descending order of <attr>.
 126 If no prefix is given, use ascending order by default.
 127 +
 128 If multiple <attr>s is given, use comma to separate.
 129 +
 130 --sync::::
 131 To retrieve information after updating the state of qgroups,
 132 force sync of the filesystem identified by <path> before getting information.
 133
 134 EXIT STATUS
 135 -----------
 136 *btrfs qgroup* returns a zero exit status if it succeeds. Non zero is
 137 returned in case of failure.
 138
 139 AVAILABILITY
 140 ------------
 141 *btrfs* is part of btrfs-progs.
 142 Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
 143 further details.
 144
 145 SEE ALSO
 146 --------
 147 `mkfs.btrfs`(8),
 148 `btrfs-subvolume`(8),
 149 `btrfs-quota`(8),