freebsd/share/doc/handbook/quotas.sgml

<!-- This is an SGML document in the linuxdoc DTD describing
     disk quotas under FreeBSD.  By Mike Pritchard, 1996.

     $Id: quotas.sgml,v 1.5 1997/02/22 12:59:12 peter Exp $

     The FreeBSD Documentation Project

<!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN">

  <article>
      <title> Disk quotas
      <author> Mike Pritchard <tt/mpp@FreeBSD.org/
      <date> 26 February 1996, (c) 1996

      <abstract> This document describes configuration and administration 
        of disk quotas under FreeBSD. </abstract>

    <toc>
--> 

  <chapt><heading>Disk quotas<label id="quotas"></heading>  

  <p><em>Contributed by &a.mpp;.<newline>26 February 1996</em>

  Quotas are an optional feature of the operating system that allow
  you to limit the amount of disk space and/or the number of files
  a user, or members of a group, may allocate on a per-file system basis.
  This is used most often on timesharing systems where it is desirable
  to limit the amount of resources any one user or group of users may
  allocate.  This will prevent one user from consuming all of
  the available disk space.

<sect><heading>Configuring your system to enable disk quotas</heading>

  <p>Before attempting to use disk quotas it is
    necessary to make sure that quotas are configured in your kernel.
    This is done by adding the following line to your kernel configuration file:
<verb>
options		QUOTA
</verb>
    The stock GENERIC kernel does not have this enabled by default, so you
    will have to configure, build and install a custom kernel in order to use 
    disk quotas.  Please refer to the
    <ref id="kernelconfig" name="Configuring the FreeBSD Kernel">
    section for more information on kernel configuration.

    <p>Next you will need to enable disk quotas in <tt>/etc/sysconfig</tt>.
    This is done by changing the line:
<verb>
quotas=NO
</verb>
to:
<verb>
quotas=YES
</verb>

  <p>Finally you will need to edit <tt>/etc/fstab</tt> to enable 
  disk quotas on a per-file system basis.  This is where you can
  either enable user or group quotas or both for all of your file
  systems.

  <p>To enable per-user quotas on a file system, add the 
  <tt>userquota</tt> option to the options field in the
  <tt>/etc/fstab</tt> entry for the file system you want to
  to enable quotas on.  For example:
<verb>
/dev/sd1s2g    /home    ufs rw,userquota 1 2
</verb>

  <p>Similarly, to enable group quotas, use the <tt>groupquota</tt>
  option instead of the <tt>userquota</tt> keyword.  To enable both
  user and group quotas, change the entry as follows:
<verb>
/dev/sd1s2g    /home    ufs rw,userquota,groupquota 1 2
</verb>

  <p>By default the quota files are stored in the root directory of the file
  system with the names <tt>quota.user</tt> and <tt>quota.group</tt>
  for user and group quotas respectively.  See <tt>man fstab</tt> for more 
  information.  Even though that man page says that you can specify an 
  alternate location for the quota files, this is not recommended since
  all of the various quota utilities do not seem to handle this
  properly.

  <p>At this point you should reboot your system with your new kernel.
  <tt>/etc/rc</tt> will automatically run the appropriate commands to 
  create the initial quota files for all of the quotas you enabled
  in <tt>/etc/fstab</tt>, so there is no need to manually create any
  zero length quota files.

  <p>In the normal course of operations you should not be required
  to run the <tt>quotacheck</tt>, <tt>quotaon</tt>, or <tt>quotaoff</tt>
  commands manually.  However, you may want to read their man pages
  just to be familiar with their operation.

