Debian Codegraph @

upstream/debian-unstable/man8/xfs_quota.8

raw
1 .TH xfs_quota 8
2 .SH NAME
3 xfs_quota \- manage use of quota on XFS filesystems
4 .SH SYNOPSIS
5 .B xfs_quota
6 [
7 .B \-x
8 ] [
9 .B \-f
10 ] [
11 .B \-p
12 .I prog
13 ] [
14 .B \-c
15 .I cmd
16 ] ... [
17 .B \-d
18 .I project
19 ] ... [
20 .B \-D
21 .I projects_file
22 ] [
23 .B \-P
24 .I projid_file
25 ] [
26 .IR path " ... ]"
27 .br
28 .B xfs_quota \-V
29 .SH DESCRIPTION
30 .B xfs_quota
31 is a utility for reporting and editing various aspects of filesystem quota.
32 .PP
33 The options to
34 .B xfs_quota
35 are:
36 .TP 1.0i
37 .BI \-c " cmd"
38 .B xfs_quota
39 commands may be run interactively (the default) or as arguments on
40 the command line. Multiple
41 .B \-c
42 arguments may be given.
43 The commands are run in the sequence given, then the program exits.
44 .TP
45 .BI \-p " prog"
46 Set the program name for prompts and some error messages,
47 the default value is
48 .BR xfs_quota .
49 .TP
50 .B \-x
51 Enable expert mode.
52 All of the administrative commands (see the ADMINISTRATOR COMMANDS
53 section below) which allow modifications to the quota system are
54 available only in expert mode.
55 .TP
56 .B \-f
57 Enable foreign filesystem mode.
58 A limited number of user and administrative commands are available for
59 use on some foreign (non-XFS) filesystems.
60 .TP
61 .BI \-d " project"
62 Project names or numeric identifiers may be specified with this option,
63 which restricts the output of the individual
64 .B xfs_quota
65 commands to the set of projects specified. Multiple
66 .B \-d
67 arguments may be given.
68 .TP
69 .BI \-D " projects_file"
70 Specify a file containing the mapping of numeric project identifiers
71 to directory trees.
72 .I /etc/projects
73 as default, if this option is none.
74 .TP
75 .BI \-P " projid_file"
76 Specify a file containing the mapping of numeric project identifiers
77 to project names.
78 .I /etc/projid
79 as default, if this option is none.
80 .TP
81 .B \-V
82 Prints the version number and exits.
83 .PP
84 The optional
85 .I path
86 argument(s) can be used to specify mount points or device files
87 which identify XFS filesystems. The output of the individual
88 .B xfs_quota
89 commands will then be restricted to the set of filesystems specified.
90 .PP
91 This manual page is divided into two sections \- firstly,
92 information for users of filesystems with quota enabled, and the
93 .B xfs_quota
94 commands of interest to such users; and then information which is
95 useful only to administrators of XFS filesystems using quota and the
96 quota commands which allow modifications to the quota system.
97 .PP
98 Note that common to almost all of the individual commands described
99 below are the options for specifying which quota types are of interest
100 \- user quota
101 .RB ( \-u ),
102 group quota
103 .RB ( \-g ),
104 and/or project quota
105 .RB ( \-p ).
106 Also, several commands provide options to operate on "blocks used"
107 .RB ( \-b ),
108 "inodes used"
109 .RB ( \-i ),
110 and/or "realtime blocks used"
111 .RB ( \-r ).
112 .PP
113 Many commands also have extensive online help. Use the
114 .B help
115 command for more details on any command.
116 .SH QUOTA OVERVIEW
117 .PP
118 In most computing environments, disk space is not infinite.
119 The quota subsystem provides a mechanism to control usage of disk space.
120 Quotas can be set for each individual user on any/all of the local
121 filesystems.
122 The quota subsystem warns users when they exceed their allotted limit,
123 but allows some extra space for current work (hard limit/soft limit).
124 In addition, XFS filesystems with limit enforcement turned off can be
125 used as an effective disk usage accounting system.
126 .SS Users' View of Disk Quotas
127 To most users, disk quotas are either of no concern or a fact of life
128 that cannot be avoided.
129 There are two possible quotas that can be imposed \- a limit can be set
130 on the amount of space a user can occupy, and there may be a limit on
131 the number of files (inodes) they can own.
132 .PP
133 The
134 .B quota
135 command provides information on the quotas that have been
136 set by the system administrators and current usage.
137 .PP
138 There are four numbers for each limit: current usage, soft limit
139 (quota), hard limit, and time limit.
140 The soft limit is the number of 1K-blocks (or files) that the user is
141 expected to remain below.
142 The hard limit cannot be exceeded.
143 If a user's usage reaches the hard limit, further requests for space
144 (or attempts to create a file) fail with the "Quota exceeded" (EDQUOT)
145 error.
146 .PP
147 When a user exceeds the soft limit, the timer is enabled.
148 Any time the quota drops below the soft limits, the timer is disabled.
149 If the timer pops, the particular limit that has been exceeded is treated
150 as if the hard limit has been reached, and no more resources are allocated
151 to the user.
152 The only way to reset this condition, short of turning off limit
153 enforcement or increasing the limit, is to reduce usage below quota.
154 Only the superuser (i.e. a sufficiently capable process) can set the
155 time limits and this is done on a per filesystem basis.
156 .SS Surviving When the Quota Limit Is Reached
157 In most cases, the only way for a user to recover from over-quota
158 conditions is to abort whatever activity is in progress on the filesystem
159 that has reached its limit, remove sufficient files to bring the limit
160 back below quota, and retry the failed program.
161 .br
162 However, if a user is in the editor and a write fails because of an over
163 quota situation, that is not a suitable course of action.
164 It is most likely that initially attempting to write the file has truncated
165 its previous contents, so if the editor is aborted without correctly writing
166 the file, not only are the recent changes lost, but possibly much, or even
167 all, of the contents that previously existed.
168 .br
169 There are several possible safe exits for a user caught in this situation.
170 They can use the editor shell escape command to examine their file space
171 and remove surplus files. Alternatively, using
172 .BR sh (1),
173 they can suspend
174 the editor, remove some files, then resume it.
175 A third possibility is to write the file to some other filesystem (perhaps
176 to a file on
177 .IR /tmp )
178 where the user's quota has not been exceeded.
179 Then after rectifying the quota situation, the file can be moved back to the
180 filesystem it belongs on.
181 .SS Default Quotas
182 The XFS quota subsystem allows a default quota to be enforced
183 for any user, group or project which does not have a quota limit
184 explicitly set.
185 These limits are stored in and displayed as ID 0's limits, although they
186 do not actually limit ID 0.
187 .SH USER COMMANDS
188 .TP
189 .B print
190 Lists all paths with devices/project identifiers.
191 The path list can come from several places \- the command line,
192 the mount table, and the
193 .I /etc/projects
194 file.
195 .TP
196 .B df
197 See the
198 .B free
199 command.
200 .HP
201 .B quota
202 [
203 .BR \-g " | " \-p " | " \-u
204 ] [
205 .B \-bir
206 ] [
207 .B \-hnNv
208 ] [
209 .B \-f
210 .I file
211 ] [
212 .I ID
213 |
214 .I name
215 ] ...
216 .br
217 Show individual usage and limits, for a single user
218 .I name
219 or numeric user
220 .IR ID .
221 The
222 .B \-h
223 option reports in a "human-readable" format similar to the
224 .BR df (1)
225 command. The
226 .B \-n
227 option reports the numeric IDs rather than the name. The
228 .B \-N
229 option omits the header. The
230 .B \-v
231 option outputs verbose information. The
232 .B \-f
233 option sends the output to
234 .I file
235 instead of stdout.
236 .HP
237 .B free
238 [
239 .B \-bir
240 ] [
241 .B \-hN
242 ] [
243 .B \-f
244 .I file
245 ]
246 .br
247 Reports filesystem usage, much like the
248 .BR df (1)
249 utility.
250 It can show usage for
251 .BR b locks,
252 .BR i node,
253 and/or
254 .BR r ealtime
255 block space, and shows used, free, and total available.
256 If project quota are in use (see the DIRECTORY TREE QUOTA section below),
257 it will also report utilisation for those projects (directory trees). The
258 .B \-h
259 option reports in a "human-readable" format. The
260 .B \-N
261 option omits the header. The
262 .B \-f
263 option outputs the report to
264 .I file
265 instead of stdout.
266 .HP
267 .B help
268 [
269 .I command
270 ]
271 .br
272 Online help for all commands, or one specific
273 .IR command .
274 .TP
275 .B quit
276 Exit
277 .BR xfs_quota .
278 .TP
279 .B q
280 See the
281 .B quit
282 command.
283 .SH QUOTA ADMINISTRATION
284 The XFS quota system differs to that of other filesystems
285 in a number of ways.
286 Most importantly, XFS considers quota information as
287 filesystem metadata and uses journaling to provide a higher level
288 guarantee of consistency.
289 As such, it is administered differently, in particular:
290 .IP 1.
291 The
292 .B quotacheck
293 command has no effect on XFS filesystems.
294 The first time quota accounting is turned on (at mount time), XFS does
295 an automatic quotacheck internally; afterwards, the quota system will
296 always be completely consistent until quotas are manually turned off.
297 .IP 2.
298 There is no need for quota file(s) in the root of the XFS filesystem.
299 .IP 3.
300 XFS distinguishes between quota accounting and limit enforcement.
301 Quota accounting must be turned on at the time of mounting the XFS
302 filesystem.
303 However, it is possible to turn on/off limit enforcement any time
304 quota accounting is turned on.
305 The "quota" option to the
306 .B mount
307 command turns on both (user) quota accounting and enforcement.
308 The "uqnoenforce" option must be used to turn on user accounting with
309 limit enforcement disabled.
310 .IP 4.
311 Turning on quotas on the root filesystem is slightly different from
312 the above.
313 For Linux XFS, the quota mount flags must be passed in with the
314 "rootflags=" boot parameter.
315 .IP 5.
316 It is useful to use the
317 .B state
318 to monitor the XFS quota subsystem
319 at various stages \- it can be used to see if quotas are turned on,
320 and also to monitor the space occupied by the quota system itself..
321 .IP 6.
322 There is a mechanism built into
323 .B xfsdump
324 that allows quota limit information to be backed up for later
325 restoration, should the need arise.
326 .IP 7.
327 Quota limits cannot be set before turning on quotas on.
328 .IP 8.
329 XFS filesystems keep quota accounting on the superuser (user ID zero),
330 and the tool will display the superuser's usage information.
331 However, limits are never enforced on the superuser (nor are they
332 enforced for group and project ID zero).
333 .IP 9.
334 XFS filesystems perform quota accounting whether the user has quota
335 limits or not.
336 .IP 10.
337 XFS supports the notion of project quota, which can be used to
338 implement a form of directory tree quota (i.e. to restrict a
339 directory tree to only being able to use up a component of the
340 filesystems available space; or simply to keep track of the
341 amount of space used, or number of inodes, within the tree).
342 .SH ADMINISTRATOR COMMANDS
343 .HP
344 .B path
345 [
346 .I N
347 ]
348 .br
349 Lists all paths with devices/project identifiers or set the current
350 path to the
351 .IR N th
352 list entry (the current path is used by many
353 of the commands described here, it identifies the filesystem toward
354 which a command is directed).
355 The path list can come from several places \- the command line,
356 the mount table, and the
357 .I /etc/projects
358 file.
359 .HP
360 .B report
361 [
362 .B \-gpu
363 ] [
364 .B \-bir
365 ] [
366 .B \-ahntlLNU
367 ] [
368 .B \-f
369 .I file
370 ]
371 .br
372 Report filesystem quota information.
373 This reports all quota usage for a filesystem, for the specified
374 quota type
375 .RB ( u / g / p
376 and/or
377 .BR b locks/ i nodes/ r ealtime).
378 It reports blocks in 1KB units by default. The
379 .B \-h
380 option reports in a "human-readable" format similar to the
381 .BR df (1)
382 command. The
383 .B \-f
384 option outputs the report to
385 .I file
386 instead of stdout. The
387 .B \-a
388 option reports on all filesystems. By default, outputs the name of
389 the user/group/project. If no name is defined for a given ID, outputs
390 the numeric ID instead. The
391 .B \-n
392 option outputs the numeric ID instead of the name. The
393 .B \-L
394 and
395 .B \-U
396 options specify lower and/or upper ID bounds to report on. If upper/lower
397 bounds are specified, then by default only the IDs will be displayed
398 in output; with the
399 .B \-l
400 option, a lookup will be performed to translate these IDs to names. The
401 .B \-N
402 option reports information without the header line. The
403 .B \-t
404 option performs a terse report.
405 .HP
406 .B state
407 [
408 .B \-gpu
409 ] [
410 .B \-av
411 ] [
412 .B \-f
413 .I file
414 ]
415 .br
416 Report overall quota state information.
417 This reports on the state of quota accounting, quota enforcement,
418 and the number of extents being used by quota metadata within the
419 filesystem. The
420 .B \-f
421 option outputs state information to
422 .I file
423 instead of stdout. The
424 .B \-a
425 option reports state on all filesystems and not just the current path.
426 .HP
427 .B limit
428 [
429 .BR \-g " | " \-p " | " \-u
430 ]
431 .BI bsoft= N
432 |
433 .BI bhard= N
434 |
435 .BI isoft= N
436 |
437 .BI ihard= N
438 |
439 .BI rtbsoft= N
440 |
441 .BI rtbhard= N
442 .B \-d
443 |
444 .I id
445 |
446 .I name
447 .br
448 Set quota block limits (bhard/bsoft), inode count limits (ihard/isoft)
449 and/or realtime block limits (rtbhard/rtbsoft) to N, where N is a
450 number representing bytes or inodes.
451 For block limits, a number with a s/b/k/m/g/t/p/e multiplication suffix
452 as described in
453 .BR mkfs.xfs (8)
454 is also accepted.
455 For inode limits, no suffixes are allowed.
456 The
457 .B \-d
458 option (defaults) can be used to set the default value
459 that will be used, otherwise a specific
460 .BR u ser/ g roup/ p roject
461 .I name
462 or numeric
463 .IR id entifier
464 must be specified.
465 .HP
466 .B timer
467 [
468 .BR \-g " | " \-p " | " \-u
469 ] [
470 .B \-bir
471 ]
472 .I value
473 [
474 .B -d
475 |
476 .I id
477 |
478 .I name
479 ]
480 .br
481 Allows the quota enforcement timeout (i.e. the amount of time allowed
482 to pass before the soft limits are enforced as the hard limits) to
483 be modified. The current timeout setting can be displayed using the
484 .B state
485 command.
486 .br
487 When setting the default timer via the
488 .B \-d
489 option, or for
490 .B id
491 0, or if no argument is given after
492 .I value
493 the
494 .I value
495 argument is a number of seconds indicating the relative amount of time after
496 soft limits are exceeded, before hard limits are enforced.
497 .br
498 When setting any other individual timer by
499 .I id
500 or
501 .I name,
502 the
503 .I value
504 is the number of seconds from now, at which time the hard limits will be enforced.
505 This allows extending the grace time of an individual user who has exceeded soft
506 limits.
507 .br
508 For
509 .I value,
510 units of \&'minutes', 'hours', 'days', and 'weeks' are also understood
511 (as are their abbreviations 'm', 'h', 'd', and 'w').
512 .br
513 .HP
514 .B warn
515 [
516 .BR \-g " | " \-p " | " \-u
517 ] [
518 .B \-bir
519 ]
520 .I value
521 .B -d
522 |
523 .I id
524 |
525 .I name
526 .br
527 Allows the quota warnings limit (i.e. the number of times a warning
528 will be send to someone over quota) to be viewed and modified. The
529 .B \-d
530 option (defaults) can be used to set the default time
531 that will be used, otherwise a specific
532 .BR u ser/ g roup/ p roject
533 .I name
534 or numeric
535 .IR id entifier
536 must be specified.
537 .B NOTE: this feature is not currently implemented.
538 .TP
539 .BR enable " [ " \-gpu " ] [ " \-v " ]"
540 Switches on quota enforcement for the filesystem identified by the
541 current path.
542 This requires the filesystem to have been mounted with quota enabled,
543 and for accounting to be currently active. The
544 .B \-v
545 option (verbose) displays the state after the operation has completed.
546 .TP
547 .BR disable " [ " \-gpu " ] [ " \-v " ]"
548 Disables quota enforcement, while leaving quota accounting active. The
549 .B \-v
550 option (verbose) displays the state after the operation has completed.
551 .TP
552 .BR off " [ " \-gpu " ] [ " \-v " ]"
553 Permanently switches quota off for the filesystem identified by the
554 current path.
555 Quota can only be switched back on subsequently by unmounting and
556 then mounting again.
557 .TP
558 .BR remove " [ " \-gpu " ] [ " \-v " ]"
559 Remove any space allocated to quota metadata from the filesystem
560 identified by the current path.
561 Quota must not be enabled on the filesystem, else this operation will
562 report an error.
563 .HP
564 .B dump
565 [
566 .BR \-g " | " \-p " | " \-u
567 ] [
568 .BR \-L " | " \-U
569 ] [
570 .B \-f
571 .I file
572 ]
573 .br
574 Dump out quota limit information for backup utilities, either to
575 standard output (default) or to a
576 .IR file .
577 The
578 .B \-L
579 and
580 .B \-U
581 options specify lower and/or upper ID bounds to dump.
582 This is only the limits, not the usage information, of course.
583 .HP
584 .B restore
585 [
586 .BR \-g " | " \-p " | " \-u
587 ] [
588 .B \-f
589 .I file
590 ]
591 .br
592 Restore quota limits from a backup
593 .IR file .
594 The file must be in the format produced by the
595 .B dump
596 command.
597 .HP
598 .B quot
599 [
600 .BR \-g " | " \-p " | " \-u
601 ] [
602 .B \-bir
603 ] [
604 .B \-acnv
605 ] [
606 .B \-f
607 .I file
608 ]
609 .br
610 Summarize filesystem ownership, by user, group or project.
611 This command uses a special XFS "bulkstat" interface to quickly scan
612 an entire filesystem and report usage information.
613 This command can be used even when filesystem quota are not enabled,
614 as it is a full-filesystem scan (it may also take a long time...). The
615 .B \-a
616 option displays information on all filesystems. The
617 .B \-c
618 option displays a histogram instead of a report. The
619 .B \-n
620 option displays numeric IDs rather than names. The
621 .B \-v
622 option displays verbose information. The
623 .B \-f
624 option send the output to
625 .I file
626 instead of stdout.
627 .HP
628 .B project
629 [
630 .B \-cCs
631 [
632 .B \-d
633 .I depth
634 ]
635 [
636 .B \-p
637 .I path
638 ]
639 .I id
640 |
641 .I name
642 ]
643 .br
644 The
645 .BR \-c ,
646 .BR \-C ,
647 and
648 .B \-s
649 options allow the directory tree quota mechanism to be maintained.
650 .BR \-d
651 allows one to limit recursion level when processing project directories
652 and
653 .BR \-p
654 allows one to specify project paths at command line ( instead of
655 .I /etc/projects
656 ). All options are discussed in detail below.
657 .SH DIRECTORY TREE QUOTA
658 The project quota mechanism in XFS can be used to implement a form of
659 directory tree quota, where a specified directory and all of the files
660 and subdirectories below it (i.e. a tree) can be restricted to using
661 a subset of the available space in the filesystem.
662 .PP
663 A managed tree must be setup initially using the
664 .B \-s
665 option to the
666 .B project
667 command. The specified project name or identifier is matched to one
668 or more trees defined in
669 .IR /etc/projects ,
670 and these trees are then recursively descended
671 to mark the affected inodes as being part of that tree.
672 This process sets an inode flag and the project identifier on every file
673 in the affected tree.
674 Once this has been done, new files created in the tree will automatically
675 be accounted to the tree based on their project identifier.
676 An attempt to create a hard link to a file in the tree will only succeed
677 if the project identifier matches the project identifier for the tree.
678 The
679 .B xfs_io
680 utility can be used to set the project ID for an arbitrary file, but this
681 can only be done by a privileged user.
682 .PP
683 A previously setup tree can be cleared from project quota control through
684 use of the
685 .B project \-C
686 option, which will recursively descend
687 the tree, clearing the affected inodes from project quota control.
688 .PP
689 Finally, the
690 .B project \-c
691 option can be used to check whether a
692 tree is setup, it reports nothing if the tree is correct, otherwise it
693 reports the paths of inodes which do not have the project ID of the rest
694 of the tree, or if the inode flag is not set.
695 .PP
696 Option
697 .B \-d
698 can be used to limit recursion level (\-1 is infinite, 0 is top level only,
699 1 is first level ... ).
700 Option
701 .B \-p
702 adds possibility to specify project paths in command line without a need
703 for
704 .I /etc/projects
705 to exist. Note that if projects file exists then it is also used.
706
707 .SH EXAMPLES
708 Enabling quota enforcement on an XFS filesystem (restrict a user
709 to a set amount of space).
710 .nf
711 .sp
712 .in +5
713 # mount \-o uquota /dev/xvm/home /home
714 # xfs_quota \-x \-c 'limit bsoft=500m bhard=550m tanya' /home
715 # xfs_quota \-x \-c report /home
716 .in -5
717 .fi
718 .PP
719 Enabling project quota on an XFS filesystem (restrict files in
720 log file directories to only using 1 gigabyte of space).
721 .nf
722 .sp
723 .in +5
724 # mount \-o prjquota /dev/xvm/var /var
725 # echo 42:/var/log >> /etc/projects
726 # echo logfiles:42 >> /etc/projid
727 # xfs_quota \-x \-c 'project \-s logfiles' /var
728 # xfs_quota \-x \-c 'limit \-p bhard=1g logfiles' /var
729 .in -5
730 .fi
731 .PP
732 Same as above without a need for configuration files.
733 .nf
734 .sp
735 .in +5
736 # rm \-f /etc/projects /etc/projid
737 # mount \-o prjquota /dev/xvm/var /var
738 # xfs_quota \-x \-c 'project \-s \-p /var/log 42' /var
739 # xfs_quota \-x \-c 'limit \-p bhard=1g 42' /var
740 .in -5
741 .fi
742 .SH CAVEATS
743 .PP
744 The XFS allocation mechanism will always reserve the
745 maximum amount of space required before proceeding with an allocation.
746 If insufficient space for this reservation is available, due to the
747 block quota limit being reached for example, this may result in the
748 allocation failing even though there is sufficient space.
749 Quota enforcement can thus sometimes happen in situations where the
750 user is under quota and the end result of some operation would still
751 have left the user under quota had the operation been allowed to run
752 its course.
753 This additional overhead is typically in the range of tens of blocks.
754 .PP
755 Both of these properties are unavoidable side effects of the way XFS
756 operates, so should be kept in mind when assigning block limits.
757 .SH BUGS
758 Quota support for filesystems with realtime subvolumes is not yet
759 implemented, nor is the quota warning mechanism (the Linux
760 .BR warnquota (8)
761 tool can be used to provide similar functionality on that platform).
762 .SH FILES
763 .PD 0
764 .TP 20
765 .I /etc/projects
766 Mapping of numeric project identifiers to directories trees.
767 .TP
768 .I /etc/projid
769 Mapping of numeric project identifiers to project names.
770 .PD
771
772 .SH SEE ALSO
773 .BR df (1),
774 .BR mount (1),
775 .BR sync (2),
776 .BR projid (5),
777 .BR projects (5).
778 .BR xfs (5).
779 .BR warnquota (8),