doc/quotadoc.sgml

   1 <!doctype linuxdoc system>
   2
   3 <!--
   4         Documentation of quota utilities
   5 -->
   6
   7 <article>
   8
   9 <title>Disk quota system for Linux
  10 <author>Jan Kara <tt/jack@suse.cz/
  11
  12 <date>2000-2004
  13 <abstract>
  14 This document contains documentation of Linux quota disk formats and appropriate quota utilities
  15 (currently in version 3.12).
  16 </abstract>
  17
  18 <!-- Table of contents -->
  19 <toc>
  20 <!-- Document begins -->
  21
  22 <sect>Introduction
  23 <label id="intro">
  24 <p>
  25 Quota subsystem allows system administrator to set limits on used space and
  26 number of used inodes (<it/inode/ is a filesystem structure which is associated
  27 which each file or directory) for users and/or groups. For both used space and
  28 number of used inodes there are actually two limits. The first one is called
  29 <it/softlimit/ and the second one <it/hardlimit/.  An user can never exceed a
  30 hardlimit for any resource. When an user exceeds a softlimit (s)he is warned
  31 that (s)he uses more space than (s)he should but space/inode is allocated (of
  32 course only if an user also does not exceed the hardlimit). If an user is
  33 exceeding softlimit for specified period of time (this period is called
  34 <it/grace time/) (s)he is not allowed to allocate more resources (so (s)he must
  35 free some space/inodes to get under softlimit).
  36 <p>
  37 Quota limits are set independently for each filesystem. Currently following
  38 filesystems are supporting quota: Ext2, Ext3, ReiserFS, XFS.
  39
  40 <label id="config">
  41 <sect>Configuration
  42 <label id="new_quota">
  43 <sect1>Setting up new quota
  44 <p>
  45 In order for quota subsystem to work you have to have quota compiled in a
  46 kernel and configured appropriately. That means that the filesystem on which
  47 you want to use quotas must be mounted with quota options so that quota tools
  48 recognize the filesystems to work with (and also a filesystem itself might use
  49 the information).  Currently there are following quota options (note that XFS
  50 uses completely different quota system and these information does not apply to
  51 it):
  52 <itemize>
  53 <item><tt/usrquota/ or <tt/quota/ or <tt/usrjquota=filename/ if you want to use
  54 limits for users
  55 <item><tt/grpquota/ or <tt/grpjquota=filename/ if you want to use limits for
  56 groups
  57 </itemize>
  58 The <tt/usrquota/ and <tt/grpquota/ options have also alternative with
  59 <tt/=filename/ appended. <tt/filename/ is then used as a name (together with
  60 path) of quota file to use. But note that by this you prevent quota utilities
  61 to do some useful autodetection. <tt/jquota/ mount options tell the tools and
  62 also the filesystem that it should journal the quota. That basically means that
  63 quota on disk is updated together with filesystem's metadata and hence you do
  64 not need to run <tt/quotacheck(8)/ after an unclean shutdown. For these options
  65 specifying of filename is mandatory (because filesystem also needs to know the
  66 file with quota information) and <tt/filename/ must specify a file in the root
  67 directory of a filesystem. When any of <tt/jquota/ options is specified
  68 additional option <tt/jqfmt=format/ must be also specified where <tt/format/ is
  69 a format of quota files. As journaled quota is currently supported only for
  70 <tt/vfsv0/ format the value of format must be <tt/vfsv0/. Journaled quota
  71 is currently (as of July 2005) supported for Ext3 and Reiserfs filesystems
  72 and you need to have at least 2.6.11 kernel.
  73 <p>
  74 For each filesystem with quotas you have to have files with quota data. The
  75 name of these quota files depends on <ref id="quota_formats" name="quota
  76 format"> and you can even specify the filenames by yourself by adding
  77 <tt/=filename/ to <tt/usrquota/ or <tt/grpquota/ options -- e.g.
  78 <tt/usrquota=file.quota/. But note that by this you prevent quota utilities to
  79 do some useful autodetection. The quota files can be created by
  80 <tt/quotacheck(8)/ utility. When you have successfully created quota files you
  81 can turn quotas on (ie. system will start tracking how much each user uses and
  82 will check set limits). This is done by <tt/quotaon(8)/ program.
  83 <label id="converting_quota">
  84 <sect1>Converting quota formats
  85 <p>
  86 When you already have working quota subsystem but you want to use newer quota format
  87 you have to convert quota files. This can be done by <tt/convertquota(8)/ utility.
  88 <label id="setting_limits">
  89 <sect1>Setting user limits
  90 <p>
  91 You can edit user (group) limits by <tt/edquota(8)/ or <tt/setquota(8)/ programs.
  92 By these programs you can also set grace times.
  93
  94 <label id="quota_formats">
  95 <sect>Quota formats
  96 <label id="quota_format_old">
  97 <sect1>Original quota format
  98 <p>
  99 Original quota format was the only one available in kernels up to 2.4.21 Linux
 100 kernels (note that vendors such as <it/RedHat/ or <it/SuSE/ have included quota
 101 format patches into their kernels earlier and use <ref id="quota_format_v0"
 102 name="newer quota format">).  This quota format is in manpages and quota utils
 103 called <tt/vfsold/.
 104 <p>
 105 Data for this format are usually stored in files <tt/quota.user/ (for user quotas) and
 106 <tt/quota.group/ (for group quotas). Both files have the same structure. They are just
 107 the arrays of following structures:
 108 <code>
 109 struct v1_disk_dqblk {
 110         u_int32_t dqb_bhardlimit;       /* Absolute limit on disk blks alloc */
 111         u_int32_t dqb_bsoftlimit;       /* Preferred limit on disk blks */
 112         u_int32_t dqb_curblocks;        /* Current block count */
 113         u_int32_t dqb_ihardlimit;       /* Maximum # allocated inodes */
 114         u_int32_t dqb_isoftlimit;       /* Preferred limit on inodes */
 115         u_int32_t dqb_curinodes;        /* Current # allocated inodes */
 116         time_t dqb_btime;       /* Time limit for excessive disk use */
 117         time_t dqb_itime;       /* Time limit for excessive files */
 118 };
 119 </code>
 120 Structure for user (group) with id <tt/N/ is stored as <tt/N/-th structure in file.
 121 In fields <tt/dqb_btime/ and <tt/dqb_itime/ of first structure (id = 0) are stored
 122 grace times for this filesystem.
 123 <label id="quota_format_v0">
 124 <sect1>V0 quota format
 125 <p>
 126 This quota format is currently available in 2.4.22 and newer kernels. Also
 127 kernels distributed by RedHat (>= 7.1) and SuSE (>= 7.2) contain support for
 128 this quota format.  This format is called <tt/vfsv0/ in manpages and utilities
 129 and quota files are usually called <tt/aquota.user/ and <tt/aquota.group/.
 130 <p>
 131 This quota format has following advantages against old quota format:
 132 <itemize>
 133 <item>It allows 32-bit UIDs/GIDs.
 134 <item>Used space is stored in bytes and so ReiserFS can do precise accounting.
 135 <item>UID/GID 0 is no longer special (grace times are stored independently).
 136 <item>Header which allows quota format and version detection was added.
 137 </itemize>
 138 <p>
 139 Format of quota file is the following:
 140 In the beginning of quota file there is a generic header which is intended to be present
 141 in every quota file in future. The header has the following structure:
 142 <code>
 143 struct disk_dqheader {
 144   __u32 dqh_magic;        /* Magic number identifying file */
 145   __u32 dqh_version;      /* File version */
 146 };
 147 </code>
 148 From this header any utility or a kernel code should be able to recognize whether they
 149 understand a format of file and eventually refuse to continue.
 150 <p>
 151 Following header might be specific for quota type and version (currently this
 152 header is the same for user and group quota and there is only one version of
 153 quota file format).
 154 <code>
 155 struct disk_dqinfo {
 156   __u32 dqi_bgrace;     /* Time before block soft limit becomes hard limit - in seconds */
 157   __u32 dqi_igrace;     /* Time before inode soft limit becomes hard limit - in seconds */
 158   __u32 dqi_flags;      /* Flags for quota file (DQF_*) (currently there are no ondisk flags) */
 159   __u32 dqi_blocks;     /* Number of blocks in file */
 160   __u32 dqi_free_blk;   /* Number of first free block in the list */
 161   __u32 dqi_free_entry; /* Number of block with at least one free entry */
 162 };
 163 </code>
 164 There are two linked lists of blocks in a quota file. The first linked list is
 165 used to link all blocks that are completely unused (<tt/dqi_free_blk/ points to
 166 the first element of this list). The second linked list is used to link all
 167 <it/data blocks/ which have at least one entry free and which also have at
 168 least one used entry.  The beginning of the list is pointed by
 169 <tt/dqi_free_entry/.
 170 <p>
 171 The rest of a file (starting at 1KB) is divided into 1KB blocks. In these
 172 blocks is stored a radix tree with quotas. The key for the radix tree is UID or
 173 GID (I will use just ID in the following text) depending on a quota file type.
 174 One node of the tree is 1KB block so there are up to 256 references to the sons.
 175 At each level we choose reference corresponding to one byte of ID so having
 176 four-level radix tree we can support 32-bit IDs.  Reference from the last level
 177 points to <it/data block/ which contains quota structure for proper ID.
 178 <p>
 179 <it/Data block/ has following structure: In the beginning there is a header
 180 with the following structure:
 181 <code>
 182 struct disk_dqdbheader {
 183   __u32 dqdh_next_free;   /* Number of next block with free entry */
 184   __u32 dqdh_prev_free;   /* Number of previous block with free entry */
 185   __u16 dqdh_entries;     /* Number of valid entries in block */
 186   __u16 dqdh_pad1;
 187   __u32 dqdh_pad2;
 188 };
 189 </code>
 190 Entries <tt/dqdh_next_free/ and <tt/dqdh_prev_free/ are used only if the block
 191 has at least one free and one used entry. If it has no free entry these
 192 references are set to 0. When block is completely free only <tt/dqdh_next_free/
 193 is used for linked list of free blocks.
 194 <p>
 195 The rest of the block is divided into 21 quota entries. Unused entry is entry
 196 that contains only zeros. Note that used entries might be freely scattered in
 197 the block. Quota entry has the following structure:
 198 <code>
 199 struct disk_dqblk {
 200         __u32 dqb_id;           /* id this quota applies to */
 201         __u32 dqb_ihardlimit;   /* absolute limit on allocated inodes */
 202         __u32 dqb_isoftlimit;   /* preferred inode limit */
 203         __u32 dqb_curinodes;    /* current # allocated inodes */
 204         __u32 dqb_bhardlimit;   /* absolute limit on disk space (in kb) */
 205         __u32 dqb_bsoftlimit;   /* preferred limit on disk space (in kb) */
 206         __u64 dqb_curspace;     /* current space occupied (in bytes) */
 207         __u64 dqb_btime;        /* time limit for excessive disk use */
 208         __u64 dqb_itime;        /* time limit for excessive inode use */
 209 };
 210 </code>
 211 <label id="utils">
 212 <sect>Utilities
 213 <p>
 214 As of version 3.01 quota utilities support original, vfsv0 and xfs quota format.
 215 You can download latest version of utils from <tt>http://www.sf.net/projects/linuxquota/</tt>.
 216 <p>
 217 Utils try to do autodetection of currently used quota format (i.e. they detect which
 218 format is compiled into kernel and they try to use this one). Anytime you can
 219 force utils to use different format by specifying <tt>-F &lt;format&gt;</tt>. More information
 220 about quota utils can be found in appropriate manpages.
 221 </article>