ConfiguringQuotas.xml

   1 <?xml version='1.0' encoding='UTF-8'?>
   2 <!-- This document was created with Syntext Serna Free. --><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">
   3   <title xml:id="configuringquotas.title">Configuring and Managing Quotas</title>
   4   <para>This chapter describes how to configure quotas and includes the following sections:</para>
   5   <itemizedlist>
   6     <listitem>
   7       <para><xref linkend="dbdoclet.50438217_54945"/></para>
   8     </listitem>
   9     <listitem>
  10       <para><xref linkend="dbdoclet.50438217_31982"/></para>
  11     </listitem>
  12     <listitem>
  13       <para><xref linkend="dbdoclet.50438217_49939"/></para>
  14     </listitem>
  15     <listitem>
  16       <para><xref linkend="dbdoclet.50438217_15106"/></para>
  17     </listitem>
  18     <listitem>
  19       <para><xref linkend="dbdoclet.50438217_27895"/></para>
  20     </listitem>
  21     <listitem>
  22       <para><xref linkend="dbdoclet.50438217_20772"/></para>
  23     </listitem>
  24   </itemizedlist>
  25   <section xml:id="dbdoclet.50438217_54945">
  26       <title>
  27           <indexterm><primary>Quotas</primary><secondary>configuring</secondary></indexterm>
  28           Working with Quotas</title>
  29     <para>Quotas allow a system administrator to limit the amount of disk space a user or group can use in a directory. 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>
  30     <para>Lustre quota enforcement differs from standard Linux quota enforcement in several ways:</para>
  31     <itemizedlist>
  32       <listitem>
  33         <para>Quotas are administered via the <literal>lfs</literal> command (post-mount).</para>
  34       </listitem>
  35       <listitem>
  36         <para>Quotas are distributed (as Lustre is a distributed file system), which has several ramifications.</para>
  37       </listitem>
  38       <listitem>
  39         <para>Quotas are allocated and consumed in a quantized fashion.</para>
  40       </listitem>
  41       <listitem>
  42         <para>Client does not set the <literal>usrquota</literal> or <literal>grpquota</literal> options to mount. When quota is enabled, it is enabled for all clients of the file system; started automatically using <literal>quota_type</literal> or started manually with <literal>lfs quotaon</literal>.</para>
  43       </listitem>
  44     </itemizedlist>
  45     <caution>
  46       <para>Although quotas are available in Lustre, root quotas are NOT enforced.</para>
  47       <para><literal>lfs setquota -u root</literal> (limits are not enforced)</para>
  48       <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>
  49     </caution>
  50   </section>
  51   <section xml:id="dbdoclet.50438217_31982">
  52     <title><indexterm><primary>Quotas</primary><secondary>enabling disk</secondary></indexterm>Enabling Disk Quotas</title>
  53     <para>Use this procedure to enable (configure) disk quotas in Lustre.</para>
  54     <orderedlist>
  55       <listitem>
  56         <para>If you have re-complied your Linux kernel, be sure that <literal>CONFIG_QUOTA</literal> and <literal>CONFIG_QUOTACTL</literal> are enabled. Also, verify that <literal>CONFIG_QFMT_V1</literal> and/or <literal>CONFIG_QFMT_V2</literal> are enabled.</para>
  57         <para>Quota is enabled in all Linux 2.6 kernels supplied for Lustre.</para>
  58       </listitem>
  59       <listitem>
  60         <para>Start the server.</para>
  61       </listitem>
  62       <listitem>
  63         <para>
  64         Mount the Lustre file system on the client and verify that the <literal>lquota</literal> module has loaded properly by using the <literal>lsmod</literal> command.
  65
  66         </para>
  67         <screen>$ lsmod
  68 [root@oss161 ~]# lsmod
  69 Module                     Size                    Used by
  70 obdfilter          220532                  1
  71 fsfilt_ldiskfs             52228                   1
  72 ost                        96712                   1
  73 mgc                        60384                   1
  74 ldiskfs                    186896                  2 fsfilt_ldiskfs
  75 lustre                     401744                  0
  76 lov                        289064                  1 lustre
  77 lquota                     107048                  4 obdfilter
  78 mdc                        95016                   1 lustre
  79 ksocklnd           111812                  1</screen>
  80       </listitem>
  81     </orderedlist>
  82     <para>The Lustre mount command no longer recognizes the <literal>usrquota</literal> and <literal>grpquota</literal> options. If they were previously specified, remove them from <literal>/etc/fstab</literal>.</para>
  83     <para>When quota is enabled, it is enabled for all file system clients (started automatically using <literal>quota_type</literal> or manually with <literal>lfs quotaon</literal>).</para>
  84     <para>To enable quotas automatically when the file system is started, you must set the <literal>mdd.quota_type</literal> and <literal>ost.quota_type</literal> parameters, respectively, on the MDT and OSTs. The parameters can be set to the string <literal>u</literal> (user), <literal>g</literal> (group) or <literal>ug</literal> for both users and groups.</para>
  85     <para>You can enable quotas at <literal>mkfs</literal> time (<literal>mkfs.lustre --param mdd.quota_type=ug</literal>) or with <literal>tunefs.lustre</literal>. As an example:</para>
  86     <screen>tunefs.lustre --param ost.quota_type=ug $ost_dev</screen>
  87     <caution>
  88       <para>If you are using <literal>mkfs.lustre --param mdd.quota_type=ug</literal> or <literal>tunefs.lustre --param ost.quota_type=ug</literal>, be sure to run the command on all OSTs and the MDT. Otherwise, abnormal results may occur.</para>
  89     </caution>
  90     <section remap="h4">
  91       <title><indexterm><primary>Quotas</primary><secondary>administrating</secondary></indexterm>Administrative and Operational Quotas</title>
  92       <para>Lustre has two kinds of quota files:</para>
  93       <itemizedlist>
  94         <listitem>
  95           <para>Administrative quotas (for the MDT), which contain limits for users/groups for the entire cluster.</para>
  96         </listitem>
  97         <listitem>
  98           <para>Operational quotas (for the MDT and OSTs), which contain quota information dedicated to a cluster node.</para>
  99         </listitem>
 100       </itemizedlist>
 101       <para>Lustre 1.6.5 introduced the v2 file format for administrative quota files, with continued support for the old file format (v1). The mdd.quota_type parameter also handles &apos;1&apos; and &apos;2&apos; options, to specify the Lustre quota versions that will be used. For example:</para>
 102       <screen>--param mdd.quota_type=ug1
 103 --param mdd.quota_type=u2</screen>
 104       <para>Lustre 1.6.6 introduced the v2 file format for operational quotas, with continued support for the old file format (v1). The ost.quota_type parameter handles &apos;1&apos; and &apos;2&apos; options, to specify the Lustre quota versions that will be used. For example:</para>
 105       <screen>--param ost.quota_type=ug2
 106 --param ost.quota_type=u1</screen>
 107       <para>For more information about the v1 and v2 formats, see <xref linkend="dbdoclet.50438217_66360"/>.</para>
 108     </section>
 109   </section>
 110   <section xml:id="dbdoclet.50438217_49939">
 111     <title><indexterm><primary>Quotas</primary><secondary>creating</secondary></indexterm>Creating Quota Files and Quota Administration</title>
 112     <para>Once each quota-enabled file system is remounted, it is capable of working with disk quotas. However, the file system is not yet ready to support quotas. If <literal>umount</literal> has been done regularly, run the <literal>lfs</literal> command with the <literal>quotaon</literal> option. If <literal>umount</literal> has not been done, perform these steps:</para>
 113     <orderedlist>
 114       <listitem>
 115         <para>Take Lustre &apos;&apos;offline&apos;&apos;.</para>
 116         <para>That is, verify that no write operations (append, write, truncate, create or delete) are being performed (preparing to run <literal>lfs quotacheck</literal>). Operations that do not change Lustre files (such as read or mount) are okay to run.</para>
 117         <caution>
 118           <para>When <literal>lfs quotacheck</literal> is run, Lustre must NOT be performing any write operations. Failure to follow this caution may cause the statistic information of quota to be inaccurate. For example, the number of blocks used by OSTs for users or groups will be inaccurate, which can cause unexpected quota problems.</para>
 119         </caution>
 120       </listitem>
 121       <listitem>
 122         <para> Run the <emphasis role="bold">
 123             <literal>lfs</literal>
 124           </emphasis> command with the <emphasis role="bold">
 125             <literal>quotacheck</literal>
 126           </emphasis> option:</para>
 127         <screen># lfs quotacheck -ug /mnt/lustre</screen>
 128         <para>By default, quota is turned on after <literal>quotacheck</literal> completes. Available options are:</para>
 129         <itemizedlist>
 130           <listitem>
 131             <para><literal>u</literal>  -- checks the user disk quota information</para>
 132           </listitem>
 133           <listitem>
 134             <para><literal>g</literal>  -- checks the group disk quota information</para>
 135           </listitem>
 136         </itemizedlist>
 137       </listitem>
 138     </orderedlist>
 139     <para>The lfsquotacheck command checks all objects on all OSTs and the MDS to sum up for every UID/GID. It reads all Lustre metadata and re-computes the number of blocks/inodes that each UID/GID has used. If there are many files in Lustre, it may take a long time to complete.</para>
 140     <note>
 141       <para>User and group quotas are separate. If either quota limit is reached, a process with the corresponding UID/GID cannot allocate more space on the file system.</para>
 142     </note>
 143     <note>
 144       <para>When <literal>lfs quotacheck</literal> runs, it creates a quota file -- a sparse file with a size proportional to the highest UID in use and UID/GID distribution. As a general rule, if the highest UID in use is large, then the sparse file will be large, which may affect functions such as creating a snapshot.</para>
 145     </note>
 146     <note>
 147       <para>Lustre 1.6.5 and later use journaled quota files, so it is not necessary to run <literal>quotacheck</literal> after an unclean shutdown.</para>
 148       <para>In certain failure situations (e.g., when a broken Lustre installation or build is used), re-run <literal>quotacheck</literal> after checking the server kernel logs and fixing the root problem.</para>
 149     </note>
 150     <para>The <literal>lfs</literal> command includes several command options to work with quotas:</para>
 151     <itemizedlist>
 152       <listitem>
 153         <para><varname>quotaon</varname>  -- enables disk quotas on the specified file system. The file system quota files must be present in the root directory of the file system.</para>
 154       </listitem>
 155       <listitem>
 156         <para><varname>quotaoff</varname>  -- disables disk quotas on the specified file system.</para>
 157       </listitem>
 158       <listitem>
 159         <para><varname>quota</varname>  -- displays general quota information (disk usage and limits)</para>
 160       </listitem>
 161       <listitem>
 162         <para><varname>setquota</varname>  -- specifies quota limits and tunes the grace period. By default, the grace period is one week.</para>
 163       </listitem>
 164     </itemizedlist>
 165     <para> Usage:</para>
 166     <screen>lfs quotaon [-ugf] &lt;filesystem&gt;
 167 lfs quotaoff [-ug] &lt;filesystem&gt;
 168 lfs quota [-q] [-v] [-o obd_uuid] [-u|-g &lt;uname&gt;|uid|gname|gid&gt;]  &lt;filesystem&gt;
 169 lfs quota -t &lt;-u|-g&gt; &lt;filesystem&gt;
 170 lfs setquota &lt;-u|--user|-g|--group&gt; &lt;username|groupname&gt; [-b &lt;block-softlimit&gt;] [\
 171 -B &lt;block-hardlimit&gt;] [-i &lt;inode-softlimit&gt;] [-I &lt;inode-hardlimit&gt;] &lt;filesystem&gt;</screen>
 172     <para>Examples:</para>
 173     <para>In all of the examples below, the file system is <literal>/mnt</literal> lustre.</para>
 174     <para>To turn on user and group quotas, run:</para>
 175     <screen>$ lfs quotaon -ug /mnt/lustre</screen>
 176     <para>To turn off user and group quotas, run:</para>
 177     <screen>$ lfs quotaoff -ug /mnt/lustre</screen>
 178     <para>To display general quota information (disk usage and limits) for the user running the command and his primary group, run:</para>
 179     <screen>$ lfs quota /mnt/lustre </screen>
 180     <para>To display general quota information for a specific user (&quot;<literal>bob</literal>&quot; in this example), run:</para>
 181     <screen>$ lfs quota -u bob /mnt/lustre</screen>
 182     <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>
 183     <screen>$ lfs quota -u bob -v /mnt/lustre</screen>
 184     <para>To display general quota information for a specific group (&quot;<literal>eng</literal>&quot; in this example), run:</para>
 185     <screen>$ lfs quota -g eng /mnt/lustre</screen>
 186     <para>To display block and inode grace times for user quotas, run:</para>
 187     <screen>$ lfs quota -t -u /mnt/lustre</screen>
 188     <para>To set user and group quotas for a specific user (&quot;bob&quot; in this example), run:</para>
 189     <screen>$ lfs setquota -u bob 307200 309200 10000 11000 /mnt/lustre</screen>
 190     <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>
 191     <note>
 192       <para>For the Lustre command <literal>$lfssetquota/quota ...</literal> the qunit for block is KB (1024) and the qunit for inode is 1.</para>
 193     </note>
 194     <para>The quota command displays the quota allocated and consumed for each Lustre device. Using the previous <literal>setquota</literal> example, running this <literal>lfs</literal> quota command:</para>
 195     <screen>$ lfs quota -u bob -v /mnt/lustre </screen>
 196     <para>displays this command output:</para>
 197     <screen>Disk quotas for user bob (uid 6000):
 198 Filesystem         kbytes          quota           limit           grace   \
 199         files           quota           limit           grace
 200 /mnt/lustre                0               30720           30920           \
 201 -               0               10000           11000           -
 202 lustre-MDT0000_UUID        0               -               16384           \
 203 -               0               -               2560            -
 204 lustre-OST0000_UUID        0               -               16384           \
 205 -               0               -               0               -
 206 lustre-OST0001_UUID        0               -               16384           \
 207 -               0               -               0               -</screen>
 208   </section>
 209   <section xml:id="dbdoclet.50438217_15106">
 210     <title><indexterm><primary>Quotas</primary><secondary>allocating</secondary></indexterm>Quota Allocation</title>
 211     <para>In Lustre, quota must be properly allocated or users may experience unnecessary failures. The file system block quota is divided up among the OSTs within the file system. Each OST requests an allocation which is increased up to the quota limit. The quota allocation is then <emphasis role="italic">quantized</emphasis> to reduce the number of quota-related request traffic. By default, Lustre supports both user and group quotas to limit disk usage and file counts.</para>
 212     <para>The quota system in Lustre is completely compatible with the quota systems used on other file systems. The Lustre quota system distributes quotas from the quota master. Generally, the MDS is the quota master for both inodes and blocks. All OSTs and the MDS are quota slaves to the OSS nodes. To reduce quota requests and get reasonably accurate quota distribution, the transfer quota unit (qunit) between quota master and quota slaves is changed dynamically by the lquota module. The default minimum value of qunit is 1 MB for blocks and 2 for inodes. The proc entries to set these values are: <literal>/proc/fs/lustre/mds/lustre-MDT*/quota_least_bunit</literal> and <literal>/proc/fs/lustre/mds/lustre-MDT*/quota_least_iunit</literal>. The default maximum value of <literal>qunit</literal> is 128 MB for blocks and 5120 for inodes. The proc entries to set these values are <literal>quota_bunit_sz</literal> and <literal>quota_iunit_sz</literal> in the MDT and OSTs.</para>
 213     <note>
 214       <para>In general, the <literal>quota_bunit_sz</literal> value should be larger than 1 MB. For testing purposes, it can be set to 4 KB, if necessary.</para>
 215     </note>
 216     <para>The file system block quota is divided up among the OSTs and the MDS within the file system. Only the MDS uses the file system inode quota.</para>
 217     <para>This means that the minimum quota for block is 1 MB* (the number of OSTs + the number of MDSs), which is 1 MB* (number of OSTs + 1). If you attempt to assign a smaller quota, users maybe not be able to create files. As noted, the default minimum quota for inodes is 2. The default is established at file system creation time, but can be tuned via <literal>/proc</literal> values (described below). The inode quota is also allocated in a quantized manner on the MDS.</para>
 218     <para>If we look at the <literal>setquota</literal> example again, running this <literal>lfs quota</literal> command:</para>
 219     <screen># lfs quota -u bob -v /mnt/lustre
 220 </screen>
 221     <para>displays this command output:</para>
 222     <screen>Disk quotas for user bob (uid 500):
 223 Filesystem         kbytes          quota           limit           grace   \
 224         files           quota           limit           grace
 225 /mnt/lustre                30720*          30720           30920           \
 226 6d23h56m44s     10101*          10000           11000           6d23h59m50s
 227 lustre-MDT0000_UUID        0               -               1024            \
 228 -               10101           -               10240
 229 lustre-OST0000_UUID        0               -               1024            \
 230 -               -               -               -
 231 lustre-OST0001_UUID        30720*          -               28872           \
 232 -               -               -               -</screen>
 233     <para>The total quota limit of 30,920 is allotted to user bob, which is further distributed to two OSTs and one MDS.</para>
 234     <note>
 235       <para>Values appended with &apos;<literal>*</literal>&apos; show the limit that has been over-used (exceeding the quota), and receives this message Disk quota exceeded. For example:</para>
 236       <para><screen>$ cp: writing `/mnt/lustre/var/cache/fontconfig/ beeeeb3dfe132a8a0633a017c99ce0-x86.cache&apos;: Disk quota exceeded.</screen></para>
 237     </note>
 238     <para>The requested quota of 300 MB is divided across the OSTs.</para>
 239     <note>
 240       <para>It is very important to note that the block quota is consumed per OST and the MDS per block and inode (there is only one MDS for inodes). Therefore, when the quota is consumed on one OST, the client may not be able to create files regardless of the quota available on other OSTs.</para>
 241     </note>
 242     <section remap="h5">
 243       <title>Additional information:</title>
 244       <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>
 245       <itemizedlist>
 246         <listitem>
 247           <para> user block soft limit</para>
 248         </listitem>
 249         <listitem>
 250           <para> user inode soft limit</para>
 251         </listitem>
 252         <listitem>
 253           <para> group block soft limit</para>
 254         </listitem>
 255         <listitem>
 256           <para> group inode soft limit</para>
 257         </listitem>
 258       </itemizedlist>
 259       <para>The grace periods are applied to all users. The user block soft limit is for all users who are using a blocks quota.</para>
 260       <para><emphasis role="bold">Soft limit</emphasis> -- Once you are beyond the soft limit, the quota module begins to time, but you still can write block and inode. When you are always beyond the soft limit and use up your grace time, you get the same result as the hard limit. For inodes and blocks, it is the same. Usually, the soft limit MUST be less than the hard limit; if not, the quota module never triggers the timing. If the soft limit is not needed, leave it as zero (0).</para>
 261       <para><emphasis role="bold">Hard limit</emphasis> -- When you are beyond the hard limit, you get <literal>-EQUOTA</literal> and cannot write inode/block any more. The hard limit is the absolute limit. When a grace period is set, you can exceed the soft limit within the grace period if are under the hard limits.</para>
 262       <para>Lustre quota allocation is controlled by two variables, <literal>quota_bunit_sz</literal> and <literal>quota_iunit_sz</literal> referring to KBs and inodes, respectively. These values can be accessed on the MDS as <literal>/proc/fs/lustre/mds/*/quota_*</literal> and on the OST as <literal>/proc/fs/lustre/obdfilter/*/quota_*</literal>. The <literal>quota_bunit_sz </literal>and <literal>quota_iunit_sz</literal> variables are the maximum qunit values for blocks and inodes, respectively. At any time, module lquota chooses a reasonable qunit between the minimum and maximum values.</para>
 263       <para>The /proc values are bounded by two other variables <literal>quota_btune_sz</literal> and <literal>quota_itune_sz</literal>. By default, the <literal>*tune_sz</literal> variables are set at 1/2 the <literal>*unit_sz</literal> variables, and you cannot set <literal>*tune_sz</literal> larger than <literal>*unit_sz</literal>. You must set <literal>bunit_sz</literal> first if it is increasing by more than 2x, and <literal>btune_sz</literal> first if it is decreasing by more than 2x.</para>
 264       <para><emphasis role="bold">Total number of inodes</emphasis> -- To determine the total number of inodes, use <literal>lfs df -i</literal> (and also <literal>/proc/fs/lustre/*/*/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>
 265       <para>Unfortunately, the <literal>statfs</literal> interface does not report the free inode count directly, but instead reports the total inode and used inode counts. The free inode count is calculated for <literal>df</literal> from (total inodes - used inodes).</para>
 266       <para>It is not critical to know a file system&apos;s total inode count. Instead, you should know (accurately), the free inode count and the used inode count for a file system. Lustre manipulates the total inode count in order to accurately report the other two values.</para>
 267       <para>The values set for the MDS must match the values set on the OSTs.</para>
 268       <para>The <literal>quota_bunit_sz</literal> parameter displays bytes, however <literal>lfs setquota</literal> uses KBs. The <literal>quota_bunit_sz</literal> parameter must be a multiple of 1024. A proper minimum KB size for <literal>lfs setquota</literal> can be calculated as:</para>
 269       <informalexample>
 270         <para>
 271           <emphasis role="bold">Size in KBs = minimum_quota_bunit_sz * (number of OSTS + 1) = 1024 * (number of OSTs +1)</emphasis>
 272         </para>
 273       </informalexample>
 274       <para>We add one (1) to the number of OSTs as the MDS also consumes KBs. As inodes are only consumed on the MDS, the minimum inode size for <literal>lfs setquota</literal> is equal to <literal>quota_iunit_sz</literal>.</para>
 275       <note>
 276         <para>Setting the quota below this limit may prevent the user from all file creation.</para>
 277       </note>
 278     </section>
 279   </section>
 280   <section xml:id="dbdoclet.50438217_27895">
 281     <title><indexterm><primary>Quotas</primary><secondary>known issues</secondary></indexterm>Known Issues with Quotas</title>
 282     <para>Using quotas in Lustre can be complex and there are several known issues.</para>
 283     <section remap="h3">
 284       <title>Granted Cache and Quota Limits</title>
 285       <para>In Lustre, granted cache does not respect quota limits. In this situation, OSTs grant cache to Lustre client to accelerate I/O. Granting cache causes writes to be successful in OSTs, even if they exceed the quota limits, and will overwrite them.</para>
 286       <para>The sequence is:</para>
 287       <orderedlist>
 288         <listitem>
 289           <para>A user writes files to Lustre.</para>
 290         </listitem>
 291         <listitem>
 292           <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>
 293         </listitem>
 294         <listitem>
 295           <para>Because Lustre clients have delivered success to users, the OSTs cannot fail these writes.</para>
 296         </listitem>
 297       </orderedlist>
 298       <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>
 299       <note>
 300         <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 (can be set from 1 to 512):</para>
 301         <itemizedlist>
 302           <listitem>
 303             <para><literal>lctl set_param osc.*.max_dirty_mb=0</literal></para>
 304           </listitem>
 305         </itemizedlist>
 306       </note>
 307     </section>
 308     <section xml:id="dbdoclet.50438217_66360">
 309       <title><indexterm><primary>Quotas</primary><secondary>file formats</secondary></indexterm>Quota File Formats</title>
 310       <para>Lustre 1.6.5 introduced the v2 file format for administrative quotas, with 64-bit limits that support large-limits handling. The old quota file format (v1), with 32-bit limits, is also supported. Lustre 1.6.6 introduced the v2 file format for operational quotas. A few notes regarding the current quota file formats:</para>
 311       <para>From Lustre 1.6.5 until Lustre 2.0 <literal>mdt.quota_type</literal> is used to force a specific administrative quota version (v2 or v1). From Lustre 2.0 and later <literal>mdd.quota_type</literal> is used for the same effect.</para>
 312       <itemizedlist>
 313         <listitem>
 314           <para> For the v2 quota file format, (<literal>OBJECTS/admin_quotafile_v2.{usr,grp}</literal>)</para>
 315         </listitem>
 316         <listitem>
 317           <para> For the v1 quota file format, (<literal>OBJECTS/admin_quotafile.{usr,grp}</literal>)</para>
 318         </listitem>
 319       </itemizedlist>
 320       <para>Lustre 1.6.6 and later use <literal>ost.quota_type</literal> to force a specific operational quota version (v2 or v1).</para>
 321       <itemizedlist>
 322         <listitem>
 323           <para>For the v2 quota file format, (<literal>lquota_v2.{user,group}</literal>)</para>
 324         </listitem>
 325         <listitem>
 326           <para>For the v1 quota file format, (<literal>lquota.{user,group}</literal>)</para>
 327         </listitem>
 328       </itemizedlist>
 329       <para>The quota_type specifier can be used to set different combinations of administrative/operational quota file versions on a Lustre node:</para>
 330       <itemizedlist>
 331         <listitem>
 332           <para>&quot;1&quot; - v1 (32-bit) administrative quota file, v1 (32-bit) operational quota file (default in releases <emphasis role="underline">before</emphasis> Lustre 1.6.5)</para>
 333         </listitem>
 334         <listitem>
 335           <para>&quot;2&quot; - v2 (64-bit) administrative quota file, v1 (32-bit) operational quota file (default in Lustre 1.6.5)</para>
 336         </listitem>
 337         <listitem>
 338           <para>&quot;3&quot; - v2 (64-bit) administrative quota file, v2 (64-bit) operational quota file (default in releases <emphasis role="underline">after</emphasis> Lustre 1.6.5)</para>
 339         </listitem>
 340       </itemizedlist>
 341       <para>If quotas do not exist or look broken, then <literal>quotacheck</literal> creates quota files of a required name and format.</para>
 342       <para>If Lustre is using the v2 quota file format when only v1 quota files exist, then <literal>quotacheck</literal> converts old v1 quota files to new v2 quota files. This conversion is triggered automatically, and is transparent to users. If an old quota file does not exist or looks broken, then the new v2 quota file will be empty. In case of an error, details can be found in the kernel log of the corresponding MDS/OST. During conversion of a v1 quota file to a v2 quota file, the v2 quota file is marked as broken, to avoid it being used if a crash occurs. The quota module does not use broken quota files (keeping quota off).</para>
 343       <para>In most situations, Lustre administrators do not need to set specific versioning options. Upgrading Lustre without using <literal>quota_type</literal> to force specific quota file versions results in quota files being upgraded automatically to the latest version. The option ensures backward compatibility, preventing a quota file upgrade to a version which is not supported by earlier Lustre versions.</para>
 344     </section>
 345   </section>
 346   <section xml:id="dbdoclet.50438217_20772">
 347     <title><indexterm><primary>Quotas</primary><secondary>statistics</secondary></indexterm>Lustre Quota Statistics</title>
 348     <para>Lustre includes statistics that monitor quota activity, such as the kinds of quota RPCs sent during a specific period, the average time to complete the RPCs, etc. These statistics are useful to measure performance of a Lustre file system.</para>
 349     <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>
 350     <informaltable frame="all">
 351       <tgroup cols="2">
 352         <colspec colname="c1" colwidth="50*"/>
 353         <colspec colname="c2" colwidth="50*"/>
 354         <thead>
 355           <row>
 356             <entry>
 357               <para><emphasis role="bold">Quota Event</emphasis></para>
 358             </entry>
 359             <entry>
 360               <para><emphasis role="bold">Description</emphasis></para>
 361             </entry>
 362           </row>
 363         </thead>
 364         <tbody>
 365           <row>
 366             <entry>
 367               <para> <emphasis role="bold">sync_acq_req</emphasis></para>
 368             </entry>
 369             <entry>
 370               <para> Quota slaves send a acquiring_quota request and wait for its return.</para>
 371             </entry>
 372           </row>
 373           <row>
 374             <entry>
 375               <para> <emphasis role="bold">sync_rel_req</emphasis></para>
 376             </entry>
 377             <entry>
 378               <para> Quota slaves send a releasing_quota request and wait for its return.</para>
 379             </entry>
 380           </row>
 381           <row>
 382             <entry>
 383               <para> <emphasis role="bold">async_acq_req</emphasis></para>
 384             </entry>
 385             <entry>
 386               <para> Quota slaves send an acquiring_quota request and do not wait for its return.</para>
 387             </entry>
 388           </row>
 389           <row>
 390             <entry>
 391               <para> <emphasis role="bold">async_rel_req</emphasis></para>
 392             </entry>
 393             <entry>
 394               <para> Quota slaves send a releasing_quota request and do not wait for its return.</para>
 395             </entry>
 396           </row>
 397           <row>
 398             <entry>
 399               <para> <emphasis role="bold">wait_for_blk_quota (lquota_chkquota)</emphasis></para>
 400             </entry>
 401             <entry>
 402               <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>
 403             </entry>
 404           </row>
 405           <row>
 406             <entry>
 407               <para> <emphasis role="bold">wait_for_ino_quota (lquota_chkquota)</emphasis></para>
 408             </entry>
 409             <entry>
 410               <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>
 411             </entry>
 412           </row>
 413           <row>
 414             <entry>
 415               <para> <emphasis role="bold">wait_for_blk_quota (lquota_pending_commit)</emphasis></para>
 416             </entry>
 417             <entry>
 418               <para> After blocks are written to OSTs, relative quota information is updated. This is done in the lquota_pending_commit function.</para>
 419             </entry>
 420           </row>
 421           <row>
 422             <entry>
 423               <para> <emphasis role="bold">wait_for_ino_quota (lquota_pending_commit)</emphasis></para>
 424             </entry>
 425             <entry>
 426               <para> After files are created, relative quota information is updated. This is done in the lquota_pending_commit function.</para>
 427             </entry>
 428           </row>
 429           <row>
 430             <entry>
 431               <para> <emphasis role="bold">wait_for_pending_blk_quota_req (qctxt_wait_pending_dqacq)</emphasis></para>
 432             </entry>
 433             <entry>
 434               <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>
 435             </entry>
 436           </row>
 437           <row>
 438             <entry>
 439               <para> <emphasis role="bold">wait_for_pending_ino_quota_req (qctxt_wait_pending_dqacq)</emphasis></para>
 440             </entry>
 441             <entry>
 442               <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>
 443             </entry>
 444           </row>
 445           <row>
 446             <entry>
 447               <para> <emphasis role="bold">nowait_for_pending_blk_quota_req (qctxt_wait_pending_dqacq)</emphasis></para>
 448             </entry>
 449             <entry>
 450               <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>
 451             </entry>
 452           </row>
 453           <row>
 454             <entry>
 455               <para> <emphasis role="bold">nowait_for_pending_ino_quota_req (qctxt_wait_pending_dqacq)</emphasis></para>
 456             </entry>
 457             <entry>
 458               <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>
 459             </entry>
 460           </row>
 461           <row>
 462             <entry>
 463               <para> <emphasis role="bold">quota_ctl</emphasis></para>
 464             </entry>
 465             <entry>
 466               <para> The quota_ctl statistic is generated when lfs <literal>setquota</literal>, <literal>lfs quota</literal> and so on, are issued.</para>
 467             </entry>
 468           </row>
 469           <row>
 470             <entry>
 471               <para> <emphasis role="bold">adjust_qunit</emphasis></para>
 472             </entry>
 473             <entry>
 474               <para> Each time qunit is adjusted, it is counted.</para>
 475             </entry>
 476           </row>
 477         </tbody>
 478       </tgroup>
 479     </informaltable>
 480     <section remap="h3">
 481       <title>Interpreting Quota Statistics</title>
 482       <para>Quota statistics are an important measure of a Lustre file system&apos;s performance. Interpreting these statistics correctly can help you diagnose problems with quotas, and may indicate adjustments to improve system performance.</para>
 483       <para>For example, if you run this command on the OSTs:</para>
 484       <screen>cat /proc/fs/lustre/lquota/lustre-OST0000/stats</screen>
 485       <para>You will get a result similar to this:</para>
 486       <screen>snapshot_time                                1219908615.506895 secs.usecs
 487 async_acq_req                              1 samples [us]  32 32 32
 488 async_rel_req                              1 samples [us]  5 5 5
 489 nowait_for_pending_blk_quota_req(qctxt_wait_pending_dqacq) 1 samples [us] 2\
 490  2 2
 491 quota_ctl                          4 samples [us]  80 3470 4293
 492 adjust_qunit                               1 samples [us]  70 70 70
 493 ....</screen>
 494       <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>
 495       <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>
 496       <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>
 497     </section>
 498   </section>
 499 </chapter>