1xfs_quota(8)                System Manager's Manual               xfs_quota(8)
2
3
4

NAME

6       xfs_quota - manage use of quota on XFS filesystems
7

SYNOPSIS

9       xfs_quota [ -x ] [ -f ] [ -p prog ] [ -c cmd ] ... [ -d project ] ... [
10       -D projects_file ] [ -P projid_file ] [ path ... ]
11       xfs_quota -V
12

DESCRIPTION

14       xfs_quota is a utility for reporting and  editing  various  aspects  of
15       filesystem quota.
16
17       The options to xfs_quota are:
18
19       -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
24       -p prog   Set the program name for prompts and some error messages, the
25                 default value is xfs_quota.
26
27       -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
32       -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
36       -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
42       -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
47       -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
52       -V        Prints the version number and exits.
53
54       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
59       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
65       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
71       Many commands also have extensive online help. Use the help command for
72       more details on any command.
73

QUOTA OVERVIEW

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
83   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
89       The quota command provides information on the quotas that have been set
90       by the system administrators and current usage.
91
92       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
99       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
108   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
128   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

USER COMMANDS

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
139       df     See the free command.
140
141       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
149       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
159       help [ command ]
160              Online help for all commands, or one specific command.
161
162       quit   Exit xfs_quota.
163
164       q      See the quit command.
165

QUOTA ADMINISTRATION

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
172       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
178       2.     There is no need for quota  file(s)  in  the  root  of  the  XFS
179              filesystem.
180
181       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
189       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
193       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
198       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
202       7.     Quota limits cannot be set before turning on quotas on.
203
204       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
209       9.     XFS  filesystems  perform  quota accounting whether the user has
210              quota limits or not.
211
212       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

ADMINISTRATOR COMMANDS

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
227       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 upper ID bounds  to  re‐
238              port  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
244       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
252       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).
256              The  -d  option  (defaults) can be used to set the default value
257              that will be used, otherwise a specific user/group/project  name
258              or numeric identifier must be specified.
259
260       timer [ -g | -p | -u ] [ -bir ] value [ -d | id | name ]
261              Allows  the  quota  enforcement timeout (i.e. the amount of time
262              allowed to pass before the soft limits are enforced as the  hard
263              limits)  to be modified. The current timeout setting can be dis‐
264              played using the state command.
265              When setting the default timer via the -d option, or for  id  0,
266              or  if  no argument is given after value the value argument is a
267              number of seconds indicating the relative amount of  time  after
268              soft limits are exceeded, before hard limits are enforced.
269              When setting any other individual timer by id or name, the value
270              is the number of seconds from now, at which time the hard limits
271              will  be  enforced.   This allows extending the grace time of an
272              individual user who has exceeded soft limits.
273              For value, units of 'minutes', 'hours', 'days', and 'weeks'  are
274              also  understood  (as are their abbreviations 'm', 'h', 'd', and
275              'w').
276
277       warn [ -g | -p | -u ] [ -bir ] value -d | id | name
278              Allows the quota warnings limit (i.e.  the  number  of  times  a
279              warning  will  be  send  to someone over quota) to be viewed and
280              modified. The -d option (defaults) can be used to  set  the  de‐
281              fault   time   that   will   be   used,   otherwise  a  specific
282              user/group/project name or numeric identifier must be specified.
283              NOTE: this feature is not currently implemented.
284
285       enable [ -gpu ] [ -v ]
286              Switches  on  quota enforcement for the filesystem identified by
287              the current path.  This requires the  filesystem  to  have  been
288              mounted  with  quota enabled, and for accounting to be currently
289              active. The -v option (verbose) displays the state after the op‐
290              eration has completed.
291
292       disable [ -gpu ] [ -v ]
293              Disables  quota  enforcement, while leaving quota accounting ac‐
294              tive. The -v option (verbose) displays the state after the oper‐
295              ation has completed.
296
297       off [ -gpu ] [ -v ]
298              Permanently  switches quota off for the filesystem identified by
299              the current path.  Quota can only be  switched  back  on  subse‐
300              quently by unmounting and then mounting again.
301
302       remove [ -gpu ] [ -v ]
303              Remove any space allocated to quota metadata from the filesystem
304              identified by the current path.  Quota must not  be  enabled  on
305              the filesystem, else this operation will report an error.
306
307       dump [ -g | -p | -u ] [ -f file ]
308              Dump out quota limit information for backup utilities, either to
309              standard output (default) or to a file.  This is only  the  lim‐
310              its, not the usage information, of course.
311
312       restore [ -g | -p | -u ] [ -f file ]
313              Restore  quota  limits  from a backup file.  The file must be in
314              the format produced by the dump command.
315
316       quot [ -g | -p | -u ] [ -bir ] [ -acnv ] [ -f file ]
317              Summarize filesystem ownership, by user, group or project.  This
318              command  uses a special XFS "bulkstat" interface to quickly scan
319              an entire filesystem and report usage information.  This command
320              can be used even when filesystem quota are not enabled, as it is
321              a full-filesystem scan (it may also take a long time...). The -a
322              option  displays  information  on all filesystems. The -c option
323              displays a histogram instead of a report. The -n option displays
324              numeric  IDs  rather  than names. The -v option displays verbose
325              information. The -f option send the output to  file  instead  of
326              stdout.
327
328       project [ -cCs [ -d depth ] [ -p path ] id | name ]
329              The -c, -C, and -s options allow the directory tree quota mecha‐
330              nism to be maintained.  -d allows one to limit  recursion  level
331              when processing project directories and -p allows one to specify
332              project paths at command line ( instead of /etc/projects ).  All
333              options are discussed in detail below.
334

