]>
Commit | Line | Data |
---|---|---|
42cf2b97 NS |
1 | .TH xfs_quota 8 |
2 | .SH NAME | |
3 | xfs_quota \- manage use of quota on XFS filesystems | |
4 | .SH SYNOPSIS | |
5 | .nf | |
6 | \f3xfs_quota\f1 [ \f3\-x\f1 ] [ \f3\-p\f1 prog ] [ \f3\-c\f1 cmd ] ... | |
7 | [ \f3\-d\f1 project ] ... [path...] | |
8 | .fi | |
9 | .SH DESCRIPTION | |
10 | \f2xfs_quota\f1 is a utility for reporting and editing various | |
11 | aspects of filesystem quota. | |
12 | .PP | |
13 | The options to \f2xfs_quota\f1 are: | |
14 | .TP 10 | |
15 | \f3\-c\f1 \f2cmd\f1 | |
16 | \f2xfs_quota\f1 commands may be run interactively (the default) | |
17 | or as arguments on the command line. | |
18 | Multiple \f3\-c\f1 arguments may be given. | |
19 | The commands are run in the sequence given, then the program exits. | |
20 | .TP | |
21 | \f3\-p\f1 \f2prog\f1 | |
22 | Set the program name for prompts and some error messages, | |
23 | the default value is \f2xfs_quota\f1. | |
24 | .TP | |
25 | \f3\-x\f1 | |
26 | Enable expert mode. | |
27 | All of the administrative commands (see the ADMINISTRATOR COMMANDS | |
28 | section below) which allow modifications to the quota system are | |
29 | available only in expert mode. | |
30 | .TP | |
31 | \f3\-d\f1 \f2project\f1 | |
32 | Project names or numeric identifiers may be specified with this option, | |
33 | which restricts the output of the individual \f3xfs_quota\f1 commands | |
34 | to the set of projects specified. | |
35 | Multiple \f3\-d\f1 arguments may be given. | |
36 | .PP | |
37 | The optional \f2path\f1 argument(s) can be used to specify mount | |
38 | points or device files which identify XFS filesystems. | |
39 | The output of the individual \f3xfs_quota\f1 commands will then | |
40 | be restricted to the set of filesystems specified. | |
41 | .PP | |
42 | This manual page is divided into two sections \- firstly, | |
43 | information for users of filesystems with quota enabled, and the | |
44 | .B xfs_quota | |
45 | commands of interest to such users; and then information which is | |
46 | useful only to administrators of XFS filesystems using quota and the | |
47 | quota commands which allow modifications to the quota system. | |
48 | .PP | |
49 | Note that common to almost all of the individual commands described | |
50 | below are the options for specifying which quota types are of interest | |
51 | \- user quota (\f2\-u\f1), group quota (\f2\-g\f1), and/or project | |
52 | quota (\f2\-p\f1). | |
53 | Also, several commands provide options to operate on "blocks used" | |
54 | (\f2\-b\f1), "inodes used" (\f2\-i\f1), and/or "realtime blocks used" | |
55 | (\f2\-r\f1). | |
56 | .PP | |
57 | Many commands also have extensive online help. | |
58 | Use the \f3help\f1 command for more details on any command. | |
59 | .SH QUOTA OVERVIEW | |
60 | .PP | |
61 | In most computing environments, disk space is not infinite. | |
62 | The quota subsystem provides a mechanism to control usage of disk space. | |
63 | Quotas can be set for each individual user on any/all of the local | |
64 | filesystems. | |
65 | The quota subsystem warns users when they exceed their allotted limit, | |
66 | but allows some extra space for current work (hard limit/soft limit). | |
67 | In addition, XFS filesystems with limit enforcement turned off can be | |
68 | used as an effective disk usage accounting system. | |
69 | .SS Users' View of Disk Quotas | |
70 | To most users, disk quotas are either of no concern or a fact of life | |
71 | that cannot be avoided. | |
72 | There are two possible quotas that can be imposed \- a limit can be set | |
73 | on the amount of space a user can occupy, and there may be a limit on | |
74 | the number of files (inodes) he can own. | |
75 | .br | |
76 | The \f2quota\f1 command provides information on the quotas that have been | |
77 | set by the system administrators and current usage. | |
78 | .br | |
79 | There are four numbers for each limit: current usage, soft limit | |
80 | (quota), hard limit, and time limit. | |
81 | The soft limit is the number of 1K-blocks (or files) that the user is | |
82 | expected to remain below. | |
83 | The hard limit cannot be exceeded. | |
84 | If a user's usage reaches the hard limit, further requests for space | |
85 | (or attempts to create a file) fail with the "Quota exceeded" (EDQUOT) | |
86 | error. | |
87 | .br | |
88 | When a user exceeds the soft limit, the timer is enabled. | |
89 | Any time the quota drops below the soft limits, the timer is disabled. | |
90 | If the timer pops, the particular limit that has been exceeded is treated | |
91 | as if the hard limit has been reached, and no more resources are allocated | |
92 | to the user. | |
93 | The only way to reset this condition, short of turning off limit | |
94 | enforcement or increasing the limit, is to reduce usage below quota. | |
95 | Only the superuser (i.e. a sufficiently capable process) can set the | |
96 | time limits and this is done on a per filesystem basis. | |
97 | .SS Surviving When the Quota Limit Is Reached | |
98 | In most cases, the only way for a user to recover from over-quota | |
99 | conditions is to abort whatever activity is in progress on the filesystem | |
100 | that has reached its limit, remove sufficient files to bring the limit | |
101 | back below quota, and retry the failed program. | |
102 | .br | |
103 | However, if a user is in the editor and a write fails because of an over | |
104 | quota situation, that is not a suitable course of action. | |
105 | It is most likely that initially attempting to write the file has truncated | |
106 | its previous contents, so if the editor is aborted without correctly writing | |
107 | the file, not only are the recent changes lost, but possibly much, or even | |
108 | all, of the contents that previously existed. | |
109 | .br | |
110 | There are several possible safe exits for a user caught in this situation. | |
111 | He can use the editor shell escape command to examine his file space | |
112 | and remove surplus files. Alternatively, using | |
113 | .BR sh (1), | |
114 | he can suspend | |
115 | the editor, remove some files, then resume it. | |
116 | A third possibility is to write the file to some other filesystem (perhaps | |
117 | to a file on \f2/tmp\f1) where the user's quota has not been exceeded. | |
118 | Then after rectifying the quota situation, the file can be moved back to the | |
119 | filesystem it belongs on. | |
120 | .SH USER COMMANDS | |
121 | .TP | |
122 | \f3path\f1 [ \f2N\f1 ] | |
123 | Lists all paths with devices/project identifiers or set the current | |
124 | path to the \f2N\f1th list entry (the current path is used by many | |
125 | of the commands described here, it identifies the filesystem toward | |
126 | which a command is directed). | |
127 | The path list can come from several places \- the command line, | |
128 | the mount table, and the \f2/etc/projects\f1 file. | |
129 | .TP | |
130 | \f3df\f1 | |
131 | See the \f3free\f1 command. | |
132 | .TP | |
133 | \f3quota\f1 [ \f2\-gpu\f1 ] [ \f2\-bir\f1 ] [ \f2\-hnNv\f1 ] [ id|name ] ... | |
134 | Show individual usage and limits, for a single user name or numeric | |
135 | user ID. | |
136 | The \f2\-h\f1 option reports in a "human-readable" format similar | |
137 | to the | |
138 | .BR df (1) | |
139 | command. | |
140 | .TP | |
141 | \f3free\f1 [ \f2\-bir\f1 ] [ \f2\-hN\f1 ] | |
142 | Reports filesystem usage, much like the | |
143 | .BR df (1) | |
144 | utility. | |
145 | It can show usage for blocks, inode, and/or realtime block space, | |
146 | and shows used, free, and total available. | |
147 | If directory quota are in use (see the DIRECTORY QUOTA section below), | |
148 | it will also report utilisation for those directory trees. | |
149 | The \f2\-h\f1 option reports in a "human-readable" format, | |
150 | .TP | |
151 | \f3help\f1 [ \f2command\f1] | |
152 | Online help for all commands, or one specific \f2command\f1. | |
153 | .TP | |
154 | \f3quit\f1 | |
155 | Exit \f2xfs_quota\f1. | |
156 | .TP | |
157 | \f3q\f1 | |
158 | See the \f3quit\f1 command. | |
159 | .SH QUOTA ADMINISTRATION | |
160 | The XFS quota system differs to that of other filesystems | |
161 | in a number of ways. | |
162 | Most importantly, XFS considers quota information as | |
163 | filesystem metadata and uses journaling to provide a higher level | |
164 | guarantee of consistency. | |
165 | As such, it is administered differently, in particular: | |
166 | .TP | |
167 | 1. | |
2a1888c5 NS |
168 | The |
169 | .B quotacheck | |
170 | command has no effect on XFS filesystems. | |
42cf2b97 NS |
171 | The first time quota accounting is turned on (at mount time), XFS does |
172 | an automatic quotacheck internally; afterwards, the quota system will | |
173 | always be completely consistent until quotas are manually turned off. | |
174 | .TP | |
175 | 2. | |
176 | There is no need for quota file(s) in the root of the XFS filesystem. | |
177 | .TP | |
178 | 3. | |
179 | XFS distinguishes between quota accounting and limit enforcement. | |
180 | Quota accounting must be turned on at the time of mounting the XFS | |
181 | filesystem. | |
182 | However, it is possible to turn on/off limit enforcement any time | |
183 | quota accounting is turned on. | |
184 | The "quota" option to the | |
2a1888c5 | 185 | .B mount |
42cf2b97 NS |
186 | command turns on both (user) quota accounting and enforcement. |
187 | The "uqnoenforce" option must be used to turn on user accounting with | |
188 | limit enforcement disabled. | |
189 | .TP | |
190 | 4. | |
191 | Turning on quotas on the root filesystem is slightly different from | |
192 | the above. | |
193 | For IRIX XFS, refer to | |
2a1888c5 | 194 | .BR quotaon (1M). |
42cf2b97 NS |
195 | For Linux XFS, the quota mount flags must be passed in with the |
196 | "rootflags=" boot parameter. | |
197 | .TP | |
198 | 5. | |
199 | It is useful to use the \f2state\f1 to monitor the XFS quota subsystem | |
200 | at various stages \- it can be used to see if quotas are turned on, | |
201 | and also to monitor the space occupied by the quota system itself.. | |
202 | .TP | |
203 | 6. | |
204 | There is a mechanism built into | |
2a1888c5 | 205 | .B xfsdump |
42cf2b97 NS |
206 | that allows quota limit information to be backed up for later |
207 | restoration, should the need arise. | |
208 | .TP | |
209 | 7. | |
210 | Quota limits cannot be set before turning on quotas on. | |
211 | .TP | |
212 | 8. | |
213 | XFS filesystems keep quota accounting on the superuser (user ID zero), | |
214 | and the tool will display the superuser's usage information. | |
215 | However, limits are never enforced on the superuser (nor are they | |
216 | enforced for group and project ID zero). | |
217 | .TP | |
218 | 9. | |
219 | XFS filesystems perform quota accounting whether the user has quota | |
220 | limits or not. | |
221 | .TP | |
222 | 10. | |
223 | XFS supports the notion of project quota, which can be used to | |
224 | implement a form of directory tree quota (i.e. to restrict a | |
225 | directory tree to only being able to use up a component of the | |
226 | filesystems available space; or simply to keep track of the | |
227 | amount of space used, or number of inodes, within the tree). | |
228 | .SH ADMINISTRATOR COMMANDS | |
229 | .TP | |
230 | \f3report\f1 [ \f2\-gpu\f1 ] [ \f2\-bir\f1 ] [ \f2\-ahnNt\f1 ] | |
231 | Report filesystem quota information. | |
232 | This reports all quota usage for a filesystem, for the specified | |
233 | quota type (u/g/p and/or blocks/inodes/realtime). | |
234 | It reports blocks in 1KB units by default. | |
235 | The \f2\-h\f1 option reports in a "human-readable" format similar | |
236 | to the | |
237 | .BR df (1) | |
238 | command. | |
239 | .TP | |
240 | \f3state\f1 [ \f2\-gpu\f1 ] | |
241 | Report overall quota state information. | |
242 | This reports on the state of quota accounting, quota enforcement, | |
243 | and the number of extents being used by quota metadata within the | |
244 | filesystem. | |
245 | .TP | |
246 | \f3limit\f1 [ \f2\-gpu\f1 ] \\ | |
247 | \f2bsoft\f1=N | \f2bhard\f1=N | \f2isoft\f1=N | \f2ihard\f1=N | \f2rtbsoft\f1=N | \f2rtbhard\f1=N... \-d|id|name | |
248 | .br | |
249 | Set quota block limits (bhard/bsoft), inode count limits (ihard/isoft) | |
250 | and/or realtime block limits (rtbhard/rtbsoft). | |
251 | The \f2\-d\f1 option (defaults) can be used to set the default value | |
252 | that will be used, otherwise a specific user/group/project name or | |
253 | numeric identifier must be specified. | |
254 | .TP | |
255 | \f3timer\f1 [ \f2\-gpu\f1 ] [ \f2\-bir\f1 ] value | |
256 | Allows the quota enforcement timeout (i.e. the amount of time allowed | |
257 | to pass before the soft limits are enforced as the hard limits) to | |
258 | be modified. | |
259 | The current timeout setting can be displayed using the \f3state\f1 command. | |
260 | The value argument is a number of seconds, but units of 'seconds', | |
261 | 'minutes', 'hours', 'days', and 'weeks' are also understood | |
262 | (as are their abbreviations, 's', 'm', 'h', 'd', and 'w'). | |
263 | .TP | |
264 | \f3warn\f1 [ \f2\-gpu\f1 ] [ \f2\-bir\f1 ] value \-d|id|name | |
265 | Allows the quota warnings limit (i.e. the number of times a warning | |
266 | will be send to someone over quota) to be viewed and modified. | |
267 | The \f2\-d\f1 option (defaults) can be used to set the default time | |
268 | that will be used, otherwise a specific user/group/project name or | |
269 | numeric identifier must be specified. | |
270 | NOTE: this feature is not currently implemented. | |
271 | .TP | |
272 | \f3enable\f1 [ \f2\-gpu\f1 ] [ \f2\-v\f1 ] | |
273 | Switches on quota enforcement for the filesystem identified by the | |
274 | current path. | |
275 | This requires the filesystem to have been mounted with quota enabled, | |
276 | and for accounting to be currently active. | |
277 | The \f2\-v\f1 option (verbose) displays the state after the operation | |
278 | has completed. | |
279 | .TP | |
280 | \f3disable\f1 [ \f2\-gpu\f1 ] [ \f2\-v\f1 ] | |
281 | Disables quota enforcement, while leaving quota accounting active. | |
282 | The \f2\-v\f1 option (verbose) displays the state after the operation | |
283 | has completed. | |
284 | .TP | |
285 | \f3off\f1 [ \f2\-gpu\f1 ] [ \f2\-v\f1 ] | |
286 | Permanently switches quota off for the filesystem identified by the | |
287 | current path. | |
288 | Quota can only be switched back on subsequently by unmounting and | |
289 | then mounting again. | |
290 | .TP | |
291 | \f3remove\f1 [ \f2\-gpu\f1 ] [ \f2\-v\f1 ] | |
292 | Remove any space allocated to quota metadata from the filesystem | |
293 | identified by the current path. | |
294 | Quota must not be enabled on the filesystem, else this operation will | |
295 | report an error. | |
296 | .TP | |
297 | \f3dump\f1 [ \f2\-gpu\f1 ] [ \f2\-f\f1 \f2file\f1 ] | |
298 | Dump out quota limit information for backup utilities, either to | |
299 | standard output (default) or to a file. | |
300 | This is only the limits, not the usage information, of course. | |
301 | .TP | |
302 | \f3restore\f1 [ \f2\-gpu\f1 ] [ \f2\-f\f1 \f2file\f1 ] | |
303 | Restore quota limits from a backup \f2file\f1. | |
304 | The file must be in the format produced by the \f3dump\f1 command. | |
305 | .TP | |
306 | \f3quot\f1 [ \f2\-gpu\f1 ] [ \f2\-bir\f1 ] [ \f2\-av\f1 ] [ \f2\-c\f1 ] | |
307 | Summarize filesystem ownership, by user, group or project. | |
308 | This command uses a special XFS "bulkstat" interface to quickly scan | |
309 | an entire filesystem and report usage information. | |
310 | This command can be used even when filesystem quota are not enabled, | |
311 | as it is a full-filesystem scan (it may also take a long time...). | |
312 | .TP | |
313 | \f3project\f1 [ \f2\-cds\f1 id|name ] | |
314 | Without arguments, this command lists known project names and identifiers | |
315 | (based on entries in the | |
316 | .I /etc/projects | |
317 | and | |
318 | .I /etc/projid | |
319 | files). | |
320 | The \f2\-c\f1, \f2\-C\f1, and \f2\-s\f1 options allow the directory | |
321 | tree quota mechanism, discussed in detail below, to be maintained. | |
322 | .SH TREE QUOTA | |
323 | The project quota mechanism in XFS can be used to implement a form of | |
324 | directory tree quota, where a specified directory and all of the files | |
325 | and subdirectories below it (i.e. a tree) can be restricted to using | |
326 | a subset of the available space in the filesystem. | |
327 | .PP | |
328 | A managed tree must be setup initially using the | |
329 | \f2\-c\f1 option to the \f3project\f1 command. | |
330 | The specified project name or identifier is matched to one or more trees | |
331 | defined in | |
332 | .IR /etc/projects , | |
333 | and these trees are then recursively descended | |
334 | to mark the affected inodes as being part of that tree. | |
335 | This process sets an inode flag and the project identifier on every file | |
336 | in the affected tree. | |
337 | Once this has been done, new files created in the tree will automatically | |
338 | be accounted to the tree based on their project identifier. | |
339 | An attempt to create a hard link to a file in the tree will only succeed | |
340 | if the project identifier matches the project identifier for the tree. | |
341 | The | |
342 | .B xfs_io | |
343 | utility can be used to set the project ID for an arbitrary file, but this | |
344 | can only be done by a privileged user. | |
345 | .PP | |
346 | A previously setup tree can be cleared from project quota control through | |
347 | use of the \f3project\f1 \f2\-C\f1 option, which will recursively descend | |
348 | the tree, clearing the affected inodes from project quota control. | |
349 | .PP | |
350 | Finally, the \f3project\f1 \f2\-c\f1 option can be used to check whether a | |
351 | tree is setup, it reports nothing if the tree is correct, otherwise it | |
352 | reports the paths of inodes which do not have the project ID of the rest | |
353 | of the tree, or if the inode flag is not set. | |
354 | .SH FILE FORMATS | |
355 | There are two files involved with the tree quota mechanism, namely | |
356 | .I /etc/projects | |
357 | and | |
358 | .IR /etc/projid . | |
359 | The latter is optional. | |
360 | The | |
361 | .I projects | |
362 | file provides a mapping between numeric project identifiers and those | |
363 | directories which are the roots of the quota tree. | |
364 | Its format is simply: | |
365 | .nf | |
366 | .sp .8v | |
367 | .in +5 | |
368 | # comments are hash-prefixed | |
369 | # ... | |
370 | 10:/export/cage | |
371 | 42:/var/log | |
372 | .in -5 | |
373 | .fi | |
374 | .PP | |
375 | The | |
376 | .I projid | |
377 | file provides a mapping between numeric project identifiers and a | |
378 | simple human readable name (similar relationship to the one that | |
379 | exists between usernames and uids). | |
380 | Its format is simply: | |
381 | .nf | |
382 | .sp .8v | |
383 | .in +5 | |
384 | # comments are hash-prefixed | |
385 | # ... | |
386 | 10:cage | |
387 | 42:logfiles | |
388 | .in -5 | |
389 | .fi | |
390 | .PP | |
391 | This file is optional, if a project identifier cannot be mapped to | |
392 | a name, it will be displayed as a number only. | |
393 | .PP | |
394 | .SH EXAMPLES | |
395 | Enabling quota enforcement on an XFS filesystem (restrict a user | |
396 | to a set amount of space). | |
397 | .nf | |
398 | .sp .8v | |
399 | .in +5 | |
56122696 | 400 | # mount \-o uquota /dev/xvm/home /home |
3dfde25b | 401 | # xfs_quota \-x \-c 'limit bsoft=500m bhard=550m tanya' /home |
56122696 | 402 | # xfs_quota \-c report /home |
42cf2b97 NS |
403 | .in -5 |
404 | .fi | |
405 | .PP | |
406 | Enabling directory quota on an XFS filesystem (restrict files in | |
407 | log file directories to only using 1 gigabyte of space). | |
408 | .nf | |
409 | .sp .8v | |
410 | .in +5 | |
56122696 | 411 | # mount \-o pquota /dev/xvm/var /var |
42cf2b97 NS |
412 | # echo 42:/var/log >> /etc/projects |
413 | # echo logfiles:42 >> /etc/projid | |
3dfde25b NS |
414 | # xfs_quota \-x \-c 'projects \-c logfiles' /home |
415 | # xfs_quota \-x \-c 'limit \-p bhard=1g logfiles' /home | |
42cf2b97 NS |
416 | .in -5 |
417 | .fi | |
418 | .SH CAVEATS | |
419 | XFS implements delayed allocation (aka. allocate-on-flush) and this | |
420 | has implications for the quota subsystem. | |
421 | Since quota accounting can only be done when blocks are actually | |
422 | allocated, it is possible to issue (buffered) writes into a file | |
423 | and not see the usage immediately updated. | |
424 | Only when the data is actually written out, either via one of the | |
425 | kernels flushing mechanisms, or via a manual | |
426 | .BR sync (2), | |
427 | will the usage reported reflect what has actually been written. | |
428 | .PP | |
429 | In addition, the XFS allocation mechanism will always reserve the | |
430 | maximum amount of space required before proceeding with an allocation. | |
431 | If insufficient space for this reservation is available, due to the | |
432 | block quota limit being reached for example, this may result in the | |
433 | allocation failing even though there is sufficient space. | |
434 | Quota enforcement can thus sometimes happen in situations where the | |
435 | user is under quota and the end result of some operation would still | |
436 | have left the user under quota had the operation been allowed to run | |
437 | its course. | |
438 | This additional overhead is typically in the range of tens of blocks. | |
439 | .PP | |
440 | Both of these properties are unavoidable side effects of the way XFS | |
441 | operates, so should be kept in mind when assigning block limits. | |
442 | .SH BUGS | |
443 | Quota support for filesystems with realtime subvolumes is not yet | |
444 | implemented, nor is the quota warning mechanism (the Linux | |
445 | .BR warnquota (8) | |
446 | tool can be used to provide similar functionality on that platform). | |
447 | .SH FILES | |
448 | .PD 0 | |
449 | .TP 20 | |
450 | .BR /etc/projects | |
451 | Mapping of numeric project identifiers to directories trees. | |
452 | .TP | |
453 | .BR /etc/projid | |
454 | Mapping of numeric project identifiers to project names. | |
455 | .PD | |
2a1888c5 NS |
456 | .SH IRIX SEE ALSO |
457 | quotaon(1M), | |
458 | xfs(4). | |
459 | ||
460 | .SH LINUX SEE ALSO | |
461 | warnquota(8), | |
462 | xfs(5). | |
463 | ||
42cf2b97 NS |
464 | .SH SEE ALSO |
465 | df(1), | |
466 | mount(1), | |
467 | sync(2), |