<sect><heading>Setting quota limits</heading>

  <p>Once you have configured your system to enable quotas, verify that
  they really are enabled.  An easy way to do this is to run
  <tt>quota -v</tt>.  You should see a one line summary of disk
  usage and current quota limits for each file system that
  quotas are enabled on.

  <p>You are now ready to start assigning quota limits
  with the <tt>edquota</tt> command.

  <p>You have several options on how to enforce limits on the amount of
  disk space a user or group may allocate, and how many files they may create.
  You may limit allocations based on disk space (block quotas) or
  number of files (inode quotas) or a combination of both.  
  Each of these limits are further broken down into two categories: hard and
  soft limits.  

  <p>A hard limit may not be exceeded.  Once a user reaches their hard
  limit they may not make any further allocations on the file system
  in question.  For example, if the user has a hard limit of 500 blocks
  on a file system and is currently using 490 blocks, the user can only allocate
  an additional 10 blocks.  Attempting to allocate an additional 11 blocks 
  will fail.

  <p>Soft limits on the other hand can be exceeded for a limited amount
  of time.  This period of time is known as the grace period, which is
  one week by default.  If a user stays over his or her soft limit longer
  than their grace period, the soft limit will turn into a hard limit
  and no further allocations will be allowed.  When the user drops
  back below the soft limit, the grace period will be reset.

  <p>The following is an example of what you might see when
  you run then <tt>edquota</tt> command.  When the <tt>edquota</tt>
  command is invoked, you are placed into the editor specified by the
  <tt>EDITOR</tt> environment variable, or in the <tt>vi</tt> editor 
  if the <tt>EDITOR</tt> variable is not set, to
  allow you to edit the quota limits.
<verb>
# edquota -u test
Quotas for user test:
/usr: blocks in use: 65, limits (soft = 50, hard = 75)
        inodes in use: 7, limits (soft = 50, hard = 60)
/usr/var: blocks in use: 0, limits (soft = 50, hard = 75)
        inodes in use: 0, limits (soft = 50, hard = 60)
</verb>
  You will normally see two lines for each file system that has
  quotas enabled.  One line for the block limits, and one line
  for inode limits.  Simply change the value you want updated
  to modify the quota limit.  For example, to raise this users
  block limit from a soft limit of 50 and a hard limit of 75
  to a soft limit of 500 and a hard limit of 600, change:
<verb>
/usr: blocks in use: 65, limits (soft = 50, hard = 75)
</verb>
to:
<verb>
/usr: blocks in use: 65, limits (soft = 500, hard = 600)
</verb>
  The new quota limits will be in place when you exit the editor.

  <p>Sometimes it is desirable to set quota limits on a range
  of uids.  This can be done by use of the <tt>-p</tt> option
  on the <tt>edquota</tt> command.  First, assign the desired
  quota limit to a user, and then run 
  <tt>edquota -p protouser startuid-enduid</tt>.
  For example, if user <tt>test</tt> has the desired quota
  limits, the following command can be used to duplicate
  those quota limits for uids 10,000 through 19,999:
<verb>
edquota -p test 10000-19999
</verb>

  <p>The ability to specify uid ranges was added to the system
  after 2.1 was released.  If you need this feature on a 2.1
  system, you will need to obtain a newer copy of edquota.

  <p>See <tt>man edquota</tt> for more detailed information.

<sect><heading>Checking quota limits and disk usage</heading>

  <p>You can use either the <tt>quota</tt> or the <tt>repquota</tt>
  commands to check quota limits and disk usage.  The <tt>quota</tt>
  command can be used to check individual user and group quotas and
  disk usage.  Only the super-user may examine quotas and usage for
  other users, or for groups that they are not a member of.
  The <tt>repquota</tt> command can be used to get a summary of all
  quotas and disk usage for file systems with quotas enabled.  

 <p>The following is some sample output from the <tt>quota -v</tt>
 command for a user that has quota limits on two file systems.

<verb>
Disk quotas for user test (uid 1002): 
     Filesystem  blocks   quota   limit   grace   files   quota   limit   grace
           /usr      65*     50      75   5days       7      50      60        
       /usr/var       0      50      75               0      50      60        
</verb>
  On the /usr file system in the above example this user is 
  currently 15 blocks over their soft limit of 50 blocks and has 5 days of 
  their grace period left.  Note the asterisk (*) which indicates that
  the user is currently over their quota limit.

  <p>Normally file systems that the user is not using any disk space
  on will not show up in the output from the <tt>quota</tt> command,
  even if they have a quota limit assigned for that file system.
  The <tt>-v</tt> option will display those file systems, such as 
  the <tt>/usr/var</tt> file system in the above example.

<sect><heading>* Quotas over NFS</heading>

  <p>This section is still under development.