DIRECTORY TREE QUOTA

336       The  project  quota mechanism in XFS can be used to implement a form of
337       directory tree quota, where a specified directory and all of the  files
338       and  subdirectories below it (i.e. a tree) can be restricted to using a
339       subset of the available space in the filesystem.
340
341       A managed tree must be setup initially  using  the  -s  option  to  the
342       project command. The specified project name or identifier is matched to
343       one or more trees defined in /etc/projects, and these  trees  are  then
344       recursively descended to mark the affected inodes as being part of that
345       tree.  This process sets an inode flag and the  project  identifier  on
346       every  file  in  the affected tree.  Once this has been done, new files
347       created in the tree will automatically be accounted to the  tree  based
348       on  their  project  identifier.   An attempt to create a hard link to a
349       file in the tree will only succeed if the  project  identifier  matches
350       the project identifier for the tree.  The xfs_io utility can be used to
351       set the project ID for an arbitrary file, but this can only be done  by
352       a privileged user.
353
354       A  previously  setup  tree  can  be  cleared from project quota control
355       through use of the project -C option, which  will  recursively  descend
356       the tree, clearing the affected inodes from project quota control.
357
358       Finally,  the  project -c option can be used to check whether a tree is
359       setup, it reports nothing if the tree is correct, otherwise it  reports
360       the paths of inodes which do not have the project ID of the rest of the
361       tree, or if the inode flag is not set.
362
363       Option -d can be used to limit recursion level (-1 is  infinite,  0  is
364       top  level only, 1 is first level ... ).  Option -p adds possibility to
365       specify project paths in command line without a need for  /etc/projects
366       to exist. Note that if projects file exists then it is also used.
367
368

EXAMPLES

370       Enabling  quota  enforcement on an XFS filesystem (restrict a user to a
371       set amount of space).
372
373            # mount -o uquota /dev/xvm/home /home
374            # xfs_quota -x -c 'limit bsoft=500m bhard=550m tanya' /home
375            # xfs_quota -x -c report /home
376
377       Enabling project quota on an XFS filesystem (restrict files in log file
378       directories to only using 1 gigabyte of space).
379
380            # mount -o prjquota /dev/xvm/var /var
381            # echo 42:/var/log >> /etc/projects
382            # echo logfiles:42 >> /etc/projid
383            # xfs_quota -x -c 'project -s logfiles' /var
384            # xfs_quota -x -c 'limit -p bhard=1g logfiles' /var
385
386       Same as above without a need for configuration files.
387
388            # rm -f /etc/projects /etc/projid
389            # mount -o prjquota /dev/xvm/var /var
390            # xfs_quota -x -c 'project -s -p /var/log 42' /var
391            # xfs_quota -x -c 'limit -p bhard=1g 42' /var
392

CAVEATS

394       The  XFS allocation mechanism will always reserve the maximum amount of
395       space required before proceeding with an allocation.   If  insufficient
396       space  for  this reservation is available, due to the block quota limit
397       being reached for example, this may result in  the  allocation  failing
398       even  though  there  is  sufficient  space.  Quota enforcement can thus
399       sometimes happen in situations where the user is under  quota  and  the
400       end result of some operation would still have left the user under quota
401       had the operation been allowed to  run  its  course.   This  additional
402       overhead is typically in the range of tens of blocks.
403
404       Both  of  these  properties are unavoidable side effects of the way XFS
405       operates, so should be kept in mind when assigning block limits.
406

BUGS

408       Quota support for filesystems with realtime subvolumes is not  yet  im‐
409       plemented,  nor  is the quota warning mechanism (the Linux warnquota(8)
410       tool can be used to provide similar functionality on that platform).
411

FILES

413       /etc/projects       Mapping of numeric project identifiers to  directo‐
414                           ries trees.
415       /etc/projid         Mapping  of  numeric project identifiers to project
416                           names.
417
418

SEE ALSO

420       df(1),  mount(1),  sync(2),  projid(5),  projects(5).   xfs(5).   warn‐
421       quota(8),
422
423
424
425                                                                  xfs_quota(8)
Impressum