Added a section explaining how to configure/use disk quotas.

Reviewed by:  Guy Helmer, John Fieber, Sean Kelly

4 files changed, 199 insertions, 4 deletions

diff --git a/share/doc/handbook/Makefile b/share/doc/handbook/Makefile
index 044d6d3..1fb94be 100644
--- a/share/doc/handbook/Makefile
+++ b/share/doc/handbook/Makefile
@@ -1,4 +1,4 @@
-# $Id: Makefile,v 1.8 1996/02/11 00:16:06 jkh Exp $
+# $Id: Makefile,v 1.9 1996/02/16 13:28:19 jkh Exp $
 
 SRCS= authors.sgml basics.sgml bibliography.sgml boothelp.sgml
 SRCS+= booting.sgml contrib.sgml crypt.sgml ctm.sgml current.sgml dialup.sgml
@@ -7,7 +7,7 @@ SRCS+= firewalls.sgml glossary.sgml goals.sgml
 SRCS+= handbook.sgml history.sgml hw.sgml install.sgml kerberos.sgml
 SRCS+= kernelconfig.sgml kerneldebug.sgml memoryuse.sgml
 SRCS+= mirrors.sgml nfs.sgml nutshell.sgml 
-SRCS+= porting.sgml ports.sgml ppp.sgml printing.sgml relnotes.sgml 
+SRCS+= porting.sgml ports.sgml ppp.sgml printing.sgml quotas.sgml relnotes.sgml 
 SRCS+= routing.sgml scsi.sgml sections.sgml sio.sgml
 SRCS+= skey.sgml slipc.sgml slips.sgml stable.sgml submitters.sgml sup.sgml
 SRCS+= synching.sgml troubleshooting.sgml userppp.sgml uart.sgml
diff --git a/share/doc/handbook/handbook.sgml b/share/doc/handbook/handbook.sgml
index d236101..2ac580a 100644
--- a/share/doc/handbook/handbook.sgml
+++ b/share/doc/handbook/handbook.sgml
@@ -1,4 +1,4 @@
-<!-- $Id: handbook.sgml,v 1.40 1996/02/11 00:16:14 jkh Exp $ -->
+<!-- $Id: handbook.sgml,v 1.41 1996/02/27 15:57:45 jfieber Exp $ -->
 <!-- The FreeBSD Documentation Project -->
 
 <!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN" [
@@ -84,6 +84,8 @@ Web server">.
       &firewalls;
 
     &printing;
+
+    &quotas;
     <chapt><heading>The X-Window System</heading>
        <p>Pending the completion of this section, please refer to
          documentation supplied by the <url url="http://www.xfree86.org/"
diff --git a/share/doc/handbook/quotas.sgml b/share/doc/handbook/quotas.sgml
new file mode 100644
index 0000000..dae4a57
--- /dev/null
+++ b/share/doc/handbook/quotas.sgml
@@ -0,0 +1,192 @@
+<!-- This is an SGML document in the linuxdoc DTD describing
+     disk quotas under FreeBSD.  By Mike Pritchard, 1996.
+
+     $Id$
+
+     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 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>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.
+
diff --git a/share/doc/handbook/sections.sgml b/share/doc/handbook/sections.sgml
index 945d7ea..1bd287a 100644
--- a/share/doc/handbook/sections.sgml
+++ b/share/doc/handbook/sections.sgml
@@ -1,4 +1,4 @@
-<!-- $Id: sections.sgml,v 1.8 1996/02/11 00:16:15 jkh Exp $ -->
+<!-- $Id: sections.sgml,v 1.9 1996/02/16 13:28:21 jkh Exp $ -->
 <!-- The FreeBSD Documentation Project -->
 
 <!-- Entities containing all the pieces of the handbook are -->
@@ -34,6 +34,7 @@
 <!ENTITY ports SYSTEM "ports.sgml">
 <!ENTITY ppp SYSTEM "ppp.sgml">
 <!ENTITY printing SYSTEM "printing.sgml">
+<!ENTITY quotas SYSTEM "quotas.sgml">
 <!ENTITY relnotes SYSTEM "relnotes.sgml">
 <!ENTITY routing SYSTEM "routing.sgml">
 <!ENTITY scsi SYSTEM "scsi.sgml">