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
66       below  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),
69       "inodes 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
86       imposed  - 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) he 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.  He can use the editor shell escape command to examine  his  file
121       space  and  remove  surplus  files.  Alternatively, using sh(1), he can
122       suspend the editor, remove some files, then resume it.  A third  possi‐
123       bility is to write the file to some other filesystem (perhaps to a file
124       on /tmp) where the user's quota has not been exceeded.  Then after rec‐
125       tifying the quota situation, the file can be moved back to the filesys‐
126       tem it belongs on.
127

USER COMMANDS

129       print  Lists all paths with devices/project identifiers.  The path list
130              can  come  from several places - the command line, the mount ta‐
131              ble, and the /etc/projects file.
132
133       df     See the free command.
134
135       quota [ -g | -p | -u ] [ -bir ] [ -hnNv ] [ -f file ] [ ID | name ] ...
136              Show individual usage and limits, for  a  single  user  name  or
137              numeric  user  ID.   The -h option reports in a "human-readable"
138              format similar to the df(1) command. The -n option  reports  the
139              numeric  IDs  rather  than  the  name.  The  -N option omits the
140              header. The -v option outputs verbose information. The -f option
141              sends the output to file instead of stdout.
142
143       free [ -bir ] [ -hN ] [ -f file ]
144              Reports  filesystem  usage, much like the df(1) utility.  It can
145              show usage for blocks, inode, and/or realtime block  space,  and
146              shows  used, free, and total available.  If project quota are in
147              use (see the DIRECTORY TREE QUOTA section below), it  will  also
148              report  utilisation for those projects (directory trees). The -h
149              option reports in a "human-readable" format. The -N option omits
150              the  header. The -f option outputs the report to file instead of
151              stdout.
152
153       help [ command ]
154              Online help for all commands, or one specific command.
155
156       quit   Exit xfs_quota.
157
158       q      See the quit command.
159

QUOTA ADMINISTRATION

161       The XFS quota system differs to that of other filesystems in  a  number
162       of ways.  Most importantly, XFS considers quota information as filesys‐
163       tem metadata and uses journaling to provide a higher level guarantee of
164       consistency.  As such, it is administered differently, in particular:
165
166       1.     The  quotacheck  command  has no effect on XFS filesystems.  The
167              first time quota accounting is turned on (at  mount  time),  XFS
168              does  an  automatic quotacheck internally; afterwards, the quota
169              system will always be completely  consistent  until  quotas  are
170              manually turned off.
171
172       2.     There  is  no  need  for  quota  file(s)  in the root of the XFS
173              filesystem.
174
175       3.     XFS distinguishes between quota accounting  and  limit  enforce‐
176              ment.   Quota accounting must be turned on at the time of mount‐
177              ing the XFS filesystem.  However, it is possible to turn  on/off
178              limit  enforcement  any time quota accounting is turned on.  The
179              "quota" option to the mount command turns on both  (user)  quota
180              accounting  and  enforcement.   The "uqnoenforce" option must be
181              used to turn on user accounting with limit enforcement disabled.
182
183       4.     Turning on quotas on the root filesystem is  slightly  different
184              from  the  above.   For Linux XFS, the quota mount flags must be
185              passed in with the "rootflags=" boot parameter.
186
187       5.     It is useful to use the state to monitor the XFS quota subsystem
188              at  various  stages - it can be used to see if quotas are turned
189              on, and also to monitor the space occupied by the  quota  system
190              itself..
191
192       6.     There  is a mechanism built into xfsdump that allows quota limit
193              information to be backed up for later  restoration,  should  the
194              need arise.
195
196       7.     Quota limits cannot be set before turning on quotas on.
197
198       8.     XFS  filesystems keep quota accounting on the superuser (user ID
199              zero), and the tool will display the superuser's usage  informa‐
200              tion.   However, limits are never enforced on the superuser (nor
201              are they enforced for group and project ID zero).
202
203       9.     XFS filesystems perform quota accounting whether  the  user  has
204              quota limits or not.
205
206       10.    XFS  supports  the notion of project quota, which can be used to
207              implement a form of directory tree quota  (i.e.  to  restrict  a
208              directory  tree  to only being able to use up a component of the
209              filesystems available space; or simply  to  keep  track  of  the
210              amount of space used, or number of inodes, within the tree).
211

ADMINISTRATOR COMMANDS

