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