ConfiguringQuotas.xml

   1 <?xml version='1.0' encoding='UTF-8'?><chapter xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en-US" xml:id="configuringquotas">
   2   <title xml:id="configuringquotas.title">Configuring and Managing Quotas</title>
   3   <para>This chapter describes how to configure quotas and includes the following sections:</para>
   4   <itemizedlist>
   5     <listitem>
   6       <para><xref linkend="quota_configuring"/></para>
   7     </listitem>
   8     <listitem>
   9       <para><xref linkend="enabling_disk_quotas"/></para>
  10     </listitem>
  11     <listitem>
  12       <para><xref linkend="quota_administration"/></para>
  13     </listitem>
  14     <listitem>
  15       <para><xref linkend="quota_allocation"/></para>
  16     </listitem>
  17     <listitem>
  18       <para><xref linkend="quota_interoperability"/></para>
  19     </listitem>
  20     <listitem>
  21       <para><xref linkend="granted_cache_and_quota_limits"/></para>
  22     </listitem>
  23     <listitem>
  24       <para><xref linkend="lustre_quota_statistics"/></para>
  25     </listitem>
  26   </itemizedlist>
  27   <section xml:id="quota_configuring">
  28       <title>
  29           <indexterm><primary>Quotas</primary><secondary>configuring</secondary></indexterm>Working with Quotas</title>
  30     <para>Quotas allow a system administrator to limit the amount of disk space a user or group can use. Quotas are set by root, and can be specified for individual users and/or groups. Before a file is written to a partition where quotas are set, the quota of the creator&apos;s group is checked. If a quota exists, then the file size counts towards the group&apos;s quota. If no quota exists, then the owner&apos;s user quota is checked before the file is written. Similarly, inode usage for specific functions can be controlled if a user over-uses the allocated space.</para>
  31     <para>Lustre quota enforcement differs from standard Linux quota enforcement in several ways:</para>
  32     <itemizedlist>
  33       <listitem>
  34         <para>Quotas are administered via the <literal>lfs</literal> and <literal>lctl</literal> commands (post-mount).</para>
  35       </listitem>
  36       <listitem>
  37         <para>Quotas are distributed (as the Lustre file system is a distributed file system), which
  38           has several ramifications.</para>
  39       </listitem>
  40       <listitem>
  41         <para>Quotas are allocated and consumed in a quantized fashion.</para>
  42       </listitem>
  43       <listitem>
  44       <para>Client does not set the <literal>usrquota</literal> or <literal>grpquota</literal>
  45           options to mount. As of Lustre software release 2.4, space accounting is always enabled by
  46           default and quota enforcement can be enabled/disabled on a per-file system basis with
  47             <literal>lctl conf_param</literal>. It is worth noting that both <literal>lfs
  48             quotaon</literal> and <literal>quota_type</literal> are deprecated as of Lustre software
  49           release 2.4.0.</para>
  50       </listitem>
  51     </itemizedlist>
  52     <caution>
  53       <para>Although a quota feature is available in the Lustre software, root quotas are NOT
  54         enforced.</para>
  55       <para><literal>lfs setquota -u root</literal> (limits are not enforced)</para>
  56       <para><literal>lfs quota -u root</literal> (usage includes internal Lustre data that is dynamic in size and does not accurately reflect mount point visible block and inode usage).</para>
  57     </caution>
  58   </section>
  59   <section xml:id="enabling_disk_quotas">
  60     <title><indexterm><primary>Quotas</primary><secondary>enabling disk</secondary></indexterm>Enabling Disk Quotas</title>
  61     <para>Prior to Lustre software release 2.4.0, enabling quota involved a full file system scan
  62       via <literal>lfs quotacheck</literal>. All file systems formatted with Lustre software release
  63       2.4.0 or newer no longer require quotacheck to be run since up-to-date accounting information
  64       are now always maintained by the OSD layer, regardless of the quota enforcement status. </para>
  65     <section remap="h3" condition="l24">
  66       <title>Enabling Disk Quotas (Lustre Software Release 2.4 and later)</title>
  67       <para>Although quota enforcement is managed by the Lustre software, each OSD implementation
  68         relies on the backend file system to maintain per-user/group block and inode usage:</para>
  69       <itemizedlist>
  70         <listitem>
  71           <para>For ldiskfs backends, <literal>mkfs.lustre</literal> now creates empty quota files
  72             and enables the QUOTA feature flag in the superblock which turns quota accounting on at
  73             mount time automatically. e2fsck was also modified to fix the quota files when the QUOTA
  74             feature flag is present.</para>
  75         </listitem>
  76         <listitem>
  77           <para>For ZFS backend, accounting ZAPs are created and maintained by the ZFS file system
  78             itself. While ZFS tracks per-user and group block usage, it does not handle inode
  79             accounting. The ZFS OSD implements its own support for inode tracking. Two options are
  80             available:</para>
  81           <orderedlist>
  82             <listitem>
  83               <para> The ZFS OSD can estimate the number of inodes in-use based on the number of
  84                 blocks used by a given user or group. This mode can be enabled by running the
  85                 following command on the server running the target: <literal>lctl set_param
  86                   osd-zfs.${FSNAME}-${TARGETNAME}.quota_iused_estimate=1</literal>.</para>
  87             </listitem>
  88             <listitem>
  89               <para> Similarly to block accounting, dedicated ZAPs are also created the ZFS OSD to
  90                 maintain per-user and group inode usage. This is the default mode which corresponds
  91                 to <literal>quota_iused_estimate</literal> set to 0.</para>
  92             </listitem>
  93           </orderedlist>
  94         </listitem>
  95       </itemizedlist>
  96       <para>As a result, <literal>lfs quotacheck</literal> is now deprecated and not required any
  97         more when running Lustre software release 2.4 on the servers.</para>
  98       <para>Lustre file systems formatted with a Lustre release prior to 2.4.0 can be still safely
  99         upgraded to release 2.4.0, but won't have functional space usage report until
 100           <literal>tunefs.lustre --quota</literal> is run against all targets. This command sets the
 101         QUOTA feature flag in the superblock and runs e2fsck (as a result, the target must be
 102         offline) to build the per-UID/GID disk usage database. </para>
 103       <caution>
 104         <para>Lustre software release 2.4 and beyond requires a version of e2fsprogs that supports
 105           quota (i.e. newer or equal to 1.42.3.wc1) to be installed on the server nodes using
 106           ldiskfs backend (e2fsprogs isn't needed with ZFS backend). In general, we recommend to use
 107           the latest e2fsprogs version available on <link
 108             xl:href="http://downloads.hpdd.intel.com/e2fsprogs/"
 109             >http://downloads.hpdd.intel.com/public/e2fsprogs/</link>.</para>
 110
 111         <para>The ldiskfs OSD relies on the standard Linux quota to maintain accounting information
 112           on disk. As a consequence, the Linux kernel running on the Lustre servers using ldiskfs
 113           backend must have <literal>CONFIG_QUOTA</literal>, <literal>CONFIG_QUOTACTL</literal> and
 114             <literal>CONFIG_QFMT_V2</literal> enabled.</para>
 115       </caution>
 116       <para>As of Lustre software release 2.4.0, quota enforcement is thus turned on/off
 117         independently of space accounting which is always enabled. <literal>lfs
 118             quota<replaceable>on|off</replaceable></literal> as well as the per-target
 119           <literal>quota_type</literal> parameter are deprecated in favor of a single per-file
 120         system quota parameter controlling inode/block quota enforcement. Like all permanent
 121         parameters, this quota parameter can be set via <literal>lctl conf_param</literal> on the
 122         MGS via the following syntax:</para>
 123       <screen>lctl conf_param <replaceable>fsname</replaceable>.quota.<replaceable>ost|mdt</replaceable>=<replaceable>u|g|ug|none</replaceable></screen>
 124       <itemizedlist>
 125         <listitem>
 126           <para><literal>ost</literal> -- to configure block quota managed by OSTs</para>
 127         </listitem>
 128         <listitem>
 129           <para><literal>mdt</literal> -- to configure inode quota managed by MDTs</para>
 130         </listitem>
 131         <listitem>
 132           <para><literal>u</literal> -- to enable quota enforcement for users only</para>
 133         </listitem>
 134         <listitem>
 135           <para><literal>g</literal> -- to enable quota enforcement for groups only</para>
 136         </listitem>
 137         <listitem>
 138           <para><literal>ug</literal> -- to enable quota enforcement for both users and
 139             groups</para>
 140         </listitem>
 141         <listitem>
 142           <para><literal>none</literal> -- to disable quota enforcement for both users and
 143             groups</para>
 144         </listitem>
 145       </itemizedlist>
 146       <para>Examples:</para>
 147       <para>To turn on user and group quotas for block only on file system
 148           <literal>testfs1</literal>, run:</para>
 149       <screen>$ lctl conf_param testfs1.quota.ost=ug</screen>
 150       <para>To turn on group quotas for inodes on file system <literal>testfs2</literal>,
 151         run:</para>
 152       <screen>$ lctl conf_param testfs2.quota.mdt=g</screen>
 153       <para>To turn off user and group quotas for both inode and block on file system
 154           <literal>testfs3</literal>, run:</para>
 155       <screen>$ lctl conf_param testfs3.quota.ost=none</screen>
 156       <screen>$ lctl conf_param testfs3.quota.mdt=none</screen>
 157       <para>Once the quota parameter set on the MGS, all targets which are part of the file system
 158         will be notified of the new quota settings and enable/disable quota enforcement as needed.
 159         The per-target enforcement status can still be verified by running the following command on
 160         the Lustre servers:</para>
 161       <screen>$ lctl get_param osd-*.*.quota_slave.info
 162 osd-zfs.testfs-MDT0000.quota_slave.info=
 163 target name:    testfs-MDT0000
 164 pool ID:        0
 165 type:           md
 166 quota enabled:  ug
 167 conn to master: setup
 168 user uptodate:  glb[1],slv[1],reint[0]
 169 group uptodate: glb[1],slv[1],reint[0]</screen>
 170       <caution>
 171         <para>Lustre software release 2.4 comes with a new quota protocol and a new on-disk format,
 172           be sure to check the Interoperability section below (see <xref
 173             linkend="quota_interoperability"/>.) when migrating to release 2.4</para>
 174       </caution>
 175     </section>
 176     <section remap="h3">
 177       <title>Enabling Disk Quotas (Lustre Releases Previous to Release 2.4 )</title>
 178       <para><note>
 179           <?oxy_custom_start type="oxy_content_highlight" color="255,64,0"?>
 180           <para><?oxy_custom_end?>In Lustre software releases previous to release 2.4, when new OSTs
 181             are added to the file system, quotas are not automatically propagated to the new OSTs.
 182             As a workaround, clear and then reset quotas for each user or group using the
 183               <literal>lfs setquota</literal> command. In the example below, quotas are cleared and
 184             reset for user <literal>bob</literal> on file system <literal>testfs</literal>:
 185             <screen>$ lfs setquota -u bob -b 0 -B 0 -i 0 -I 0 /mnt/testfs
 186 $ lfs setquota -u bob -b 307200 -B 309200 -i 10000 -I 11000 /mnt/testfs</screen></para>
 187         </note>For Lustre software releases older than release 2.4, <literal>lfs
 188           quotacheck</literal> must be first run from a client node to create quota files on the
 189         Lustre targets (i.e. the MDT and OSTs). <literal>lfs quotacheck</literal> requires the file
 190         system to be quiescent (i.e. no modifying operations like write, truncate, create or delete
 191         should run concurrently). Failure to follow this caution may result in inaccurate user/group
 192         disk usage. Operations that do not change Lustre files (such as read or mount) are okay to
 193         run. <literal>lfs quotacheck</literal> performs a scan on all the Lustre targets to
 194         calculates the block/inode usage for each user/group. If the Lustre file system has many
 195         files, <literal>quotacheck</literal> may take a long time to complete. Several options can
 196         be passed to <literal>lfs quotacheck</literal>:</para>
 197       <screen># lfs quotacheck -ug /mnt/testfs</screen>
 198       <itemizedlist>
 199         <listitem>
 200           <para><literal>u</literal> -- checks the user disk quota information</para>
 201         </listitem>
 202         <listitem>
 203           <para><literal>g</literal> -- checks the group disk quota information</para>
 204         </listitem>
 205       </itemizedlist>
 206       <para>By default, quota is turned on after <literal>quotacheck</literal> completes. However,
 207         this setting isn't persistent and quota will have to be enabled again (via <literal>lfs
 208           quotaon</literal>) if one of the Lustre targets is restarted. <literal>lfs
 209           quotaoff</literal> is used to turn off quota.</para>
 210       <para>To enable quota permanently with a Lustre software release older than release 2.4, the
 211           <literal>quota_type</literal> parameter must be used. This requires setting
 212           <literal>mdd.quota_type</literal> and <literal>ost.quota_type</literal>, respectively, on
 213         the MDT and OSTs. <literal>quota_type</literal> can be set to the string
 214           <literal>u</literal> (user), <literal>g</literal> (group) or <literal>ug</literal> for
 215         both users and groups. This parameter can be specified at <literal>mkfs</literal> time
 216           (<literal>mkfs.lustre --param mdd.quota_type=ug</literal>) or with
 217           <literal>tunefs.lustre</literal>. As an example:</para>
 218       <screen>tunefs.lustre --param ost.quota_type=ug $ost_dev</screen>
 219       <para>When using <literal>mkfs.lustre --param mdd.quota_type=ug</literal> or
 220           <literal>tunefs.lustre --param ost.quota_type=ug</literal>, be sure to run the command on
 221         all OSTs and the MDT. Otherwise, abnormal results may occur.</para>
 222     </section>
 223
 224   </section>
 225   <section xml:id="quota_administration">
 226     <title><indexterm><primary>Quotas</primary><secondary>creating</secondary></indexterm>Quota Administration</title>
 227     <para>Once the file system is up and running, quota limits on blocks and files can be set for
 228       both user and group. This is controlled via three quota parameters:</para>
 229     <para><emphasis role="bold">Grace period</emphasis> -- The period of time (in seconds) within which users are allowed to exceed their soft limit. There are four types of grace periods:</para>
 230     <itemizedlist>
 231       <listitem>
 232         <para> user block soft limit</para>
 233       </listitem>
 234       <listitem>
 235         <para> user inode soft limit</para>
 236       </listitem>
 237       <listitem>
 238         <para> group block soft limit</para>
 239       </listitem>
 240       <listitem>
 241         <para> group inode soft limit</para>
 242       </listitem>
 243     </itemizedlist>
 244     <para>The grace period applies to all users. The user block soft limit is for all users who are using a blocks quota.</para>
 245     <para><emphasis role="bold">Soft limit</emphasis> -- The grace timer is started once the soft limit is exceeded. At this point, the user/group can still allocate block/inode. When the grace time expires and if the user is still above the soft limit, the soft limit becomes a hard limit and the user/group can't allocate any new block/inode any more. The user/group should then delete files to be under the soft limit. The soft limit MUST be smaller than the hard limit. If the soft limit is not needed, it should be set to zero (0).</para>
 246       <para><emphasis role="bold">Hard limit</emphasis> -- Block or inode allocation will fail with <literal>EDQUOT</literal> (i.e. quota exceeded) when the hard limit is reached. The hard limit is the absolute limit. When a grace period is set, one can exceed the soft limit within the grace period if under the hard limit.</para>
 247     <para>Due to the distributed nature of a Lustre file system and the need to mainain performance
 248       under load, those quota parameters may not be 100% accurate. The quota settings can be
 249       manipulated via the <literal>lfs</literal> command which includes several options to work with
 250       quotas:</para>
 251     <itemizedlist>
 252       <listitem>
 253         <para><varname>quota</varname>     -- displays general quota information (disk usage and limits)</para>
 254       </listitem>
 255       <listitem>
 256         <para><varname>setquota</varname>  -- specifies quota limits and tunes the grace period. By default, the grace period is one week.</para>
 257       </listitem>
 258     </itemizedlist>
 259     <para> Usage:</para>
 260     <screen>lfs quota [-q] [-v] [-h] [-o obd_uuid] [-u|-g <replaceable>uname|uid|gname|gid</replaceable>]  <replaceable>/mount_point</replaceable>
 261 lfs quota -t <replaceable>-u|-g</replaceable> <replaceable>/mount_point</replaceable>
 262 lfs setquota <replaceable>-u|--user|-g|--group</replaceable> <replaceable>username|groupname</replaceable> [-b <replaceable>block-softlimit</replaceable>] \
 263              [-B <replaceable>block_hardlimit</replaceable>] [-i <replaceable>inode_softlimit</replaceable>] \
 264              [-I <replaceable>inode_hardlimit</replaceable>] <replaceable>/mount_point</replaceable></screen>
 265     <para>To display general quota information (disk usage and limits) for the user running the command and his primary group, run:</para>
 266     <screen>$ lfs quota /mnt/testfs </screen>
 267     <para>To display general quota information for a specific user (&quot;<literal>bob</literal>&quot; in this example), run:</para>
 268     <screen>$ lfs quota -u bob /mnt/testfs</screen>
 269     <para>To display general quota information for a specific user (&quot;<literal>bob</literal>&quot; in this example) and detailed quota statistics for each MDT and OST, run:</para>
 270     <screen>$ lfs quota -u bob -v /mnt/testfs</screen>
 271     <para>To display general quota information for a specific group (&quot;<literal>eng</literal>&quot; in this example), run:</para>
 272     <screen>$ lfs quota -g eng /mnt/testfs</screen>
 273     <para>To display block and inode grace times for user quotas, run:</para>
 274     <screen>$ lfs quota -t -u /mnt/testfs</screen>
 275     <para>To set user or group quotas for a specific ID (&quot;bob&quot; in this example), run:</para>
 276     <screen>$ lfs setquota -u bob -b 307200 -B 309200 -i 10000 -I 11000 /mnt/testfs</screen>
 277     <para>In this example, the quota for user &quot;bob&quot; is set to 300 MB (309200*1024) and the hard limit is 11,000 files. Therefore, the inode hard limit should be 11000.</para>
 278     <para>The quota command displays the quota allocated and consumed by each Lustre target. Using the previous <literal>setquota</literal> example, running this <literal>lfs</literal> quota command:</para>
 279     <screen>$ lfs quota -u bob -v /mnt/testfs </screen>
 280     <para>displays this command output:</para>
 281     <screen>Disk quotas for user bob (uid 6000):
 282 Filesystem          kbytes quota limit grace files quota limit grace
 283 /mnt/testfs         0      30720 30920 -     0     10000 11000 -
 284 testfs-MDT0000_UUID 0      -      8192 -     0     -     2560  -
 285 testfs-OST0000_UUID 0      -      8192 -     0     -     0     -
 286 testfs-OST0001_UUID 0      -      8192 -     0     -     0     -
 287 Total allocated inode limit: 2560, total allocated block limit: 24576</screen>
 288   <para>Global quota limits are stored in dedicated index files (there is one such index per quota type) on the quota master target (aka QMT). The QMT runs on MDT0000 and exports the global indexes via /proc. The global indexes can thus be dumped via the following command: <screen># lctl get_param qmt.testfs-QMT0000.*.glb-*</screen> The format of global indexes depends on the OSD type. The ldiskfs OSD uses an IAM files while the ZFS OSD creates dedicated ZAPs.</para>
 289   <para>Each slave also stores a copy of this global index locally. When the global index is modified on the master, a glimpse callback is issued on the global quota lock to notify all slaves that the global index has been modified. This glimpse callback includes information about the identifier subject to the change. If the global index on the QMT is modified while a slave is disconnected, the index version is used to determine whether the slave copy of the global index isn't uptodate any more. If so, the slave fetches the whole index again and updates the local copy. The slave copy of the global index is also exported via /proc and can be accessed via the following command: <screen>lctl get_param osd-*.*.quota_slave.limit*</screen></para>
 290   <note>
 291   <para>Prior to 2.4, global quota limits used to be stored in administrative quota files using the on-disk format of the linux quota file. When upgrading MDT0000 to 2.4, those administrative quota files are converted into IAM indexes automatically, conserving existing quota limits previously set by the administrator.</para>
 292   </note>
 293   </section>
 294   <section xml:id="quota_allocation">
 295     <title><indexterm><primary>Quotas</primary><secondary>allocating</secondary></indexterm>Quota Allocation</title>
 296     <para>In a Lustre file system, quota must be properly allocated or users may experience
 297       unnecessary failures. The file system block quota is divided up among the OSTs within the file
 298       system. Each OST requests an allocation which is increased up to the quota limit. The quota
 299       allocation is then <emphasis role="italic">quantized</emphasis> to reduce the number of
 300       quota-related request traffic.</para>
 301     <para>The Lustre quota system distributes quotas from the Quota Master Target (aka QMT). Only one QMT instance is supported for now and only runs on the same node as MDT0000. All OSTs and MDTs set up a Quota Slave Device (aka QSD) which connects to the QMT to allocate/release quota space. The QSD is setup directly from the OSD layer.</para>
 302     <para>To reduce quota requests, quota space is initially allocated to QSDs in very large chunks. How much unused quota space can be hold by a target is controlled by the qunit size. When quota space for a given ID is close to exhaustion on the QMT, the qunit size is reduced and QSDs are notified of the new qunit size value via a glimpse callback. Slaves are then responsible for releasing quota space above the new qunit value. The qunit size isn't shrunk indefinitely and there is a minimal value of 1MB for blocks and 1,024 for inodes. This means that the quota space rebalancing process will stop when this mininum value is reached. As a result, quota exceeded can be returned while many slaves still have 1MB or 1,024 inodes of spare quota space.</para>
 303     <para>If we look at the <literal>setquota</literal> example again, running this <literal>lfs quota</literal> command:</para>
 304     <screen># lfs quota -u bob -v /mnt/testfs
 305 </screen>
 306     <para>displays this command output:</para>
 307     <screen>Disk quotas for user bob (uid 500):
 308 Filesystem          kbytes quota limit grace       files  quota limit grace
 309 /mnt/testfs         30720* 30720 30920 6d23h56m44s 10101* 10000 11000 6d23h59m50s
 310 testfs-MDT0000_UUID 0      -     0     -           10101  -     10240
 311 testfs-OST0000_UUID 0      -     1024  -           -      -     -
 312 testfs-OST0001_UUID 30720* -     29896 -           -      -     -
 313 Total allocated inode limit: 10240, total allocated block limit: 30920</screen>
 314     <para>The total quota limit of 30,920 is allocated to user bob, which is further distributed to two OSTs.</para>
 315     <para>Values appended with &apos;<literal>*</literal>&apos; show that the quota limit has been exceeded, causing the following error when trying to write or create a file:</para>
 316     <para><screen>$ cp: writing `/mnt/testfs/foo`: Disk quota exceeded.</screen></para>
 317     <note>
 318       <para>It is very important to note that the block quota is consumed per OST and the inode quota per MDS. Therefore, when the quota is consumed on one OST (resp. MDT), the client may not be able to create files regardless of the quota available on other OSTs (resp. MDTs).</para>
 319       <para>Setting the quota limit below the minimal qunit size may prevent the user/group from all file creation. It is thus recommended to use soft/hard limits which are a multiple of the number of OSTs * the minimal qunit size.</para>
 320     </note>
 321     <para> To determine the total number of inodes, use <literal>lfs df -i</literal> (and also <literal>lctl get_param *.*.filestotal</literal>). For more information on using the <literal>lfs df -i</literal> command and the command output, see <xref linkend="dbdoclet.50438209_35838"/>.</para>
 322     <para>Unfortunately, the <literal>statfs</literal> interface does not report the free inode
 323       count directly, but instead reports the total inode and used inode counts. The free inode
 324       count is calculated for <literal>df</literal> from (total inodes - used inodes). It is not
 325       critical to know the total inode count for a file system. Instead, you should know
 326       (accurately), the free inode count and the used inode count for a file system. The Lustre
 327       software manipulates the total inode count in order to accurately report the other two
 328       values.</para>
 329   </section>
 330   <section xml:id="quota_interoperability">
 331     <title><indexterm><primary>Quotas</primary><secondary>Interoperability</secondary></indexterm>Interoperability</title>
 332     <para>The new quota protocol introduced in Lustre software release 2.4.0 <emphasis role="bold"
 333         >isn't compatible</emphasis> with the old one. As a consequence, <emphasis role="bold">all
 334         Lustre servers must be upgraded to release 2.4.0 for quota to be functional</emphasis>.
 335       Quota limits set on the Lustre file system prior to the upgrade will be automatically migrated
 336       to the new quota index format. As for accounting information with ldiskfs backend, they will
 337       be regenerated by running <literal>tunefs.lustre --quota</literal> against all targets. It is
 338       worth noting that running <literal>tunefs.lustre --quota</literal> is <emphasis role="bold"
 339         >mandatory</emphasis> for all targets formatted with a Lustre software release older than
 340       release 2.4.0, otherwise quota enforcement as well as accounting won't be functional.</para>
 341     <para>Besides, the quota protocol in release 2.4 takes for granted that the Lustre client
 342       supports the <literal>OBD_CONNECT_EINPROGRESS</literal> connect flag. Clients supporting this
 343       flag will retry indefinitely when the server returns <literal>EINPROGRESS</literal> in a
 344       reply. Here is the list of Lustre client version which are compatible with release 2.4:</para>
 345     <itemizedlist>
 346       <listitem>
 347         <para>Release 2.3-based clients and beyond</para>
 348       </listitem>
 349       <listitem>
 350         <para>Release 1.8 clients newer or equal to release 1.8.9-wc1</para>
 351       </listitem>
 352       <listitem>
 353         <para>Release 2.1 clients newer or equal to release 2.1.4</para>
 354       </listitem>
 355   </itemizedlist>
 356   </section>
 357   <section xml:id="granted_cache_and_quota_limits">
 358     <title><indexterm><primary>Quotas</primary><secondary>known issues</secondary></indexterm>Granted Cache and Quota Limits</title>
 359     <para>In a Lustre file system, granted cache does not respect quota limits. In this situation,
 360       OSTs grant cache to a Lustre client to accelerate I/O. Granting cache causes writes to be
 361       successful in OSTs, even if they exceed the quota limits, and will overwrite them.</para>
 362     <para>The sequence is:</para>
 363     <orderedlist>
 364       <listitem>
 365         <para>A user writes files to the Lustre file system.</para>
 366       </listitem>
 367       <listitem>
 368         <para>If the Lustre client has enough granted cache, then it returns &apos;success&apos; to users and arranges the writes to the OSTs.</para>
 369       </listitem>
 370       <listitem>
 371         <para>Because Lustre clients have delivered success to users, the OSTs cannot fail these writes.</para>
 372       </listitem>
 373     </orderedlist>
 374     <para>Because of granted cache, writes always overwrite quota limitations. For example, if you set a 400 GB quota on user A and use IOR to write for user A from a bundle of clients, you will write much more data than 400 GB, and cause an out-of-quota error (<literal>EDQUOT</literal>).</para>
 375     <note>
 376       <para>The effect of granted cache on quota limits can be mitigated, but not eradicated. Reduce the maximum amount of dirty data on the clients (minimal value is 1MB):</para>
 377       <itemizedlist>
 378         <listitem>
 379           <para><literal>lctl set_param osc.*.max_dirty_mb=8</literal></para>
 380         </listitem>
 381       </itemizedlist>
 382     </note>
 383   </section>
 384   <section xml:id="lustre_quota_statistics">
 385     <title><indexterm><primary>Quotas</primary><secondary>statistics</secondary></indexterm>Lustre Quota Statistics</title>
 386     <para>The Lustre software includes statistics that monitor quota activity, such as the kinds of
 387       quota RPCs sent during a specific period, the average time to complete the RPCs, etc. These
 388       statistics are useful to measure performance of a Lustre file system.</para>
 389     <para>Each quota statistic consists of a quota event and <literal>min_time</literal>, <literal>max_time</literal> and <literal>sum_time</literal> values for the event.</para>
 390     <informaltable frame="all">
 391       <tgroup cols="2">
 392         <colspec colname="c1" colwidth="50*"/>
 393         <colspec colname="c2" colwidth="50*"/>
 394         <thead>
 395           <row>
 396             <entry>
 397               <para><emphasis role="bold">Quota Event</emphasis></para>
 398             </entry>
 399             <entry>
 400               <para><emphasis role="bold">Description</emphasis></para>
 401             </entry>
 402           </row>
 403         </thead>
 404         <tbody>
 405           <row>
 406             <entry>
 407               <para> <emphasis role="bold">sync_acq_req</emphasis></para>
 408             </entry>
 409             <entry>
 410               <para> Quota slaves send a acquiring_quota request and wait for its return.</para>
 411             </entry>
 412           </row>
 413           <row>
 414             <entry>
 415               <para> <emphasis role="bold">sync_rel_req</emphasis></para>
 416             </entry>
 417             <entry>
 418               <para> Quota slaves send a releasing_quota request and wait for its return.</para>
 419             </entry>
 420           </row>
 421           <row>
 422             <entry>
 423               <para> <emphasis role="bold">async_acq_req</emphasis></para>
 424             </entry>
 425             <entry>
 426               <para> Quota slaves send an acquiring_quota request and do not wait for its return.</para>
 427             </entry>
 428           </row>
 429           <row>
 430             <entry>
 431               <para> <emphasis role="bold">async_rel_req</emphasis></para>
 432             </entry>
 433             <entry>
 434               <para> Quota slaves send a releasing_quota request and do not wait for its return.</para>
 435             </entry>
 436           </row>
 437           <row>
 438             <entry>
 439               <para> <emphasis role="bold">wait_for_blk_quota (lquota_chkquota)</emphasis></para>
 440             </entry>
 441             <entry>
 442               <para> Before data is written to OSTs, the OSTs check if the remaining block quota is sufficient. This is done in the lquota_chkquota function.</para>
 443             </entry>
 444           </row>
 445           <row>
 446             <entry>
 447               <para> <emphasis role="bold">wait_for_ino_quota (lquota_chkquota)</emphasis></para>
 448             </entry>
 449             <entry>
 450               <para> Before files are created on the MDS, the MDS checks if the remaining inode quota is sufficient. This is done in the lquota_chkquota function.</para>
 451             </entry>
 452           </row>
 453           <row>
 454             <entry>
 455               <para> <emphasis role="bold">wait_for_blk_quota (lquota_pending_commit)</emphasis></para>
 456             </entry>
 457             <entry>
 458               <para> After blocks are written to OSTs, relative quota information is updated. This is done in the lquota_pending_commit function.</para>
 459             </entry>
 460           </row>
 461           <row>
 462             <entry>
 463               <para> <emphasis role="bold">wait_for_ino_quota (lquota_pending_commit)</emphasis></para>
 464             </entry>
 465             <entry>
 466               <para> After files are created, relative quota information is updated. This is done in the lquota_pending_commit function.</para>
 467             </entry>
 468           </row>
 469           <row>
 470             <entry>
 471               <para> <emphasis role="bold">wait_for_pending_blk_quota_req (qctxt_wait_pending_dqacq)</emphasis></para>
 472             </entry>
 473             <entry>
 474               <para> On the MDS or OSTs, there is one thread sending a quota request for a specific UID/GID for block quota at any time. At that time, if other threads need to do this too, they should wait. This is done in the qctxt_wait_pending_dqacq function.</para>
 475             </entry>
 476           </row>
 477           <row>
 478             <entry>
 479               <para> <emphasis role="bold">wait_for_pending_ino_quota_req (qctxt_wait_pending_dqacq)</emphasis></para>
 480             </entry>
 481             <entry>
 482               <para> On the MDS, there is one thread sending a quota request for a specific UID/GID for inode quota at any time. If other threads need to do this too, they should wait. This is done in the qctxt_wait_pending_dqacq function.</para>
 483             </entry>
 484           </row>
 485           <row>
 486             <entry>
 487               <para> <emphasis role="bold">nowait_for_pending_blk_quota_req (qctxt_wait_pending_dqacq)</emphasis></para>
 488             </entry>
 489             <entry>
 490               <para> On the MDS or OSTs, there is one thread sending a quota request for a specific UID/GID for block quota at any time. When threads enter qctxt_wait_pending_dqacq, they do not need to wait. This is done in the qctxt_wait_pending_dqacq function.</para>
 491             </entry>
 492           </row>
 493           <row>
 494             <entry>
 495               <para> <emphasis role="bold">nowait_for_pending_ino_quota_req (qctxt_wait_pending_dqacq)</emphasis></para>
 496             </entry>
 497             <entry>
 498               <para> On the MDS, there is one thread sending a quota request for a specific UID/GID for inode quota at any time. When threads enter qctxt_wait_pending_dqacq, they do not need to wait. This is done in the qctxt_wait_pending_dqacq function.</para>
 499             </entry>
 500           </row>
 501           <row>
 502             <entry>
 503               <para> <emphasis role="bold">quota_ctl</emphasis></para>
 504             </entry>
 505             <entry>
 506               <para> The quota_ctl statistic is generated when lfs <literal>setquota</literal>, <literal>lfs quota</literal> and so on, are issued.</para>
 507             </entry>
 508           </row>
 509           <row>
 510             <entry>
 511               <para> <emphasis role="bold">adjust_qunit</emphasis></para>
 512             </entry>
 513             <entry>
 514               <para> Each time qunit is adjusted, it is counted.</para>
 515             </entry>
 516           </row>
 517         </tbody>
 518       </tgroup>
 519     </informaltable>
 520     <section remap="h3">
 521       <title>Interpreting Quota Statistics</title>
 522       <para>Quota statistics are an important measure of the performance of a Lustre file system.
 523         Interpreting these statistics correctly can help you diagnose problems with quotas, and may
 524         indicate adjustments to improve system performance.</para>
 525       <para>For example, if you run this command on the OSTs:</para>
 526       <screen>lctl get_param lquota.testfs-OST0000.stats</screen>
 527       <para>You will get a result similar to this:</para>
 528       <screen>snapshot_time                                1219908615.506895 secs.usecs
 529 async_acq_req                              1 samples [us]  32 32 32
 530 async_rel_req                              1 samples [us]  5 5 5
 531 nowait_for_pending_blk_quota_req(qctxt_wait_pending_dqacq) 1 samples [us] 2\
 532  2 2
 533 quota_ctl                          4 samples [us]  80 3470 4293
 534 adjust_qunit                               1 samples [us]  70 70 70
 535 ....</screen>
 536       <para>In the first line, <literal>snapshot_time</literal> indicates when the statistics were taken. The remaining lines list the quota events and their associated data.</para>
 537       <para>In the second line, the <literal>async_acq_req</literal> event occurs one time. The <literal>min_time</literal>, <literal>max_time</literal> and <literal>sum_time</literal> statistics for this event are 32, 32 and 32, respectively. The unit is microseconds (μs).</para>
 538       <para>In the fifth line, the quota_ctl event occurs four times. The <literal>min_time</literal>, <literal>max_time</literal> and <literal>sum_time</literal> statistics for this event are 80, 3470 and 4293, respectively. The unit is microseconds (μs).</para>
 539     </section>
 540   </section>
 541 </chapter>