213       path [ N ]
214              Lists all paths with devices/project identifiers or set the cur‐
215              rent path to the Nth list entry (the current  path  is  used  by
216              many  of the commands described here, it identifies the filesys‐
217              tem toward which a command is directed).  The path list can come
218              from several places - the command line, the mount table, and the
219              /etc/projects file.
220
221       report [ -gpu ] [ -bir ] [ -ahntlLNU ] [ -f file ]
222              Report filesystem quota information.   This  reports  all  quota
223              usage  for  a  filesystem,  for  the specified quota type (u/g/p
224              and/or blocks/inodes/realtime).  It reports blocks in 1KB  units
225              by  default.  The -h option reports in a "human-readable" format
226              similar to the df(1) command. The -f option outputs  the  report
227              to file instead of stdout. The -a option reports on all filesys‐
228              tems. By default, outputs the name of the user/group/project. If
229              no  name  is  defined  for  a  given  ID, outputs the numeric ID
230              instead. The -n option outputs the numeric  ID  instead  of  the
231              name. The -L and -U options specify lower and upper ID bounds to
232              report on.  If upper/lower bounds are specified, then by default
233              only  the IDs will be displayed in output; with the -l option, a
234              lookup will be performed to translate these IDs to names. The -N
235              option  reports  information  without  the  header  line. The -t
236              option performs a terse report.
237
238       state [ -gpu ] [ -av ] [ -f file ]
239              Report overall quota state information.   This  reports  on  the
240              state  of quota accounting, quota enforcement, and the number of
241              extents being used by quota metadata within the filesystem.  The
242              -f  option  outputs state information to file instead of stdout.
243              The -a option reports state on all filesystems and not just  the
244              current path.
245
246       limit  [  -g  |  -p | -u ] bsoft=N | bhard=N | isoft=N | ihard=N | rtb‐
247              soft=N | rtbhard=N -d | id | name
248              Set  quota  block  limits  (bhard/bsoft),  inode  count   limits
249              (ihard/isoft)  and/or  realtime  block limits (rtbhard/rtbsoft).
250              The -d option (defaults) can be used to set  the  default  value
251              that  will be used, otherwise a specific user/group/project name
252              or numeric identifier must be specified.
253
254       timer [ -g | -p | -u ] [ -bir ] value [ -d | id | name ]
255              Allows the quota enforcement timeout (i.e. the  amount  of  time
256              allowed  to pass before the soft limits are enforced as the hard
257              limits) to be modified. The current timeout setting can be  dis‐
258              played using the state command.
259              When  setting  the default timer via the -d option, or for id 0,
260              or if no argument is given after value the value argument  is  a
261              number  of  seconds indicating the relative amount of time after
262              soft limits are exceeded, before hard limits are enforced.
263              When setting any other individual timer by id or name, the value
264              is the number of seconds from now, at which time the hard limits
265              will be enforced.  This allows extending the grace  time  of  an
266              individual user who has exceeded soft limits.
267              For  value, units of 'minutes', 'hours', 'days', and 'weeks' are
268              also understood (as are their abbreviations 'm', 'h',  'd',  and
269              'w').
270
271       warn [ -g | -p | -u ] [ -bir ] value -d | id | name
272              Allows  the  quota  warnings  limit  (i.e. the number of times a
273              warning will be send to someone over quota)  to  be  viewed  and
274              modified.  The  -d  option  (defaults)  can  be  used to set the
275              default  time  that  will  be   used,   otherwise   a   specific
276              user/group/project name or numeric identifier must be specified.
277              NOTE: this feature is not currently implemented.
278
279       enable [ -gpu ] [ -v ]
280              Switches on quota enforcement for the filesystem  identified  by
281              the  current  path.   This  requires the filesystem to have been
282              mounted with quota enabled, and for accounting to  be  currently
283              active.  The  -v  option  (verbose) displays the state after the
284              operation has completed.
285
286       disable [ -gpu ] [ -v ]
287              Disables  quota  enforcement,  while  leaving  quota  accounting
288              active.  The  -v  option  (verbose) displays the state after the
289              operation has completed.
290
291       off [ -gpu ] [ -v ]
292              Permanently switches quota off for the filesystem identified  by
293              the  current  path.   Quota  can only be switched back on subse‐
294              quently by unmounting and then mounting again.
295
296       remove [ -gpu ] [ -v ]
297              Remove any space allocated to quota metadata from the filesystem
298              identified  by  the  current path.  Quota must not be enabled on
299              the filesystem, else this operation will report an error.
300
301       dump [ -g | -p | -u ] [ -f file ]
302              Dump out quota limit information for backup utilities, either to
303              standard  output  (default) or to a file.  This is only the lim‐
304              its, not the usage information, of course.
305
306       restore [ -g | -p | -u ] [ -f file ]
307              Restore quota limits from a backup file.  The file  must  be  in
308              the format produced by the dump command.
309
310       quot [ -g | -p | -u ] [ -bir ] [ -acnv ] [ -f file ]
311              Summarize filesystem ownership, by user, group or project.  This
312              command uses a special XFS "bulkstat" interface to quickly  scan
313              an entire filesystem and report usage information.  This command
314              can be used even when filesystem quota are not enabled, as it is
315              a full-filesystem scan (it may also take a long time...). The -a
316              option displays information on all filesystems.  The  -c  option
317              displays a histogram instead of a report. The -n option displays
318              numeric IDs rather than names. The -v  option  displays  verbose
319              information.  The  -f  option send the output to file instead of
320              stdout.
321
322       project [ -cCs [ -d depth ] [ -p path ] id | name ]
323              The -c, -C, and -s options allow the directory tree quota mecha‐
324              nism  to  be maintained.  -d allows one to limit recursion level
325              when processing project directories and -p allows one to specify
326              project  paths at command line ( instead of /etc/projects ). All
327              options are discussed in detail below.
328

DIRECTORY TREE QUOTA

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

EXAMPLES

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

CAVEATS

388       XFS implements delayed allocation (aka. allocate-on-flush) and this has
389       implications  for the quota subsystem.  Since quota accounting can only
390       be done when blocks are actually allocated, it  is  possible  to  issue
391       (buffered)  writes  into  a  file  and  not  see  the usage immediately
392       updated.  Only when the data is actually written out, either via one of
393       the  kernels  flushing  mechanisms,  or  via a manual sync(2), will the
394       usage reported reflect what has actually been written.
395
396       In addition, the XFS allocation mechanism will always reserve the maxi‐
397       mum  amount of space required before proceeding with an allocation.  If
398       insufficient space for this reservation is available, due to the  block
399       quota  limit  being reached for example, this may result in the alloca‐
400       tion failing even though there is sufficient space.  Quota  enforcement
401       can  thus  sometimes happen in situations where the user is under quota
402       and the end result of some operation would still  have  left  the  user
403       under  quota  had  the  operation been allowed to run its course.  This
404       additional overhead is typically in the range of tens of blocks.
405
406       Both of these properties are unavoidable side effects of  the  way  XFS
407       operates, so should be kept in mind when assigning block limits.
408

BUGS

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

FILES

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

SEE ALSO

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