[src/netbsd-6]: src/share/doc/smm/04.quotas Pull up following revision(s) (re...

[riz <riz%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/c3de272bf7ae
branches:  netbsd-6
changeset: 774449:c3de272bf7ae
user:      riz <riz%NetBSD.org@localhost>
date:      Wed Aug 15 01:20:23 2012 +0000

description:
Pull up following revision(s) (requested by dholland in ticket #499):
        share/doc/smm/04.quotas/quotas.ms: revision 1.5
        share/doc/smm/04.quotas/quotas.ms: revision 1.6
        share/doc/smm/04.quotas/quotas.ms: revision 1.7
Update. comments/suggestions/edits please.
This should be pulled up to netbsd-6 once the dust (if any) settles.
Typos, capitalization, and file systems.
(Not reviewed at the content level.)
Some edits, prompted by suggestions from Edgar Fuss.

diffstat:

 share/doc/smm/04.quotas/quotas.ms |  910 +++++++++++++++++++++++++++++--------
 1 files changed, 698 insertions(+), 212 deletions(-)

diffs (truncated from 994 to 300 lines):

diff -r 63711705b33f -r c3de272bf7ae share/doc/smm/04.quotas/quotas.ms
--- a/share/doc/smm/04.quotas/quotas.ms Wed Aug 15 00:36:50 2012 +0000
+++ b/share/doc/smm/04.quotas/quotas.ms Wed Aug 15 01:20:23 2012 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: quotas.ms,v 1.4 2004/02/13 11:36:08 wiz Exp $
+.\"    $NetBSD: quotas.ms,v 1.4.56.1 2012/08/15 01:20:23 riz Exp $
 .\"
 .\" Copyright (c) 1983, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -29,254 +29,724 @@
 .\"
 .\"    @(#)quotas.ms   8.1 (Berkeley) 6/8/93
 .\"
-.EH 'SMM:4-%''Disc Quotas in a \s-2UNIX\s+2 Environment'
-.OH 'Disc Quotas in a \s-2UNIX\s+2 Environment''SMM:4-%'
-.ND 5th July, 1983
+.\"
+.\" Copyright (c) 2012 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by David A. Holland.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\"
+.\" .EH 'SMM:4-%''Disc Quotas in a \s-2UNIX\s+2 Environment'
+.\" .OH 'Disc Quotas in a \s-2UNIX\s+2 Environment''SMM:4-%'
+.\" .ND 5th July, 1983
+.\" .TL
+.\" Disc Quotas in a \s-2UNIX\s+2\s-3\u*\d\s0 Environment
+.\" .FS
+.\" * UNIX is a trademark of Bell Laboratories.
+.\" .FE
+.EH 'SMM:4-%''Disk Quotas in NetBSD'
+.OH 'Disk Quotas in NetBSD''SMM:4-%'
+.ND May 20, 2012
 .TL
-Disc Quotas in a \s-2UNIX\s+2\s-3\u*\d\s0 Environment
-.FS
-* UNIX is a trademark of Bell Laboratories.
-.FE
+Disk Quotas in NetBSD
 .AU
-Robert Elz
+David A. Holland
+.\" (XXX: what's the best way to do this?)
+.\" Robert Elz
 .AI
-Department of Computer Science
-University of Melbourne,
-Parkville,
-Victoria,
-Australia.
+Based upon an earlier version by Robert Elz.
 .AB
 .PP
-In most computing environments, disc space is not
+In most computing environments, disk space is not
 infinite.
-The disc quota system provides a mechanism
-to control usage of disc space, on an
+The disk quota system provides a mechanism
+to control usage of disk space on an
 individual basis.
 .PP
-Quotas may be set for each individual user, on any, or
-all filesystems.
+Quotas may be set for each individual user, and for groups.
+Quotas may be set (or not set) independently on each mounted file
+system.
+Quotas are not supported on all file system types, but do work over
+NFS.
 .PP
 The quota system will warn users when they
 exceed their allotted limit, but allow some
 extra space for current work.
-Repeatedly remaining over quota at logout,
-will cause a fatal over quota condition eventually.
+Remaining over quota for long periods of time
+will eventually cause a fatal over-quota condition.
 .PP
-The quota system is an optional part of
-\s-2VMUNIX\s0 that may be included when the
-system is configured.
+File system independent access to quotas is provided via a library,
+\fIlibquota\fP\|(3),
+shared by the quota tools and available to third-party software.
+Dump and restore tools are provided for backing up quota information.
 .AE
 .NH 1
-Users' view of disc quotas
+Users' view of disk quotas
+.PP
+To an ordinary user, having a disk quota is almost the same as having
+a smaller disk.
+When the amount of space available is consumed, further attempts to
+use more will fail.
 .PP
-To most users, disc quotas will either be of no concern,
-or a fact of life that cannot be avoided.
+To make this less painful, the quota system actually provides two
+limits for every resource: a
+\fIhard\fP
+limit and a
+\fIsoft\fP
+limit.
+The hard limit may not be exceeded.
+The soft limit may be exceeded temporarily: when the soft limit is
+first exceeded, a timer is initialized.
+If usage is reduced below the soft limit, the timer is cleared.
+Otherwise, when the timer expires, the soft limit becomes the hard
+limit: until usage is reduced below the soft limit, further use of
+space is denied.
+The length of time allowed is called the
+\fIgrace period\fP
+and is configurable by the system administrator.
+.PP
+Quotas may be applied to both users and groups.
+When both a user quota and a group quota apply, the most restrictive
+is used.
+.PP
+The basic purpose of quotas is to restrict the usage of disk space.
+This is measured in blocks.
+(For historical reasons, quotas are counted in terms of 512-octet
+blocks, even though most file systems use larger blocks internally.)
+Quotas can be imposed on other resource types too.
+Generally there will also be a quota on the number of files that may
+be owned.
+This functionality is supported by nearly all file system types that
+support quotas at all.
+Some file system types may support additional quotas on other file
+system resources.
+.PP
 The
 \fIquota\fP\|(1)
-command will provide information on any disc quotas
-that may have been imposed upon a user.
-.PP
-There are two individual possible quotas that may be
-imposed, usually if one is, both will be.
-A limit can be set on the amount of space a user
-can occupy, and there may be a limit on the number
-of files (inodes) he can own.
+command provides information on the disk quotas applying to a user or
+group.
+For each resource type, and each file system, it prints the current
+usage, the soft limit
+(`quota'),
+the hard limit
+(`limit'),
+and the expiration time of the current grace period, if any.
+User quotas are reported by default; the
+\fB\-g\fP
+flag allows retrieving group quotas.
 .PP
-.I Quota
-provides information on the quotas that have
-been set by the system administrators, in each
-of these areas, and current usage.
-.PP
-There are four numbers for each limit, the current
-usage, soft limit (quota), hard limit, and number
-of remaining login warnings.
-The soft limit is the number of 1K blocks (or files)
-that the user is expected to remain below.
-Each time the user's usage goes past this limit,
-he will be warned.
+The soft limit is the usage level that the user is expected to remain
+below.
+As described above, the soft limit can be exceeded temporarily;
+.\" XXX: does it really nowadays? I'm not so sure it does...
+doing so generates a warning.
 The hard limit cannot be exceeded.
-If a user's usage reaches this number, further
-requests for space (or attempts to create a file)
-will fail with an EDQUOT error, and the first time
+When the usage exceeds the applicable limit, further requests for
+space (or attempts to create a file, or allocate other resources)
+will fail with the
+EDQUOT
+error.
+The first time
 this occurs, a message will be written to the user's
 terminal.
-Only one message will be output, until space occupied
-is reduced below the limit, and reaches it again,
-in order to avoid continual noise from those
-programs that ignore write errors.
-.PP
-Whenever a user logs in with a usage greater than
-his soft limit, he will be warned, and his login
-warning count decremented.
-When he logs in under quota, the counter is reset
-to its maximum value (which is a system configuration
-parameter, that is typically 3).
-If the warning count should ever reach zero (caused
-by three successive logins over quota), the
-particular limit that has been exceeded will be treated
-as if the hard limit has been reached, and no
-more resources will be allocated to the user.
-The \fBonly\fP way to reset this condition is
-to reduce usage below quota, then log in again.
+To avoid flooding, the message will not be repeated until after the
+usage is lowered again.
 .NH 2 
 Surviving when quota limit is reached
 .PP
-In most cases, the only way to recover from over
-quota conditions, is to abort whatever activity was in progress
-on the filesystem that has reached its limit, remove
+In most cases, the only way to recover from an over-quota
+condition is to stop whatever activity was in progress, remove
 sufficient files to bring the limit back below quota,
 and retry the failed program.
 .PP
-However, if you are in the editor and a write fails
-because of an over quota situation, that is not
-a suitable course of action, as it is most likely
-that initially attempting to write the file
-will have truncated its previous contents, so should
-the editor be aborted without correctly writing the
-file not only will the recent changes be lost, but
-possibly much, or even all, of the data
-that previously existed.
+Be careful not to exit applications whose document save operations
+have or may have failed because of the over-quota conditions.
+This can often lead to losing data: the prior saved version of the
+document may have been replaced with an empty, partial, or invalid
+half-saved version.
+If it is not possible to open an additional terminal or other tools to
+do the clean-up work, use job control to suspend these applications
+rather than exiting.
+It may also be possible to save documents to a different file system
+(perhaps in /tmp)
+and then move them back into place after cleaning up.
+.NH 1
+Back-end quota implementations
+.PP
+In NetBSD there are three categories of quota implementations.
+First are file systems with native internal support for quotas.
+In these, the quota data is stored internally within the file system,
+maintained by the file system's own consistency management and
+\fIfsck\fP\|(8)
+utility, and active whenever the file system volume is mounted.
+The mechanism for setting up quotas on a particular volume is
+file-system-dependent but generally involves arguments to
+\fInewfs\fP\|(8)
+and/or
+\fItunefs\fP\|(8).
+The
+``quota2''
+quotas for
+FFS
+that appeared in
+NetBSD 6.0
+are an example of this type.
+.PP
+The second category is
+NFS.
+In NFS, quotas are handled by a separate SunRPC protocol not directly
+connected to the NFS mount.
+The quota utilities speak this protocol when invoked on NFS volumes.
+On an NFS server, the
+\fIrpc.rquotad\fP\|(8)
+daemon must be enabled to serve this protocol.
+See below for further details.
 .PP
-There are several possible safe exits for a user
-caught in this situation.
-He may use the editor \fB!\fP shell escape command to
-examine his file space, and remove surplus files.
-Alternatively, using \fIcsh\fP, he may suspend the
-editor, remove some files, then resume it.
-A third possibility, is to write the file to
-some other filesystem (perhaps to a file on /tmp)
-where the user's quota has not been exceeded.
-Then after rectifying the quota situation,
-the file can be moved back to the filesystem
-it belongs on.
+The third category is instances of the historical quota system,