File: xfs_quota.8

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

.SH LINUX SEE ALSO
.BR warnquota (8),
.BR xfs (5).

.SH SEE ALSO
.BR df (1),
.BR mount (1),
.BR sync (2).