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