Aquire serializer before calling ioctl
[dragonfly.git] / share / doc / smm / 04.quotas /
1 .\" Copyright (c) 1983, 1993
2 .\"     The Regents of the University of California.  All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\"    notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\"    notice, this list of conditions and the following disclaimer in the
11 .\"    documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\"    must display the following acknowledgement:
14 .\"     This product includes software developed by the University of
15 .\"     California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\"    may be used to endorse or promote products derived from this software
18 .\"    without specific prior written permission.
19 .\"
31 .\"
32 .\"     @(#)   8.1 (Berkeley) 6/8/93
33 .\"
34 .EH 'SMM:4-%''Disc Quotas in a \s-2UNIX\s+2 Environment'
35 .OH 'Disc Quotas in a \s-2UNIX\s+2 Environment''SMM:4-%'
36 .ND 5th July, 1983
37 .TL
38 Disc Quotas in a \s-2UNIX\s+2\s-3\u*\d\s0 Environment
39 .FS
40 * UNIX is a trademark of Bell Laboratories.
41 .FE
42 .AU
43 Robert Elz
44 .AI
45 Department of Computer Science
46 University of Melbourne,
47 Parkville,
48 Victoria,
49 Australia.
50 .AB
51 .PP
52 In most computing environments, disc space is not
53 infinite.
54 The disc quota system provides a mechanism
55 to control usage of disc space, on an
56 individual basis.
57 .PP
58 Quotas may be set for each individual user, on any, or
59 all filesystems.
60 .PP
61 The quota system will warn users when they
62 exceed their allotted limit, but allow some
63 extra space for current work.
64 Repeatedly remaining over quota at logout,
65 will cause a fatal over quota condition eventually.
66 .PP
67 The quota system is an optional part of
68 \s-2VMUNIX\s0 that may be included when the
69 system is configured.
70 .AE
71 .NH 1
72 Users' view of disc quotas
73 .PP
74 To most users, disc quotas will either be of no concern,
75 or a fact of life that cannot be avoided.
76 The
77 \fIquota\fP\|(1)
78 command will provide information on any disc quotas
79 that may have been imposed upon a user.
80 .PP
81 There are two individual possible quotas that may be
82 imposed, usually if one is, both will be.
83 A limit can be set on the amount of space a user
84 can occupy, and there may be a limit on the number
85 of files (inodes) he can own.
86 .PP
87 .I Quota
88 provides information on the quotas that have
89 been set by the system administrators, in each
90 of these areas, and current usage.
91 .PP
92 There are four numbers for each limit, the current
93 usage, soft limit (quota), hard limit, and number
94 of remaining login warnings.
95 The soft limit is the number of 1K blocks (or files)
96 that the user is expected to remain below.
97 Each time the user's usage goes past this limit,
98 he will be warned.
99 The hard limit cannot be exceeded.
100 If a user's usage reaches this number, further
101 requests for space (or attempts to create a file)
102 will fail with an EDQUOT error, and the first time
103 this occurs, a message will be written to the user's
104 terminal.
105 Only one message will be output, until space occupied
106 is reduced below the limit, and reaches it again,
107 in order to avoid continual noise from those
108 programs that ignore write errors.
109 .PP
110 Whenever a user logs in with a usage greater than
111 his soft limit, he will be warned, and his login
112 warning count decremented.
113 When he logs in under quota, the counter is reset
114 to its maximum value (which is a system configuration
115 parameter, that is typically 3).
116 If the warning count should ever reach zero (caused
117 by three successive logins over quota), the
118 particular limit that has been exceeded will be treated
119 as if the hard limit has been reached, and no
120 more resources will be allocated to the user.
121 The \fBonly\fP way to reset this condition is
122 to reduce usage below quota, then log in again.
123 .NH 2 
124 Surviving when quota limit is reached
125 .PP
126 In most cases, the only way to recover from over
127 quota conditions, is to abort whatever activity was in progress
128 on the filesystem that has reached its limit, remove
129 sufficient files to bring the limit back below quota,
130 and retry the failed program.
131 .PP
132 However, if you are in the editor and a write fails
133 because of an over quota situation, that is not
134 a suitable course of action, as it is most likely
135 that initially attempting to write the file
136 will have truncated its previous contents, so should
137 the editor be aborted without correctly writing the
138 file not only will the recent changes be lost, but
139 possibly much, or even all, of the data
140 that previously existed.
141 .PP
142 There are several possible safe exits for a user
143 caught in this situation.
144 He may use the editor \fB!\fP shell escape command to
145 examine his file space, and remove surplus files.
146 Alternatively, using \fIcsh\fP, he may suspend the
147 editor, remove some files, then resume it.
148 A third possibility, is to write the file to
149 some other filesystem (perhaps to a file on /tmp)
150 where the user's quota has not been exceeded.
151 Then after rectifying the quota situation,
152 the file can be moved back to the filesystem
153 it belongs on.
154 .NH 1
155 Administering the quota system
156 .PP
157 To set up and establish the disc quota system,
158 there are several steps necessary to be performed
159 by the system administrator.
160 .PP
161 First, the system must be configured to include
162 the disc quota sub-system.
163 This is done by including the line:
164 .DS
165 options   QUOTA
166 .DE
167 in the system configuration file, then running
168 \fIconfig\fP\|(8)
169 followed by a system configuration\s-3\u*\d\s0.
170 .FS
171 * See also the document ``Building 4.2BSD UNIX Systems with Config''.
172 .FE
173 .PP
174 Second, a decision as to what filesystems need to have
175 quotas applied needs to be made.
176 Usually, only filesystems that house users' home directories,
177 or other user files, will need to be subjected to
178 the quota system, though it may also prove useful to
179 also include \fB/usr\fR.
180 If possible, \fB/tmp\fP should usually be free of quotas.
181 .PP
182 Having decided on which filesystems quotas need to be
183 set upon, the administrator should then allocate the
184 available space amongst the competing needs. How this
185 should be done is (way) beyond the scope of this document.
186 .PP
187 Then, the
188 \fIedquota\fP\|(8)
189 command can be used to actually set the limits desired upon
190 each user. Where a number of users are to be given the
191 same quotas (a common occurrence) the \fB\-p\fP switch
192 to edquota will allow this to be easily accomplished.
193 .PP
194 Once the quotas are set, ready to operate, the system
195 must be informed to enforce quotas on the desired filesystems.
196 This is accomplished with the
197 \fIquotaon\fP\|(8)
198 command.
199 .I Quotaon
200 will either enable quotas for a particular filesystem, or
201 with the \fB\-a\fP switch, will enable quotas for each
202 filesystem indicated in \fB/etc/fstab\fP as using quotas.
203 See
204 \fIfstab\fP\|(5)
205 for details.
206 Most sites using the quota system, will include the
207 line
208 .DS C
209 /etc/quotaon -a
210 .DE
211 in \fB/etc/rc.local\fP.
212 .PP
213 Should quotas need to be disabled, the
214 \fIquotaoff\fP(8)
215 command will do that, however, should the filesystem be
216 about to be dismounted, the
217 \fIumount\fP\|(8)
218 command will disable quotas immediately before the
219 filesystem is unmounted.
220 This is actually an effect of the
221 \fIumount\fP\|(2)
222 system call, and it guarantees that the quota system
223 will not be disabled if the umount would fail
224 because the filesystem is not idle.
225 .PP
226 Periodically (certainly after each reboot, and when quotas
227 are first enabled for a filesystem), the records retained
228 in the quota file should be checked for consistency with
229 the actual number of blocks and files allocated to
230 the user.
231 The
232 \fIquotacheck\fP\|(8)
233 command can be used to accomplish this.
234 It is not necessary to dismount the filesystem, or disable
235 the quota system to run this command, though on
236 active filesystems inaccurate results may occur.
237 This does no real harm in most cases, another run of
238 .I quotacheck
239 when the filesystem is idle will certainly correct any inaccuracy.
240 .PP
241 The super-user may use the
242 \fIquota\fP\|(1)
243 command to examine the usage and quotas of any user, and
244 the
245 \fIrepquota\fP\|(8)
246 command may be used to check the usages and limits for
247 all users on a filesystem.
248 .NH 1
249 Some implementation detail.
250 .PP
251 Disc quota usage and information is stored in a file on the
252 filesystem that the quotas are to be applied to.
253 Conventionally, this file is \fBquotas\fR in the root of
254 the filesystem.
255 While this name is not known to the system in any way,
256 several of the user level utilities "know" it, and
257 choosing any other name would not be wise.
258 .PP
259 The data in the file comprises an array of structures, indexed
260 by uid, one structure for each user on the system (whether
261 the user has a quota on this filesystem or not).
262 If the uid space is sparse, then the file may have holes
263 in it, which would be lost by copying, so it is best to
264 avoid this.
265 .PP
266 The system is informed of the existence of the quota
267 file by the
268 \fIsetquota\fP\|(2)
269 system call.
270 It then reads the quota entries for each user currently
271 active, then for any files open owned by users who
272 are not currently active.
273 Each subsequent open of a file on the filesystem, will
274 be accompanied by a pairing with its quota information.
275 In most cases this information will be retained in core,
276 either because the user who owns the file is running some
277 process, because other files are open owned by the same
278 user, or because some file (perhaps this one) was recently
279 accessed.
280 In memory, the quota information is kept hashed by user-id
281 and filesystem, and retained in an LRU chain so recently
282 released data can be easily reclaimed.
283 Information about those users whose last process has
284 recently terminated is also retained in this way.
285 .PP
286 Each time a block is accessed or released, and each time an inode
287 is allocated or freed, the quota system gets told
288 about it, and in the case of allocations, gets the
289 opportunity to object.
290 .PP
291 Measurements have shown
292 that the quota code uses a very small percentage of the system
293 cpu time consumed in writing a new block to disc.
294 .NH 1
295 Acknowledgments
296 .PP
297 The current disc quota system is loosely based upon a very
298 early scheme implemented at the University of New South
299 Wales, and Sydney University in the mid 70's. That system
300 implemented a single combined limit for both files and blocks
301 on all filesystems.
302 .PP
303 A later system was implemented at the University of Melbourne
304 by the author, but was not kept highly accurately, eg:
305 chown's (etc) did not affect quotas, nor did i/o to a file
306 other than one owned by the instigator.
307 .PP
308 The current system has been running (with only minor modifications)
309 since January 82 at Melbourne.
310 It is actually just a small part of a much broader resource
311 control scheme, which is capable of controlling almost
312 anything that is usually uncontrolled in unix. The rest
313 of this is, as yet, still in a state where it is far too
314 subject to change to be considered for distribution.
315 .PP
316 For the 4.2BSD release, much work has been done to clean
317 up and sanely incorporate the quota code by Sam Leffler and
318 Kirk McKusick at The University of California at Berkeley.