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

DIRECTORY TREE QUOTA

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

EXAMPLES

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

CAVEATS

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

BUGS

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

FILES

407       /etc/projects       Mapping of numeric project identifiers to  directo‐
408                           ries trees.
409       /etc/projid         Mapping  of  numeric project identifiers to project
410                           names.
411
412

SEE ALSO

414       df(1),  mount(1),  sync(2),  projid(5),  projects(5).   xfs(5).   warn‐
415       quota(8),
416
417
418
419                                                                  xfs_quota(8)
Impressum