ConfiguringQuotas.xml

   1 <?xml version='1.0' encoding='utf-8'?>
   2 <chapter xmlns="http://docbook.org/ns/docbook"
   3 xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en-US"
   4 xml:id="configuringquotas">
   5   <title xml:id="configuringquotas.title">Configuring and Managing
   6   Quotas</title>
   7   <section xml:id="quota_configuring">
   8     <title>
   9     <indexterm>
  10       <primary>Quotas</primary>
  11       <secondary>configuring</secondary>
  12     </indexterm>Working with Quotas</title>
  13     <para>Quotas allow a system administrator to limit the amount of disk space
  14     a user or group can use. Quotas are set by root, and can be specified for
  15     individual users and/or groups. Before a file is written to a partition
  16     where quotas are set, the quota of the creator's group is checked. If a
  17     quota exists, then the file size counts towards the group's quota. If no
  18     quota exists, then the owner's user quota is checked before the file is
  19     written. Similarly, inode usage for specific functions can be controlled if
  20     a user over-uses the allocated space.</para>
  21     <para>Lustre quota enforcement differs from standard Linux quota
  22     enforcement in several ways:</para>
  23     <itemizedlist>
  24       <listitem>
  25         <para>Quotas are administered via the
  26         <literal>lfs</literal> and
  27         <literal>lctl</literal> commands (post-mount).</para>
  28       </listitem>
  29       <listitem>
  30                 <para>The quota feature in Lustre software is distributed
  31         throughout the system (as the Lustre file system is a distributed file
  32         system). Because of this, quota setup and behavior on Lustre is
  33         different from local disk quotas in the following ways:</para>
  34         <itemizedlist>
  35         <listitem>
  36           <para>No single point of administration: some commands must be
  37           executed on the MGS, other commands on the MDSs and OSSs, and still
  38           other commands on the client.</para>
  39           </listitem>
  40           <listitem>
  41           <para>Granularity: a local quota is typically specified for
  42           kilobyte resolution, Lustre uses one megabyte as the smallest quota
  43           resolution.</para>
  44           </listitem>
  45           <listitem>
  46           <para>Accuracy: quota information is distributed throughout
  47 the file system and can only be accurately calculated with a completely
  48 quite file system.</para>
  49         </listitem>
  50         </itemizedlist>
  51       </listitem>
  52       <listitem>
  53         <para>Quotas are allocated and consumed in a quantized fashion.</para>
  54       </listitem>
  55       <listitem>
  56         <para>Client does not set the
  57         <literal>usrquota</literal> or
  58         <literal>grpquota</literal> options to mount. As of Lustre software
  59         release 2.4, space accounting is always enabled by default and quota
  60         enforcement can be enabled/disabled on a per-file system basis with
  61         <literal>lctl conf_param</literal>. It is worth noting that both
  62         <literal>lfs quotaon</literal> and
  63         <literal>quota_type</literal> are deprecated as of Lustre software
  64         release 2.4.0.</para>
  65       </listitem>
  66     </itemizedlist>
  67     <caution>
  68       <para>Although a quota feature is available in the Lustre software, root
  69       quotas are NOT enforced.</para>
  70       <para>
  71       <literal>lfs setquota -u root</literal> (limits are not enforced)</para>
  72       <para>
  73       <literal>lfs quota -u root</literal> (usage includes internal Lustre data
  74       that is dynamic in size and does not accurately reflect mount point
  75       visible block and inode usage).</para>
  76     </caution>
  77   </section>
  78   <section xml:id="enabling_disk_quotas">
  79     <title>
  80     <indexterm>
  81       <primary>Quotas</primary>
  82       <secondary>enabling disk</secondary>
  83     </indexterm>Enabling Disk Quotas</title>
  84     <para>The design of quotas on Lustre has management and enforcement
  85     separated from resource usage and accounting. Lustre software is
  86     responsible for management and enforcement. The back-end file
  87     system is responsible for resource usage and accounting. Because of
  88     this, it is necessary to begin enabling quotas by enabling quotas on the
  89     back-end disk system. Because quota setup is dependent on the Lustre
  90     software version in use, you may first need to run
  91     <literal>lctl get_param version</literal> to identify
  92     <xref linkend="whichversion"/> you are currently using.
  93     </para>
  94     <section>
  95       <title>Enabling Disk Quotas (Lustre Software Prior to Release 2.4)
  96       </title>
  97       <para>
  98       For Lustre software releases older than release 2.4,
  99       <literal>lfs quotacheck</literal> must be first run from a client node to
 100       create quota files on the Lustre targets (i.e. the MDT and OSTs).
 101       <literal>lfs quotacheck</literal> requires the file system to be quiescent
 102       (i.e. no modifying operations like write, truncate, create or delete
 103       should run concurrently). Failure to follow this caution may result in
 104       inaccurate user/group disk usage. Operations that do not change Lustre
 105       files (such as read or mount) are okay to run.
 106       <literal>lfs quotacheck</literal> performs a scan on all the Lustre
 107       targets to calculates the block/inode usage for each user/group. If the
 108       Lustre file system has many files,
 109       <literal>quotacheck</literal> may take a long time to complete. Several
 110       options can be passed to
 111       <literal>lfs quotacheck</literal>:</para>
 112       <screen>
 113 # lfs quotacheck -ug /mnt/testfs
 114 </screen>
 115       <itemizedlist>
 116         <listitem>
 117           <para>
 118           <literal>u</literal>-- checks the user disk quota information</para>
 119         </listitem>
 120         <listitem>
 121           <para>
 122           <literal>g</literal>-- checks the group disk quota information</para>
 123         </listitem>
 124       </itemizedlist>
 125       <para>By default, quota is turned on after
 126       <literal>quotacheck</literal> completes. However, this setting isn't
 127       persistent and quota will have to be enabled again (via
 128       <literal>lfs quotaon</literal>) if one of the Lustre targets is
 129       restarted.
 130       <literal>lfs quotaoff</literal> is used to turn off quota.</para>
 131       <para>To enable quota permanently with a Lustre software release older
 132       than release 2.4, the
 133       <literal>quota_type</literal> parameter must be used. This requires
 134       setting
 135       <literal>mdd.quota_type</literal> and
 136       <literal>ost.quota_type</literal>, respectively, on the MDT and OSTs.
 137       <literal>quota_type</literal> can be set to the string
 138       <literal>u</literal> (user),
 139       <literal>g</literal> (group) or
 140       <literal>ug</literal> for both users and groups. This parameter can be
 141       specified at
 142       <literal>mkfs</literal> time (
 143       <literal>mkfs.lustre --param mdd.quota_type=ug</literal>) or with
 144       <literal>tunefs.lustre</literal>. As an example:</para>
 145       <screen>
 146 tunefs.lustre --param ost.quota_type=ug $ost_dev
 147 </screen>
 148       <para>When using
 149       <literal>mkfs.lustre --param mdd.quota_type=ug</literal> or
 150       <literal>tunefs.lustre --param ost.quota_type=ug</literal>, be sure to
 151       run the command on all OSTs and the MDT. Otherwise, abnormal results may
 152       occur.</para>
 153       <warning>
 154         <para>
 155         In Lustre software releases before 2.4, when new OSTs are
 156         added to the file system, quotas are not automatically propagated to
 157         the new OSTs. As a workaround, clear and then reset quotas for each
 158         user or group using the
 159         <literal>lfs setquota</literal> command. In the example below, quotas
 160         are cleared and reset for user
 161         <literal>bob</literal> on file system
 162         <literal>testfs</literal>:
 163         <screen>
 164 $ lfs setquota -u bob -b 0 -B 0 -i 0 -I 0 /mnt/testfs
 165 $ lfs setquota -u bob -b 307200 -B 309200 -i 10000 -I 11000 /mnt/testfs
 166 </screen></para>
 167       </warning>
 168     </section>
 169     <section remap="h3" condition="l24">
 170       <title>Enabling Disk Quotas (Lustre Software Release 2.4 and
 171       later)</title>
 172           <para>Quota setup is orchestrated by the MGS and <emphasis>all setup
 173       commands in this section must be run on the MGS</emphasis>. Once setup,
 174       verification of the quota state must be performed on the MDT. Although
 175       quota enforcement is managed by the Lustre software, each OSD
 176       implementation relies on the back-end file system to maintain
 177       per-user/group block and inode usage. Hence, differences exist
 178       when setting up quotas with ldiskfs or ZFS back-ends:</para>
 179       <itemizedlist>
 180         <listitem>
 181           <para>For ldiskfs backends,
 182           <literal>mkfs.lustre</literal> now creates empty quota files and
 183           enables the QUOTA feature flag in the superblock which turns quota
 184           accounting on at mount time automatically. e2fsck was also modified
 185           to fix the quota files when the QUOTA feature flag is present.</para>
 186         </listitem>
 187         <listitem>
 188           <para>For ZFS backend, accounting ZAPs are created and maintained by
 189           the ZFS file system itself. While ZFS tracks per-user and group block
 190           usage, it does not handle inode accounting. The ZFS OSD implements
 191           its own support for inode tracking. Two options are available:</para>
 192           <orderedlist>
 193             <listitem>
 194               <para>The ZFS OSD can estimate the number of inodes in-use based
 195               on the number of blocks used by a given user or group. This mode
 196               can be enabled by running the following command on the server
 197               running the target:
 198               <literal>lctl set_param
 199               osd-zfs.${FSNAME}-${TARGETNAME}.quota_iused_estimate=1</literal>.</para>
 200             </listitem>
 201             <listitem>
 202               <para>Similarly to block accounting, dedicated ZAPs are also
 203               created the ZFS OSD to maintain per-user and group inode usage.
 204               This is the default mode which corresponds to
 205               <literal>quota_iused_estimate</literal> set to 0.</para>
 206             </listitem>
 207           </orderedlist>
 208         </listitem>
 209       </itemizedlist>
 210       <note>
 211       <para>Lustre file systems formatted with a Lustre release prior to 2.4.0
 212       can be still safely upgraded to release 2.4.0, but will not have
 213       functional space usage report until
 214       <literal>tunefs.lustre --quota</literal> is run against all targets. This
 215       command sets the QUOTA feature flag in the superblock and runs e2fsck (as
 216       a result, the target must be offline) to build the per-UID/GID disk usage
 217       database. See <xref linkend="quota_interoperability"/> for further
 218       important considerations.</para>
 219       </note>
 220       <caution>
 221         <para>Lustre software release 2.4 and later requires a version of
 222         e2fsprogs that supports quota (i.e. newer or equal to 1.42.3.wc1) to be
 223         installed on the server nodes using ldiskfs backend (e2fsprogs is not
 224         needed with ZFS backend). In general, we recommend to use the latest
 225         e2fsprogs version available on
 226         <link xl:href="http://downloads.hpdd.intel.com/e2fsprogs/">
 227         http://downloads.hpdd.intel.com/public/e2fsprogs/</link>.</para>
 228         <para>The ldiskfs OSD relies on the standard Linux quota to maintain
 229         accounting information on disk. As a consequence, the Linux kernel
 230         running on the Lustre servers using ldiskfs backend must have
 231         <literal>CONFIG_QUOTA</literal>,
 232         <literal>CONFIG_QUOTACTL</literal> and
 233         <literal>CONFIG_QFMT_V2</literal> enabled.</para>
 234       </caution>
 235       <para>As of Lustre software release 2.4.0, quota enforcement is thus
 236       turned on/off independently of space accounting which is always enabled.
 237       <literal>lfs quota
 238       <replaceable>on|off</replaceable></literal> as well as the per-target
 239       <literal>quota_type</literal> parameter are deprecated in favor of a
 240       single per-file system quota parameter controlling inode/block quota
 241       enforcement. Like all permanent parameters, this quota parameter can be
 242       set via
 243       <literal>lctl conf_param</literal> on the MGS via the following
 244       syntax:</para>
 245       <screen>
 246 lctl conf_param <replaceable>fsname</replaceable>.quota.<replaceable>ost|mdt</replaceable>=<replaceable>u|g|ug|none</replaceable>
 247 </screen>
 248       <itemizedlist>
 249         <listitem>
 250           <para>
 251           <literal>ost</literal> -- to configure block quota managed by
 252           OSTs</para>
 253         </listitem>
 254         <listitem>
 255           <para>
 256           <literal>mdt</literal> -- to configure inode quota managed by
 257           MDTs</para>
 258         </listitem>
 259         <listitem>
 260           <para>
 261           <literal>u</literal> -- to enable quota enforcement for users
 262           only</para>
 263         </listitem>
 264         <listitem>
 265           <para>
 266           <literal>g</literal> -- to enable quota enforcement for groups
 267           only</para>
 268         </listitem>
 269         <listitem>
 270           <para>
 271           <literal>ug</literal> -- to enable quota enforcement for both users
 272           and groups</para>
 273         </listitem>
 274         <listitem>
 275           <para>
 276           <literal>none</literal> -- to disable quota enforcement for both users
 277           and groups</para>
 278         </listitem>
 279       </itemizedlist>
 280       <para>Examples:</para>
 281       <para>To turn on user and group quotas for block only on file system
 282       <literal>testfs1</literal>, <emphasis>on the MGS</emphasis> run:</para>
 283       <screen>$ lctl conf_param testfs1.quota.ost=ug
 284 </screen>
 285       <para>To turn on group quotas for inodes on file system
 286       <literal>testfs2</literal>, on the MGS run:</para>
 287       <screen>$ lctl conf_param testfs2.quota.mdt=g
 288 </screen>
 289       <para>To turn off user and group quotas for both inode and block on file
 290       system
 291       <literal>testfs3</literal>, on the MGS run:</para>
 292       <screen>$ lctl conf_param testfs3.quota.ost=none
 293 </screen>
 294       <screen>$ lctl conf_param testfs3.quota.mdt=none
 295 </screen>
 296       <section>
 297             <title>
 298             <indexterm>
 299               <primary>Quotas</primary>
 300               <secondary>verifying</secondary>
 301             </indexterm>Quota Verification</title>
 302           <para>Once the quota parameters have been configured, all targets
 303       which are part of the file system will be automatically notified of the
 304       new quota settings and enable/disable quota enforcement as needed. The
 305       per-target enforcement status can still be verified by running the
 306       following <emphasis>command on the MDS(s)</emphasis>:</para>
 307       <screen>
 308 $ lctl get_param osd-*.*.quota_slave.info
 309 osd-zfs.testfs-MDT0000.quota_slave.info=
 310 target name:    testfs-MDT0000
 311 pool ID:        0
 312 type:           md
 313 quota enabled:  ug
 314 conn to master: setup
 315 user uptodate:  glb[1],slv[1],reint[0]
 316 group uptodate: glb[1],slv[1],reint[0]
 317 </screen>
 318       </section>
 319     </section>
 320   </section>
 321   <section xml:id="quota_administration">
 322     <title>
 323     <indexterm>
 324       <primary>Quotas</primary>
 325       <secondary>creating</secondary>
 326     </indexterm>Quota Administration</title>
 327         <para>Once the file system is up and running, quota limits on blocks
 328     and inodes can be set for both user and group. This is <emphasis>
 329     controlled entirely from a client</emphasis> via three quota
 330     parameters:</para>
 331     <para>
 332     <emphasis role="bold">Grace period</emphasis>-- The period of time (in
 333     seconds) within which users are allowed to exceed their soft limit. There
 334     are four types of grace periods:</para>
 335     <itemizedlist>
 336       <listitem>
 337         <para>user block soft limit</para>
 338       </listitem>
 339       <listitem>
 340         <para>user inode soft limit</para>
 341       </listitem>
 342       <listitem>
 343         <para>group block soft limit</para>
 344       </listitem>
 345       <listitem>
 346         <para>group inode soft limit</para>
 347       </listitem>
 348     </itemizedlist>
 349     <para>The grace period applies to all users. The user block soft limit is
 350     for all users who are using a blocks quota.</para>
 351     <para>
 352     <emphasis role="bold">Soft limit</emphasis> -- The grace timer is started
 353     once the soft limit is exceeded. At this point, the user/group can still
 354     allocate block/inode. When the grace time expires and if the user is still
 355     above the soft limit, the soft limit becomes a hard limit and the
 356     user/group can't allocate any new block/inode any more. The user/group
 357     should then delete files to be under the soft limit. The soft limit MUST be
 358     smaller than the hard limit. If the soft limit is not needed, it should be
 359     set to zero (0).</para>
 360     <para>
 361     <emphasis role="bold">Hard limit</emphasis> -- Block or inode allocation
 362     will fail with
 363     <literal>EDQUOT</literal>(i.e. quota exceeded) when the hard limit is
 364     reached. The hard limit is the absolute limit. When a grace period is set,
 365     one can exceed the soft limit within the grace period if under the hard
 366     limit.</para>
 367     <para>Due to the distributed nature of a Lustre file system and the need to
 368     maintain performance under load, those quota parameters may not be 100%
 369     accurate. The quota settings can be manipulated via the
 370     <literal>lfs</literal> command, executed on a client, and includes several
 371     options to work with quotas:</para>
 372     <itemizedlist>
 373       <listitem>
 374         <para>
 375         <varname>quota</varname> -- displays general quota information (disk
 376         usage and limits)</para>
 377       </listitem>
 378       <listitem>
 379         <para>
 380         <varname>setquota</varname> -- specifies quota limits and tunes the
 381         grace period. By default, the grace period is one week.</para>
 382       </listitem>
 383     </itemizedlist>
 384     <para>Usage:</para>
 385     <screen>
 386 lfs quota [-q] [-v] [-h] [-o obd_uuid] [-u|-g <replaceable>uname|uid|gname|gid</replaceable>] <replaceable>/mount_point</replaceable>
 387 lfs quota -t <replaceable>-u|-g</replaceable> <replaceable>/mount_point</replaceable>
 388 lfs setquota <replaceable>-u|--user|-g|--group</replaceable> <replaceable>username|groupname</replaceable> [-b <replaceable>block-softlimit</replaceable>] \
 389              [-B <replaceable>block_hardlimit</replaceable>] [-i <replaceable>inode_softlimit</replaceable>] \
 390              [-I <replaceable>inode_hardlimit</replaceable>] <replaceable>/mount_point</replaceable>
 391 </screen>
 392     <para>To display general quota information (disk usage and limits) for the
 393     user running the command and his primary group, run:</para>
 394     <screen>
 395 $ lfs quota /mnt/testfs
 396 </screen>
 397     <para>To display general quota information for a specific user ("
 398     <literal>bob</literal>" in this example), run:</para>
 399     <screen>
 400 $ lfs quota -u bob /mnt/testfs
 401 </screen>
 402     <para>To display general quota information for a specific user ("
 403     <literal>bob</literal>" in this example) and detailed quota statistics for
 404     each MDT and OST, run:</para>
 405     <screen>
 406 $ lfs quota -u bob -v /mnt/testfs
 407 </screen>
 408     <para>To display general quota information for a specific group ("
 409     <literal>eng</literal>" in this example), run:</para>
 410     <screen>
 411 $ lfs quota -g eng /mnt/testfs
 412 </screen>
 413     <para>To display block and inode grace times for user quotas, run:</para>
 414     <screen>
 415 $ lfs quota -t -u /mnt/testfs
 416 </screen>
 417     <para>To set user or group quotas for a specific ID ("bob" in this
 418     example), run:</para>
 419     <screen>
 420 $ lfs setquota -u bob -b 307200 -B 309200 -i 10000 -I 11000 /mnt/testfs
 421 </screen>
 422     <para>In this example, the quota for user "bob" is set to 300 MB
 423     (309200*1024) and the hard limit is 11,000 files. Therefore, the inode hard
 424     limit should be 11000.</para>
 425     <para>The quota command displays the quota allocated and consumed by each
 426     Lustre target. Using the previous
 427     <literal>setquota</literal> example, running this
 428     <literal>lfs</literal> quota command:</para>
 429     <screen>
 430 $ lfs quota -u bob -v /mnt/testfs
 431 </screen>
 432     <para>displays this command output:</para>
 433     <screen>
 434 Disk quotas for user bob (uid 6000):
 435 Filesystem          kbytes quota limit grace files quota limit grace
 436 /mnt/testfs         0      30720 30920 -     0     10000 11000 -
 437 testfs-MDT0000_UUID 0      -      8192 -     0     -     2560  -
 438 testfs-OST0000_UUID 0      -      8192 -     0     -     0     -
 439 testfs-OST0001_UUID 0      -      8192 -     0     -     0     -
 440 Total allocated inode limit: 2560, total allocated block limit: 24576
 441 </screen>
 442     <para>Global quota limits are stored in dedicated index files (there is one
 443     such index per quota type) on the quota master target (aka QMT). The QMT
 444     runs on MDT0000 and exports the global indexes via /proc. The global
 445     indexes can thus be dumped via the following command:
 446     <screen>
 447 # lctl get_param qmt.testfs-QMT0000.*.glb-*
 448 </screen>The format of global indexes depends on the OSD type. The ldiskfs OSD
 449 uses an IAM files while the ZFS OSD creates dedicated ZAPs.</para>
 450     <para>Each slave also stores a copy of this global index locally. When the
 451     global index is modified on the master, a glimpse callback is issued on the
 452     global quota lock to notify all slaves that the global index has been
 453     modified. This glimpse callback includes information about the identifier
 454     subject to the change. If the global index on the QMT is modified while a
 455     slave is disconnected, the index version is used to determine whether the
 456     slave copy of the global index isn't up to date any more. If so, the slave
 457     fetches the whole index again and updates the local copy. The slave copy of
 458     the global index is also exported via /proc and can be accessed via the
 459     following command:
 460     <screen>
 461 lctl get_param osd-*.*.quota_slave.limit*
 462 </screen></para>
 463     <note>
 464       <para>Prior to 2.4, global quota limits used to be stored in
 465       administrative quota files using the on-disk format of the linux quota
 466       file. When upgrading MDT0000 to 2.4, those administrative quota files are
 467       converted into IAM indexes automatically, conserving existing quota
 468       limits previously set by the administrator.</para>
 469     </note>
 470   </section>
 471   <section xml:id="quota_allocation">
 472     <title>
 473     <indexterm>
 474       <primary>Quotas</primary>
 475       <secondary>allocating</secondary>
 476     </indexterm>Quota Allocation</title>
 477     <para>In a Lustre file system, quota must be properly allocated or users
 478     may experience unnecessary failures. The file system block quota is divided
 479     up among the OSTs within the file system. Each OST requests an allocation
 480     which is increased up to the quota limit. The quota allocation is then
 481     <emphasis role="italic">quantized</emphasis> to reduce the number of
 482     quota-related request traffic.</para>
 483     <para>The Lustre quota system distributes quotas from the Quota Master
 484     Target (aka QMT). Only one QMT instance is supported for now and only runs
 485     on the same node as MDT0000. All OSTs and MDTs set up a Quota Slave Device
 486     (aka QSD) which connects to the QMT to allocate/release quota space. The
 487     QSD is setup directly from the OSD layer.</para>
 488     <para>To reduce quota requests, quota space is initially allocated to QSDs
 489     in very large chunks. How much unused quota space can be hold by a target
 490     is controlled by the qunit size. When quota space for a given ID is close
 491     to exhaustion on the QMT, the qunit size is reduced and QSDs are notified
 492     of the new qunit size value via a glimpse callback. Slaves are then
 493     responsible for releasing quota space above the new qunit value. The qunit
 494     size isn't shrunk indefinitely and there is a minimal value of 1MB for
 495     blocks and 1,024 for inodes. This means that the quota space rebalancing
 496     process will stop when this minimum value is reached. As a result, quota
 497     exceeded can be returned while many slaves still have 1MB or 1,024 inodes
 498     of spare quota space.</para>
 499     <para>If we look at the
 500     <literal>setquota</literal> example again, running this
 501     <literal>lfs quota</literal> command:</para>
 502     <screen>
 503 # lfs quota -u bob -v /mnt/testfs
 504 </screen>
 505     <para>displays this command output:</para>
 506     <screen>
 507 Disk quotas for user bob (uid 500):
 508 Filesystem          kbytes quota limit grace       files  quota limit grace
 509 /mnt/testfs         30720* 30720 30920 6d23h56m44s 10101* 10000 11000
 510 6d23h59m50s
 511 testfs-MDT0000_UUID 0      -     0     -           10101  -     10240
 512 testfs-OST0000_UUID 0      -     1024  -           -      -     -
 513 testfs-OST0001_UUID 30720* -     29896 -           -      -     -
 514 Total allocated inode limit: 10240, total allocated block limit: 30920
 515 </screen>
 516     <para>The total quota limit of 30,920 is allocated to user bob, which is
 517     further distributed to two OSTs.</para>
 518     <para>Values appended with '
 519     <literal>*</literal>' show that the quota limit has been exceeded, causing
 520     the following error when trying to write or create a file:</para>
 521     <para>
 522       <screen>
 523 $ cp: writing `/mnt/testfs/foo`: Disk quota exceeded.
 524 </screen>
 525     </para>
 526     <note>
 527       <para>It is very important to note that the block quota is consumed per
 528       OST and the inode quota per MDS. Therefore, when the quota is consumed on
 529       one OST (resp. MDT), the client may not be able to create files
 530       regardless of the quota available on other OSTs (resp. MDTs).</para>
 531       <para>Setting the quota limit below the minimal qunit size may prevent
 532       the user/group from all file creation. It is thus recommended to use
 533       soft/hard limits which are a multiple of the number of OSTs * the minimal
 534       qunit size.</para>
 535     </note>
 536     <para>To determine the total number of inodes, use
 537     <literal>lfs df -i</literal>(and also
 538     <literal>lctl get_param *.*.filestotal</literal>). For more information on
 539     using the
 540     <literal>lfs df -i</literal> command and the command output, see
 541     <xref linkend="dbdoclet.50438209_35838" />.</para>
 542     <para>Unfortunately, the
 543     <literal>statfs</literal> interface does not report the free inode count
 544     directly, but instead reports the total inode and used inode counts. The
 545     free inode count is calculated for
 546     <literal>df</literal> from (total inodes - used inodes). It is not critical
 547     to know the total inode count for a file system. Instead, you should know
 548     (accurately), the free inode count and the used inode count for a file
 549     system. The Lustre software manipulates the total inode count in order to
 550     accurately report the other two values.</para>
 551   </section>
 552   <section xml:id="quota_interoperability">
 553     <title>
 554     <indexterm>
 555       <primary>Quotas</primary>
 556       <secondary>Interoperability</secondary>
 557     </indexterm>Quotas and Version Interoperability</title>
 558     <para>The new quota protocol introduced in Lustre software release 2.4.0
 559     <emphasis role="bold">is not compatible</emphasis> with previous
 560     versions. As a consequence,
 561     <emphasis role="bold">all Lustre servers must be upgraded to release 2.4.0
 562     for quota to be functional</emphasis>. Quota limits set on the Lustre file
 563     system prior to the upgrade will be automatically migrated to the new quota
 564     index format. As for accounting information with ldiskfs backend, they will
 565     be regenerated by running
 566     <literal>tunefs.lustre --quota</literal> against all targets. It is worth
 567     noting that running
 568     <literal>tunefs.lustre --quota</literal> is
 569     <emphasis role="bold">mandatory</emphasis> for all targets formatted with a
 570     Lustre software release older than release 2.4.0, otherwise quota
 571     enforcement as well as accounting won't be functional.</para>
 572     <para>Besides, the quota protocol in release 2.4 takes for granted that the
 573     Lustre client supports the
 574     <literal>OBD_CONNECT_EINPROGRESS</literal> connect flag. Clients supporting
 575     this flag will retry indefinitely when the server returns
 576     <literal>EINPROGRESS</literal> in a reply. Here is the list of Lustre client
 577     version which are compatible with release 2.4:</para>
 578     <itemizedlist>
 579       <listitem>
 580         <para>Release 2.3-based clients and later</para>
 581       </listitem>
 582       <listitem>
 583         <para>Release 1.8 clients newer or equal to release 1.8.9-wc1</para>
 584       </listitem>
 585       <listitem>
 586         <para>Release 2.1 clients newer or equal to release 2.1.4</para>
 587       </listitem>
 588     </itemizedlist>
 589   </section>
 590   <section xml:id="granted_cache_and_quota_limits">
 591     <title>
 592     <indexterm>
 593       <primary>Quotas</primary>
 594       <secondary>known issues</secondary>
 595     </indexterm>Granted Cache and Quota Limits</title>
 596     <para>In a Lustre file system, granted cache does not respect quota limits.
 597     In this situation, OSTs grant cache to a Lustre client to accelerate I/O.
 598     Granting cache causes writes to be successful in OSTs, even if they exceed
 599     the quota limits, and will overwrite them.</para>
 600     <para>The sequence is:</para>
 601     <orderedlist>
 602       <listitem>
 603         <para>A user writes files to the Lustre file system.</para>
 604       </listitem>
 605       <listitem>
 606         <para>If the Lustre client has enough granted cache, then it returns
 607         'success' to users and arranges the writes to the OSTs.</para>
 608       </listitem>
 609       <listitem>
 610         <para>Because Lustre clients have delivered success to users, the OSTs
 611         cannot fail these writes.</para>
 612       </listitem>
 613     </orderedlist>
 614     <para>Because of granted cache, writes always overwrite quota limitations.
 615     For example, if you set a 400 GB quota on user A and use IOR to write for
 616     user A from a bundle of clients, you will write much more data than 400 GB,
 617     and cause an out-of-quota error (
 618     <literal>EDQUOT</literal>).</para>
 619     <note>
 620       <para>The effect of granted cache on quota limits can be mitigated, but
 621       not eradicated. Reduce the maximum amount of dirty data on the clients
 622       (minimal value is 1MB):</para>
 623       <itemizedlist>
 624         <listitem>
 625           <para>
 626             <literal>lctl set_param osc.*.max_dirty_mb=8</literal>
 627           </para>
 628         </listitem>
 629       </itemizedlist>
 630     </note>
 631   </section>
 632   <section xml:id="lustre_quota_statistics">
 633     <title>
 634     <indexterm>
 635       <primary>Quotas</primary>
 636       <secondary>statistics</secondary>
 637     </indexterm>Lustre Quota Statistics</title>
 638     <para>The Lustre software includes statistics that monitor quota activity,
 639     such as the kinds of quota RPCs sent during a specific period, the average
 640     time to complete the RPCs, etc. These statistics are useful to measure
 641     performance of a Lustre file system.</para>
 642     <para>Each quota statistic consists of a quota event and
 643     <literal>min_time</literal>,
 644     <literal>max_time</literal> and
 645     <literal>sum_time</literal> values for the event.</para>
 646     <informaltable frame="all">
 647       <tgroup cols="2">
 648         <colspec colname="c1" colwidth="50*" />
 649         <colspec colname="c2" colwidth="50*" />
 650         <thead>
 651           <row>
 652             <entry>
 653               <para>
 654                 <emphasis role="bold">Quota Event</emphasis>
 655               </para>
 656             </entry>
 657             <entry>
 658               <para>
 659                 <emphasis role="bold">Description</emphasis>
 660               </para>
 661             </entry>
 662           </row>
 663         </thead>
 664         <tbody>
 665           <row>
 666             <entry>
 667               <para>
 668                 <emphasis role="bold">sync_acq_req</emphasis>
 669               </para>
 670             </entry>
 671             <entry>
 672               <para>Quota slaves send a acquiring_quota request and wait for
 673               its return.</para>
 674             </entry>
 675           </row>
 676           <row>
 677             <entry>
 678               <para>
 679                 <emphasis role="bold">sync_rel_req</emphasis>
 680               </para>
 681             </entry>
 682             <entry>
 683               <para>Quota slaves send a releasing_quota request and wait for
 684               its return.</para>
 685             </entry>
 686           </row>
 687           <row>
 688             <entry>
 689               <para>
 690                 <emphasis role="bold">async_acq_req</emphasis>
 691               </para>
 692             </entry>
 693             <entry>
 694               <para>Quota slaves send an acquiring_quota request and do not
 695               wait for its return.</para>
 696             </entry>
 697           </row>
 698           <row>
 699             <entry>
 700               <para>
 701                 <emphasis role="bold">async_rel_req</emphasis>
 702               </para>
 703             </entry>
 704             <entry>
 705               <para>Quota slaves send a releasing_quota request and do not wait
 706               for its return.</para>
 707             </entry>
 708           </row>
 709           <row>
 710             <entry>
 711               <para>
 712                 <emphasis role="bold">wait_for_blk_quota
 713                 (lquota_chkquota)</emphasis>
 714               </para>
 715             </entry>
 716             <entry>
 717               <para>Before data is written to OSTs, the OSTs check if the
 718               remaining block quota is sufficient. This is done in the
 719               lquota_chkquota function.</para>
 720             </entry>
 721           </row>
 722           <row>
 723             <entry>
 724               <para>
 725                 <emphasis role="bold">wait_for_ino_quota
 726                 (lquota_chkquota)</emphasis>
 727               </para>
 728             </entry>
 729             <entry>
 730               <para>Before files are created on the MDS, the MDS checks if the
 731               remaining inode quota is sufficient. This is done in the
 732               lquota_chkquota function.</para>
 733             </entry>
 734           </row>
 735           <row>
 736             <entry>
 737               <para>
 738                 <emphasis role="bold">wait_for_blk_quota
 739                 (lquota_pending_commit)</emphasis>
 740               </para>
 741             </entry>
 742             <entry>
 743               <para>After blocks are written to OSTs, relative quota
 744               information is updated. This is done in the lquota_pending_commit
 745               function.</para>
 746             </entry>
 747           </row>
 748           <row>
 749             <entry>
 750               <para>
 751                 <emphasis role="bold">wait_for_ino_quota
 752                 (lquota_pending_commit)</emphasis>
 753               </para>
 754             </entry>
 755             <entry>
 756               <para>After files are created, relative quota information is
 757               updated. This is done in the lquota_pending_commit
 758               function.</para>
 759             </entry>
 760           </row>
 761           <row>
 762             <entry>
 763               <para>
 764                 <emphasis role="bold">wait_for_pending_blk_quota_req
 765                 (qctxt_wait_pending_dqacq)</emphasis>
 766               </para>
 767             </entry>
 768             <entry>
 769               <para>On the MDS or OSTs, there is one thread sending a quota
 770               request for a specific UID/GID for block quota at any time. At
 771               that time, if other threads need to do this too, they should
 772               wait. This is done in the qctxt_wait_pending_dqacq
 773               function.</para>
 774             </entry>
 775           </row>
 776           <row>
 777             <entry>
 778               <para>
 779                 <emphasis role="bold">wait_for_pending_ino_quota_req
 780                 (qctxt_wait_pending_dqacq)</emphasis>
 781               </para>
 782             </entry>
 783             <entry>
 784               <para>On the MDS, there is one thread sending a quota request for
 785               a specific UID/GID for inode quota at any time. If other threads
 786               need to do this too, they should wait. This is done in the
 787               qctxt_wait_pending_dqacq function.</para>
 788             </entry>
 789           </row>
 790           <row>
 791             <entry>
 792               <para>
 793                 <emphasis role="bold">nowait_for_pending_blk_quota_req
 794                 (qctxt_wait_pending_dqacq)</emphasis>
 795               </para>
 796             </entry>
 797             <entry>
 798               <para>On the MDS or OSTs, there is one thread sending a quota
 799               request for a specific UID/GID for block quota at any time. When
 800               threads enter qctxt_wait_pending_dqacq, they do not need to wait.
 801               This is done in the qctxt_wait_pending_dqacq function.</para>
 802             </entry>
 803           </row>
 804           <row>
 805             <entry>
 806               <para>
 807                 <emphasis role="bold">nowait_for_pending_ino_quota_req
 808                 (qctxt_wait_pending_dqacq)</emphasis>
 809               </para>
 810             </entry>
 811             <entry>
 812               <para>On the MDS, there is one thread sending a quota request for
 813               a specific UID/GID for inode quota at any time. When threads
 814               enter qctxt_wait_pending_dqacq, they do not need to wait. This is
 815               done in the qctxt_wait_pending_dqacq function.</para>
 816             </entry>
 817           </row>
 818           <row>
 819             <entry>
 820               <para>
 821                 <emphasis role="bold">quota_ctl</emphasis>
 822               </para>
 823             </entry>
 824             <entry>
 825               <para>The quota_ctl statistic is generated when lfs
 826               <literal>setquota</literal>,
 827               <literal>lfs quota</literal> and so on, are issued.</para>
 828             </entry>
 829           </row>
 830           <row>
 831             <entry>
 832               <para>
 833                 <emphasis role="bold">adjust_qunit</emphasis>
 834               </para>
 835             </entry>
 836             <entry>
 837               <para>Each time qunit is adjusted, it is counted.</para>
 838             </entry>
 839           </row>
 840         </tbody>
 841       </tgroup>
 842     </informaltable>
 843     <section remap="h3">
 844       <title>Interpreting Quota Statistics</title>
 845       <para>Quota statistics are an important measure of the performance of a
 846       Lustre file system. Interpreting these statistics correctly can help you
 847       diagnose problems with quotas, and may indicate adjustments to improve
 848       system performance.</para>
 849       <para>For example, if you run this command on the OSTs:</para>
 850       <screen>
 851 lctl get_param lquota.testfs-OST0000.stats
 852 </screen>
 853       <para>You will get a result similar to this:</para>
 854       <screen>
 855 snapshot_time                                1219908615.506895 secs.usecs
 856 async_acq_req                              1 samples [us]  32 32 32
 857 async_rel_req                              1 samples [us]  5 5 5
 858 nowait_for_pending_blk_quota_req(qctxt_wait_pending_dqacq) 1 samples [us] 2\
 859  2 2
 860 quota_ctl                          4 samples [us]  80 3470 4293
 861 adjust_qunit                               1 samples [us]  70 70 70
 862 ....
 863 </screen>
 864       <para>In the first line,
 865       <literal>snapshot_time</literal> indicates when the statistics were taken.
 866       The remaining lines list the quota events and their associated
 867       data.</para>
 868       <para>In the second line, the
 869       <literal>async_acq_req</literal> event occurs one time. The
 870       <literal>min_time</literal>,
 871       <literal>max_time</literal> and
 872       <literal>sum_time</literal> statistics for this event are 32, 32 and 32,
 873       respectively. The unit is microseconds (μs).</para>
 874       <para>In the fifth line, the quota_ctl event occurs four times. The
 875       <literal>min_time</literal>,
 876       <literal>max_time</literal> and
 877       <literal>sum_time</literal> statistics for this event are 80, 3470 and
 878       4293, respectively. The unit is microseconds (μs).</para>
 879     </section>
 880   </section>
 881 </chapter>