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 ] [ -f ] [ -p prog ] [ -c cmd ] ... [ -d project ] ... [
10 -D projects_file ] [ -P projid_file ] [ path ... ]
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 -f Enable foreign filesystem mode. A limited number of user and
33 administrative commands are available for use on some foreign
34 (non-XFS) filesystems.
35 -d project
37 Project names or numeric identifiers may be specified with
38 this option, which restricts the output of the individual
39 xfs_quota commands to the set of projects specified. Multiple
40 -d arguments may be given.
41 -D projects_file
43 Specify a file containing the mapping of numeric project
44 identifiers to directory trees. /etc/projects as default, if
45 this option is none.
46 -P projid_file
48 Specify a file containing the mapping of numeric project
49 identifiers to project names. /etc/projid as default, if
50 this option is none.
51 -V Prints the version number and exits.
53 The optional path argument(s) can be used to specify mount points or
55 device files which identify XFS filesystems. The output of the individ‐
56 ual xfs_quota commands will then be restricted to the set of filesys‐
57 tems specified.
58 This manual page is divided into two sections - firstly, information
60 for users of filesystems with quota enabled, and the xfs_quota commands
61 of interest to such users; and then information which is useful only to
62 administrators of XFS filesystems using quota and the quota commands
63 which allow modifications to the quota system.
64 Note that common to almost all of the individual commands described be‐
66 low are the options for specifying which quota types are of interest -
67 user quota (-u), group quota (-g), and/or project quota (-p). Also,
68 several commands provide options to operate on "blocks used" (-b), "in‐
69 odes used" (-i), and/or "realtime blocks used" (-r).
70 Many commands also have extensive online help. Use the help command for
72 more details on any command.
73
75 In most computing environments, disk space is not infinite. The quota
76 subsystem provides a mechanism to control usage of disk space. Quotas
77 can be set for each individual user on any/all of the local filesys‐
78 tems. The quota subsystem warns users when they exceed their allotted
79 limit, but allows some extra space for current work (hard limit/soft
80 limit). In addition, XFS filesystems with limit enforcement turned off
81 can be used as an effective disk usage accounting system.
82 Users' View of Disk Quotas
84 To most users, disk quotas are either of no concern or a fact of life
85 that cannot be avoided. There are two possible quotas that can be im‐
86 posed - a limit can be set on the amount of space a user can occupy,
87 and there may be a limit on the number of files (inodes) they can own.
88 The quota command provides information on the quotas that have been set
90 by the system administrators and current usage.
91 There are four numbers for each limit: current usage, soft limit
93 (quota), hard limit, and time limit. The soft limit is the number of
94 1K-blocks (or files) that the user is expected to remain below. The
95 hard limit cannot be exceeded. If a user's usage reaches the hard
96 limit, further requests for space (or attempts to create a file) fail
97 with the "Quota exceeded" (EDQUOT) error.
98 When a user exceeds the soft limit, the timer is enabled. Any time the
100 quota drops below the soft limits, the timer is disabled. If the timer
101 pops, the particular limit that has been exceeded is treated as if the
102 hard limit has been reached, and no more resources are allocated to the
103 user. The only way to reset this condition, short of turning off limit
104 enforcement or increasing the limit, is to reduce usage below quota.
105 Only the superuser (i.e. a sufficiently capable process) can set the
106 time limits and this is done on a per filesystem basis.
107 Surviving When the Quota Limit Is Reached
109 In most cases, the only way for a user to recover from over-quota con‐
110 ditions is to abort whatever activity is in progress on the filesystem
111 that has reached its limit, remove sufficient files to bring the limit
112 back below quota, and retry the failed program.
113 However, if a user is in the editor and a write fails because of an
114 over quota situation, that is not a suitable course of action. It is
115 most likely that initially attempting to write the file has truncated
116 its previous contents, so if the editor is aborted without correctly
117 writing the file, not only are the recent changes lost, but possibly
118 much, or even all, of the contents that previously existed.
119 There are several possible safe exits for a user caught in this situa‐
120 tion. They can use the editor shell escape command to examine their
121 file space and remove surplus files. Alternatively, using sh(1), they
122 can suspend the editor, remove some files, then resume it. A third
123 possibility is to write the file to some other filesystem (perhaps to a
124 file on /tmp) where the user's quota has not been exceeded. Then after
125 rectifying the quota situation, the file can be moved back to the
126 filesystem it belongs on.
127 Default Quotas
129 The XFS quota subsystem allows a default quota to be enforced for any
130 user, group or project which does not have a quota limit explicitly
131 set. These limits are stored in and displayed as ID 0's limits, al‐
132 though they do not actually limit ID 0.
133
135 print Lists all paths with devices/project identifiers. The path list
136 can come from several places - the command line, the mount ta‐
137 ble, and the /etc/projects file.
138 df See the free command.
140 quota [ -g | -p | -u ] [ -bir ] [ -hnNv ] [ -f file ] [ ID | name ] ...
142 Show individual usage and limits, for a single user name or nu‐
143 meric user ID. The -h option reports in a "human-readable" for‐
144 mat similar to the df(1) command. The -n option reports the nu‐
145 meric IDs rather than the name. The -N option omits the header.
146 The -v option outputs verbose information. The -f option sends
147 the output to file instead of stdout.
148 free [ -bir ] [ -hN ] [ -f file ]
150 Reports filesystem usage, much like the df(1) utility. It can
151 show usage for blocks, inode, and/or realtime block space, and
152 shows used, free, and total available. If project quota are in
153 use (see the DIRECTORY TREE QUOTA section below), it will also
154 report utilisation for those projects (directory trees). The -h
155 option reports in a "human-readable" format. The -N option omits
156 the header. The -f option outputs the report to file instead of
157 stdout.
158 help [ command ]
160 Online help for all commands, or one specific command.
161 quit Exit xfs_quota.
163 q See the quit command.
165
167 The XFS quota system differs to that of other filesystems in a number
168 of ways. Most importantly, XFS considers quota information as filesys‐
169 tem metadata and uses journaling to provide a higher level guarantee of
170 consistency. As such, it is administered differently, in particular:
171 1. The quotacheck command has no effect on XFS filesystems. The
173 first time quota accounting is turned on (at mount time), XFS
174 does an automatic quotacheck internally; afterwards, the quota
175 system will always be completely consistent until quotas are
176 manually turned off.
177 2. There is no need for quota file(s) in the root of the XFS
179 filesystem.
180 3. XFS distinguishes between quota accounting and limit enforce‐
182 ment. Quota accounting must be turned on at the time of mount‐
183 ing the XFS filesystem. However, it is possible to turn on/off
184 limit enforcement any time quota accounting is turned on. The
185 "quota" option to the mount command turns on both (user) quota
186 accounting and enforcement. The "uqnoenforce" option must be
187 used to turn on user accounting with limit enforcement disabled.
188 4. Turning on quotas on the root filesystem is slightly different
190 from the above. For Linux XFS, the quota mount flags must be
191 passed in with the "rootflags=" boot parameter.
192 5. It is useful to use the state to monitor the XFS quota subsystem
194 at various stages - it can be used to see if quotas are turned
195 on, and also to monitor the space occupied by the quota system
196 itself..
197 6. There is a mechanism built into xfsdump that allows quota limit
199 information to be backed up for later restoration, should the
200 need arise.
201 7. Quota limits cannot be set before turning on quotas on.
203 8. XFS filesystems keep quota accounting on the superuser (user ID
205 zero), and the tool will display the superuser's usage informa‐
206 tion. However, limits are never enforced on the superuser (nor
207 are they enforced for group and project ID zero).
208 9. XFS filesystems perform quota accounting whether the user has
210 quota limits or not.
211 10. XFS supports the notion of project quota, which can be used to
213 implement a form of directory tree quota (i.e. to restrict a di‐
214 rectory tree to only being able to use up a component of the
215 filesystems available space; or simply to keep track of the
216 amount of space used, or number of inodes, within the tree).
217
219 path [ N ]
220 Lists all paths with devices/project identifiers or set the cur‐
221 rent path to the Nth list entry (the current path is used by
222 many of the commands described here, it identifies the filesys‐
223 tem toward which a command is directed). The path list can come
224 from several places - the command line, the mount table, and the
225 /etc/projects file.
226 report [ -gpu ] [ -bir ] [ -ahntlLNU ] [ -f file ]
228 Report filesystem quota information. This reports all quota us‐
229 age for a filesystem, for the specified quota type (u/g/p and/or
230 blocks/inodes/realtime). It reports blocks in 1KB units by de‐
231 fault. The -h option reports in a "human-readable" format simi‐
232 lar to the df(1) command. The -f option outputs the report to
233 file instead of stdout. The -a option reports on all filesys‐
234 tems. By default, outputs the name of the user/group/project. If
235 no name is defined for a given ID, outputs the numeric ID in‐
236 stead. The -n option outputs the numeric ID instead of the name.
237 The -L and -U options specify lower and/or upper ID bounds to
238 report on. If upper/lower bounds are specified, then by default
239 only the IDs will be displayed in output; with the -l option, a
240 lookup will be performed to translate these IDs to names. The -N
241 option reports information without the header line. The -t op‐
242 tion performs a terse report.
243 state [ -gpu ] [ -av ] [ -f file ]
245 Report overall quota state information. This reports on the
246 state of quota accounting, quota enforcement, and the number of
247 extents being used by quota metadata within the filesystem. The
248 -f option outputs state information to file instead of stdout.
249 The -a option reports state on all filesystems and not just the
250 current path.
251 limit [ -g | -p | -u ] bsoft=N | bhard=N | isoft=N | ihard=N | rtb‐
253 soft=N | rtbhard=N -d | id | name
254 Set quota block limits (bhard/bsoft), inode count limits
255 (ihard/isoft) and/or realtime block limits (rtbhard/rtbsoft) to
256 N, where N is a number representing bytes or inodes. For block
257 limits, a number with a s/b/k/m/g/t/p/e multiplication suffix as
258 described in mkfs.xfs(8) is also accepted. For inode limits, no
259 suffixes are allowed. The -d option (defaults) can be used to
260 set the default value that will be used, otherwise a specific
261 user/group/project name or numeric identifier must be specified.
262 timer [ -g | -p | -u ] [ -bir ] value [ -d | id | name ]
264 Allows the quota enforcement timeout (i.e. the amount of time
265 allowed to pass before the soft limits are enforced as the hard
266 limits) to be modified. The current timeout setting can be dis‐
267 played using the state command.
268 When setting the default timer via the -d option, or for id 0,
269 or if no argument is given after value the value argument is a
270 number of seconds indicating the relative amount of time after
271 soft limits are exceeded, before hard limits are enforced.
272 When setting any other individual timer by id or name, the value
273 is the number of seconds from now, at which time the hard limits
274 will be enforced. This allows extending the grace time of an
275 individual user who has exceeded soft limits.
276 For value, units of 'minutes', 'hours', 'days', and 'weeks' are
277 also understood (as are their abbreviations 'm', 'h', 'd', and
278 'w').
279 warn [ -g | -p | -u ] [ -bir ] value -d | id | name
281 Allows the quota warnings limit (i.e. the number of times a
282 warning will be send to someone over quota) to be viewed and
283 modified. The -d option (defaults) can be used to set the de‐
284 fault time that will be used, otherwise a specific
285 user/group/project name or numeric identifier must be specified.
286 NOTE: this feature is not currently implemented.
287 enable [ -gpu ] [ -v ]
289 Switches on quota enforcement for the filesystem identified by
290 the current path. This requires the filesystem to have been
291 mounted with quota enabled, and for accounting to be currently
292 active. The -v option (verbose) displays the state after the op‐
293 eration has completed.
294 disable [ -gpu ] [ -v ]
296 Disables quota enforcement, while leaving quota accounting ac‐
297 tive. The -v option (verbose) displays the state after the oper‐
298 ation has completed.
299 off [ -gpu ] [ -v ]
301 Permanently switches quota off for the filesystem identified by
302 the current path. Quota can only be switched back on subse‐
303 quently by unmounting and then mounting again.
304 remove [ -gpu ] [ -v ]
306 Remove any space allocated to quota metadata from the filesystem
307 identified by the current path. Quota must not be enabled on
308 the filesystem, else this operation will report an error.
309 dump [ -g | -p | -u ] [ -L | -U ] [ -f file ]
311 Dump out quota limit information for backup utilities, either to
312 standard output (default) or to a file. The -L and -U options
313 specify lower and/or upper ID bounds to dump. This is only the
314 limits, not the usage information, of course.
315 restore [ -g | -p | -u ] [ -f file ]
317 Restore quota limits from a backup file. The file must be in
318 the format produced by the dump command.
319 quot [ -g | -p | -u ] [ -bir ] [ -acnv ] [ -f file ]
321 Summarize filesystem ownership, by user, group or project. This
322 command uses a special XFS "bulkstat" interface to quickly scan
323 an entire filesystem and report usage information. This command
324 can be used even when filesystem quota are not enabled, as it is
325 a full-filesystem scan (it may also take a long time...). The -a
326 option displays information on all filesystems. The -c option
327 displays a histogram instead of a report. The -n option displays
328 numeric IDs rather than names. The -v option displays verbose
329 information. The -f option send the output to file instead of
330 stdout.
331 project [ -cCs [ -d depth ] [ -p path ] id | name ]
333 The -c, -C, and -s options allow the directory tree quota mecha‐
334 nism to be maintained. -d allows one to limit recursion level
335 when processing project directories and -p allows one to specify
336 project paths at command line ( instead of /etc/projects ). All
337 options are discussed in detail below.
338
340 The project quota mechanism in XFS can be used to implement a form of
341 directory tree quota, where a specified directory and all of the files
342 and subdirectories below it (i.e. a tree) can be restricted to using a
343 subset of the available space in the filesystem.
344 A managed tree must be setup initially using the -s option to the
346 project command. The specified project name or identifier is matched to
347 one or more trees defined in /etc/projects, and these trees are then
348 recursively descended to mark the affected inodes as being part of that
349 tree. This process sets an inode flag and the project identifier on
350 every file in the affected tree. Once this has been done, new files
351 created in the tree will automatically be accounted to the tree based
352 on their project identifier. An attempt to create a hard link to a
353 file in the tree will only succeed if the project identifier matches
354 the project identifier for the tree. The xfs_io utility can be used to
355 set the project ID for an arbitrary file, but this can only be done by
356 a privileged user.
357 A previously setup tree can be cleared from project quota control
359 through use of the project -C option, which will recursively descend
360 the tree, clearing the affected inodes from project quota control.
361 Finally, the project -c option can be used to check whether a tree is
363 setup, it reports nothing if the tree is correct, otherwise it reports
364 the paths of inodes which do not have the project ID of the rest of the
365 tree, or if the inode flag is not set.
366 Option -d can be used to limit recursion level (-1 is infinite, 0 is
368 top level only, 1 is first level ... ). Option -p adds possibility to
369 specify project paths in command line without a need for /etc/projects
370 to exist. Note that if projects file exists then it is also used.
371
374 Enabling quota enforcement on an XFS filesystem (restrict a user to a
375 set amount of space).
376 # mount -o uquota /dev/xvm/home /home
378 # xfs_quota -x -c 'limit bsoft=500m bhard=550m tanya' /home
379 # xfs_quota -x -c report /home
380 Enabling project quota on an XFS filesystem (restrict files in log file
382 directories to only using 1 gigabyte of space).
383 # mount -o prjquota /dev/xvm/var /var
385 # echo 42:/var/log >> /etc/projects
386 # echo logfiles:42 >> /etc/projid
387 # xfs_quota -x -c 'project -s logfiles' /var
388 # xfs_quota -x -c 'limit -p bhard=1g logfiles' /var
389 Same as above without a need for configuration files.
391 # rm -f /etc/projects /etc/projid
393 # mount -o prjquota /dev/xvm/var /var
394 # xfs_quota -x -c 'project -s -p /var/log 42' /var
395 # xfs_quota -x -c 'limit -p bhard=1g 42' /var
396
398 The XFS allocation mechanism will always reserve the maximum amount of
399 space required before proceeding with an allocation. If insufficient
400 space for this reservation is available, due to the block quota limit
401 being reached for example, this may result in the allocation failing
402 even though there is sufficient space. Quota enforcement can thus
403 sometimes happen in situations where the user is under quota and the
404 end result of some operation would still have left the user under quota
405 had the operation been allowed to run its course. This additional
406 overhead is typically in the range of tens of blocks.
407 Both of these properties are unavoidable side effects of the way XFS
409 operates, so should be kept in mind when assigning block limits.
410
412 Quota support for filesystems with realtime subvolumes is not yet im‐
413 plemented, nor is the quota warning mechanism (the Linux warnquota(8)
414 tool can be used to provide similar functionality on that platform).
415
417 /etc/projects Mapping of numeric project identifiers to directo‐
418 ries trees.
419 /etc/projid Mapping of numeric project identifiers to project
420 names.
421
424 df(1), mount(1), sync(2), projid(5), projects(5). xfs(5). warn‐
425 quota(8),
426 xfs_quota(8)