1xfs_quota(8) System Manager's Manual xfs_quota(8)
2
6 xfs_quota - manage use of quota on XFS filesystems
7
9 xfs_quota [ -x ] [ -p prog ] [ -c cmd ] ... [ -d project ] ... [ path
10 ... ]
11
13 xfs_quota is a utility for reporting and editing various aspects of
14 filesystem quota.
15 The options to xfs_quota are:
17 -c cmd xfs_quota commands may be run interactively (the default) or
19 as arguments on the command line. Multiple -c arguments may
20 be given. The commands are run in the sequence given, then
21 the program exits.
22 -p prog Set the program name for prompts and some error messages, the
24 default value is xfs_quota.
25 -x Enable expert mode. All of the administrative commands (see
27 the ADMINISTRATOR COMMANDS section below) which allow modifi‐
28 cations to the quota system are available only in expert
29 mode.
30 -d project
32 Project names or numeric identifiers may be specified with
33 this option, which restricts the output of the individual
34 xfs_quota commands to the set of projects specified. Multiple
35 -d arguments may be given.
36 The optional path argument(s) can be used to specify mount points or
38 device files which identify XFS filesystems. The output of the individ‐
39 ual xfs_quota commands will then be restricted to the set of filesys‐
40 tems specified.
41 This manual page is divided into two sections - firstly, information
43 for users of filesystems with quota enabled, and the xfs_quota commands
44 of interest to such users; and then information which is useful only to
45 administrators of XFS filesystems using quota and the quota commands
46 which allow modifications to the quota system.
47 Note that common to almost all of the individual commands described
49 below are the options for specifying which quota types are of interest
50 - user quota (-u), group quota (-g), and/or project quota (-p). Also,
51 several commands provide options to operate on "blocks used" (-b),
52 "inodes used" (-i), and/or "realtime blocks used" (-r).
53 Many commands also have extensive online help. Use the help command for
55 more details on any command.
56
58 In most computing environments, disk space is not infinite. The quota
59 subsystem provides a mechanism to control usage of disk space. Quotas
60 can be set for each individual user on any/all of the local filesys‐
61 tems. The quota subsystem warns users when they exceed their allotted
62 limit, but allows some extra space for current work (hard limit/soft
63 limit). In addition, XFS filesystems with limit enforcement turned off
64 can be used as an effective disk usage accounting system.
65 Users' View of Disk Quotas
67 To most users, disk quotas are either of no concern or a fact of life
68 that cannot be avoided. There are two possible quotas that can be
69 imposed - a limit can be set on the amount of space a user can occupy,
70 and there may be a limit on the number of files (inodes) he can own.
71 The quota command provides information on the quotas that have been set
73 by the system administrators and current usage.
74 There are four numbers for each limit: current usage, soft limit
76 (quota), hard limit, and time limit. The soft limit is the number of
77 1K-blocks (or files) that the user is expected to remain below. The
78 hard limit cannot be exceeded. If a user's usage reaches the hard
79 limit, further requests for space (or attempts to create a file) fail
80 with the "Quota exceeded" (EDQUOT) error.
81 When a user exceeds the soft limit, the timer is enabled. Any time the
83 quota drops below the soft limits, the timer is disabled. If the timer
84 pops, the particular limit that has been exceeded is treated as if the
85 hard limit has been reached, and no more resources are allocated to the
86 user. The only way to reset this condition, short of turning off limit
87 enforcement or increasing the limit, is to reduce usage below quota.
88 Only the superuser (i.e. a sufficiently capable process) can set the
89 time limits and this is done on a per filesystem basis.
90 Surviving When the Quota Limit Is Reached
92 In most cases, the only way for a user to recover from over-quota con‐
93 ditions is to abort whatever activity is in progress on the filesystem
94 that has reached its limit, remove sufficient files to bring the limit
95 back below quota, and retry the failed program.
96 However, if a user is in the editor and a write fails because of an
97 over quota situation, that is not a suitable course of action. It is
98 most likely that initially attempting to write the file has truncated
99 its previous contents, so if the editor is aborted without correctly
100 writing the file, not only are the recent changes lost, but possibly
101 much, or even all, of the contents that previously existed.
102 There are several possible safe exits for a user caught in this situa‐
103 tion. He can use the editor shell escape command to examine his file
104 space and remove surplus files. Alternatively, using sh(1), he can
105 suspend the editor, remove some files, then resume it. A third possi‐
106 bility is to write the file to some other filesystem (perhaps to a file
107 on /tmp) where the user's quota has not been exceeded. Then after rec‐
108 tifying the quota situation, the file can be moved back to the filesys‐
109 tem it belongs on.
110
112 print Lists all paths with devices/project identifiers. The path list
113 can come from several places - the command line, the mount ta‐
114 ble, and the /etc/projects file.
115 df See the free command.
117 quota [ -gpu ] [ -bir ] [ -hnNv ] [ -f file ] [ ID | name ] ...
119 Show individual usage and limits, for a single user name or
120 numeric user ID. The -h option reports in a "human-readable"
121 format similar to the df(1) command. The -n option reports the
122 numeric IDs rather than the name. The -N option omits the
123 header. The -v option outputs verbose information. The -f option
124 sends the output to file instead of stdout.
125 free [ -bir ] [ -hN ] [ -f file ]
127 Reports filesystem usage, much like the df(1) utility. It can
128 show usage for blocks, inode, and/or realtime block space, and
129 shows used, free, and total available. If project quota are in
130 use (see the DIRECTORY TREE QUOTA section below), it will also
131 report utilisation for those projects (directory trees). The -h
132 option reports in a "human-readable" format. The -N option omits
133 the header. The -f option outputs the report to file instead of
134 stdout.
135 help [ command ]
137 Online help for all commands, or one specific command.
138 quit Exit xfs_quota.
140 q See the quit command.
142
144 The XFS quota system differs to that of other filesystems in a number
145 of ways. Most importantly, XFS considers quota information as filesys‐
146 tem metadata and uses journaling to provide a higher level guarantee of
147 consistency. As such, it is administered differently, in particular:
148 1. The quotacheck command has no effect on XFS filesystems. The
150 first time quota accounting is turned on (at mount time), XFS
151 does an automatic quotacheck internally; afterwards, the quota
152 system will always be completely consistent until quotas are
153 manually turned off.
154 2. There is no need for quota file(s) in the root of the XFS
156 filesystem.
157 3. XFS distinguishes between quota accounting and limit enforce‐
159 ment. Quota accounting must be turned on at the time of mount‐
160 ing the XFS filesystem. However, it is possible to turn on/off
161 limit enforcement any time quota accounting is turned on. The
162 "quota" option to the mount command turns on both (user) quota
163 accounting and enforcement. The "uqnoenforce" option must be
164 used to turn on user accounting with limit enforcement disabled.
165 4. Turning on quotas on the root filesystem is slightly different
167 from the above. For IRIX XFS, refer to quotaon(1M). For Linux
168 XFS, the quota mount flags must be passed in with the "root‐
169 flags=" boot parameter.
170 5. It is useful to use the state to monitor the XFS quota subsystem
172 at various stages - it can be used to see if quotas are turned
173 on, and also to monitor the space occupied by the quota system
174 itself..
175 6. There is a mechanism built into xfsdump that allows quota limit
177 information to be backed up for later restoration, should the
178 need arise.
179 7. Quota limits cannot be set before turning on quotas on.
181 8. XFS filesystems keep quota accounting on the superuser (user ID
183 zero), and the tool will display the superuser's usage informa‐
184 tion. However, limits are never enforced on the superuser (nor
185 are they enforced for group and project ID zero).
186 9. XFS filesystems perform quota accounting whether the user has
188 quota limits or not.
189 10. XFS supports the notion of project quota, which can be used to
191 implement a form of directory tree quota (i.e. to restrict a
192 directory tree to only being able to use up a component of the
193 filesystems available space; or simply to keep track of the
194 amount of space used, or number of inodes, within the tree).
195
197 path [ N ]
198 Lists all paths with devices/project identifiers or set the cur‐
199 rent path to the Nth list entry (the current path is used by
200 many of the commands described here, it identifies the filesys‐
201 tem toward which a command is directed). The patch list can
202 come from several places - the command line, the mount table,
203 and the /etc/projects file.
204 report [ -gpu ] [ -bir ] [ -ahntLNU ] [ -f file ]
206 Report filesystem quota information. This reports all quota
207 usage for a filesystem, for the specified quota type (u/g/p
208 and/or blocks/inodes/realtime). It reports blocks in 1KB units
209 by default. The -h option reports in a "human-readable" format
210 similar to the df(1) command. The -f option outputs the report
211 to file instead of stdout. The -a option reports on all filesys‐
212 tems. The -n option outputs the numeric ID instead of the name.
213 The -L and -U options specify lower and upper ID bounds to
214 report on. The -N option reports information without the header
215 line. The -t option performs a terse report.
216 state [ -gpu ] [ -av ] [ -f file ]
218 Report overall quota state information. This reports on the
219 state of quota accounting, quota enforcement, and the number of
220 extents being used by quota metadata within the filesystem. The
221 -f option outputs state information to file instead of stdout.
222 The -a option reports state on all filesystems and not just the
223 current path.
224 limit [ -gpu ] bsoft=N | bhard=N | isoft=N | ihard=N | rtbsoft=N | rtb‐
226 hard=N -d | id | name
227 Set quota block limits (bhard/bsoft), inode count limits
228 (ihard/isoft) and/or realtime block limits (rtbhard/rtbsoft).
229 The -d option (defaults) can be used to set the default value
230 that will be used, otherwise a specific user/group/project name
231 or numeric identifier must be specified.
232 timer [ -gpu ] [ -bir ] value
234 Allows the quota enforcement timeout (i.e. the amount of time
235 allowed to pass before the soft limits are enforced as the hard
236 limits) to be modified. The current timeout setting can be dis‐
237 played using the state command. The value argument is a number
238 of seconds, but units of 'minutes', 'hours', 'days', and 'weeks'
239 are also understood (as are their abbreviations 'm', 'h', 'd',
240 and 'w').
241 warn [ -gpu ] [ -bir ] value -d | id | name
243 Allows the quota warnings limit (i.e. the number of times a
244 warning will be send to someone over quota) to be viewed and
245 modified. The -d option (defaults) can be used to set the
246 default time that will be used, otherwise a specific
247 user/group/project name or numeric identifier must be specified.
248 NOTE: this feature is not currently implemented.
249 enable [ -gpu ] [ -v ]
251 Switches on quota enforcement for the filesystem identified by
252 the current path. This requires the filesystem to have been
253 mounted with quota enabled, and for accounting to be currently
254 active. The -v option (verbose) displays the state after the
255 operation has completed.
256 disable [ -gpu ] [ -v ]
258 Disables quota enforcement, while leaving quota accounting
259 active. The -v option (verbose) displays the state after the
260 operation has completed.
261 off [ -gpu ] [ -v ]
263 Permanently switches quota off for the filesystem identified by
264 the current path. Quota can only be switched back on subse‐
265 quently by unmounting and then mounting again.
266 remove [ -gpu ] [ -v ]
268 Remove any space allocated to quota metadata from the filesystem
269 identified by the current path. Quota must not be enabled on
270 the filesystem, else this operation will report an error.
271 dump [ -gpu ] [ -f file ]
273 Dump out quota limit information for backup utilities, either to
274 standard output (default) or to a file. This is only the lim‐
275 its, not the usage information, of course.
276 restore [ -gpu ] [ -f file ]
278 Restore quota limits from a backup file. The file must be in
279 the format produced by the dump command.
280 quot [ -gpu ] [ -bir ] [ -acnv ] [ -f file ]
282 Summarize filesystem ownership, by user, group or project. This
283 command uses a special XFS "bulkstat" interface to quickly scan
284 an entire filesystem and report usage information. This command
285 can be used even when filesystem quota are not enabled, as it is
286 a full-filesystem scan (it may also take a long time...). The -a
287 option displays information on all filesystems. The -c option
288 displays a histogram instead of a report. The -n option displays
289 numeric IDs rather than names. The -v option displays verbose
290 information. The -f option send the output to file instead of
291 stdout.
292 project [ -cCs id | name ]
294 Without arguments, this command lists known project names and
295 identifiers (based on entries in the /etc/projects and /etc/pro‐
296 jid files). The -c, -C, and -s options allow the directory tree
297 quota mechanism, discussed in detail below, to be maintained.
298
300 The project quota mechanism in XFS can be used to implement a form of
301 directory tree quota, where a specified directory and all of the files
302 and subdirectories below it (i.e. a tree) can be restricted to using a
303 subset of the available space in the filesystem.
304 A managed tree must be setup initially using the -s option to the
306 project command. The specified project name or identifier is matched to
307 one or more trees defined in /etc/projects, and these trees are then
308 recursively descended to mark the affected inodes as being part of that
309 tree. This process sets an inode flag and the project identifier on
310 every file in the affected tree. Once this has been done, new files
311 created in the tree will automatically be accounted to the tree based
312 on their project identifier. An attempt to create a hard link to a
313 file in the tree will only succeed if the project identifier matches
314 the project identifier for the tree. The xfs_io utility can be used to
315 set the project ID for an arbitrary file, but this can only be done by
316 a privileged user.
317 A previously setup tree can be cleared from project quota control
319 through use of the project -C option, which will recursively descend
320 the tree, clearing the affected inodes from project quota control.
321 Finally, the project -c option can be used to check whether a tree is
323 setup, it reports nothing if the tree is correct, otherwise it reports
324 the paths of inodes which do not have the project ID of the rest of the
325 tree, or if the inode flag is not set.
326
328 There are two files involved with the tree quota mechanism, namely
329 /etc/projects and /etc/projid. The latter is optional. The
330 /etc/projects file provides a mapping between numeric project identi‐
331 fiers and those directories which are the roots of the quota tree. Its
332 format is simply:
333 # comments are hash-prefixed
335 # ...
336 10:/export/cage
337 42:/var/log
338 The /etc/projid file provides a mapping between numeric project identi‐
340 fiers and a simple human readable name (similar relationship to the one
341 that exists between usernames and uids). Its format is simply:
342 # comments are hash-prefixed
344 # ...
345 cage:10
346 logfiles:42
347 This file is optional, if a project identifier cannot be mapped to a
349 name, it will be displayed as a number only.
350
352 Enabling quota enforcement on an XFS filesystem (restrict a user to a
353 set amount of space).
354 # mount -o uquota /dev/xvm/home /home
356 # xfs_quota -x -c 'limit bsoft=500m bhard=550m tanya' /home
357 # xfs_quota -x -c report /home
358 Enabling project quota on an XFS filesystem (restrict files in log file
360 directories to only using 1 gigabyte of space).
361 # mount -o prjquota /dev/xvm/var /var
363 # echo 42:/var/log >> /etc/projects
364 # echo logfiles:42 >> /etc/projid
365 # xfs_quota -x -c 'project -s logfiles' /var
366 # xfs_quota -x -c 'limit -p bhard=1g logfiles' /var
367
369 XFS implements delayed allocation (aka. allocate-on-flush) and this has
370 implications for the quota subsystem. Since quota accounting can only
371 be done when blocks are actually allocated, it is possible to issue
372 (buffered) writes into a file and not see the usage immediately
373 updated. Only when the data is actually written out, either via one of
374 the kernels flushing mechanisms, or via a manual sync(2), will the
375 usage reported reflect what has actually been written.
376 In addition, the XFS allocation mechanism will always reserve the maxi‐
378 mum amount of space required before proceeding with an allocation. If
379 insufficient space for this reservation is available, due to the block
380 quota limit being reached for example, this may result in the alloca‐
381 tion failing even though there is sufficient space. Quota enforcement
382 can thus sometimes happen in situations where the user is under quota
383 and the end result of some operation would still have left the user
384 under quota had the operation been allowed to run its course. This
385 additional overhead is typically in the range of tens of blocks.
386 Both of these properties are unavoidable side effects of the way XFS
388 operates, so should be kept in mind when assigning block limits.
389
391 Quota support for filesystems with realtime subvolumes is not yet
392 implemented, nor is the quota warning mechanism (the Linux warnquota(8)
393 tool can be used to provide similar functionality on that platform).
394
396 /etc/projects Mapping of numeric project identifiers to directo‐
397 ries trees.
398 /etc/projid Mapping of numeric project identifiers to project
399 names.
400
402 quotaon(1M), xfs(4).
403
406 warnquota(8), xfs(5).
407
410 df(1), mount(1), sync(2).
411 xfs_quota(8)