Back to main site | Back to man page index

xfs_quota(8)                                   System Manager's Manual                                   xfs_quota(8)

       xfs_quota - manage use of quota on XFS filesystems

       xfs_quota [ -x ] [ -p prog ] [ -c cmd ] ... [ -d project ] ... [ path ... ]
       xfs_quota -V

       xfs_quota is a utility for reporting and editing various aspects of filesystem quota.

       The options to xfs_quota are:

       -c cmd    xfs_quota  commands may be run interactively (the default) or as arguments on the command line. Mul‐
                 tiple -c arguments may be given.  The commands are run in  the  sequence  given,  then  the  program

       -p prog   Set the program name for prompts and some error messages, the default value is xfs_quota.

       -x        Enable  expert  mode.   All  of  the administrative commands (see the ADMINISTRATOR COMMANDS section
                 below) which allow modifications to the quota system are available only in expert mode.

       -d project
                 Project names or numeric identifiers may be specified with this option, which restricts  the  output
                 of  the individual xfs_quota commands to the set of projects specified. Multiple -d arguments may be

       -V        Prints the version number and exits.

       The optional path argument(s) can be used to specify mount points or device files which identify XFS  filesys‐
       tems. The output of the individual xfs_quota commands will then be restricted to the set of filesystems speci‐

       This manual page is divided into two sections - firstly, information  for  users  of  filesystems  with  quota
       enabled,  and  the  xfs_quota commands of interest to such users; and then information which is useful only to
       administrators of XFS filesystems using quota and the quota commands which allow modifications  to  the  quota

       Note that common to almost all of the individual commands described below are the options for specifying which
       quota types are of interest - user quota (-u), group quota (-g), and/or project  quota  (-p).   Also,  several
       commands  provide  options to operate on "blocks used" (-b), "inodes used" (-i), and/or "realtime blocks used"

       Many commands also have extensive online help. Use the help command for more details on any command.

       In most computing environments, disk space is not infinite.  The quota subsystem provides a mechanism to  con‐
       trol  usage  of  disk  space.  Quotas can be set for each individual user on any/all of the local filesystems.
       The quota subsystem warns users when they exceed their allotted limit, but allows some extra space for current
       work  (hard  limit/soft limit).  In addition, XFS filesystems with limit enforcement turned off can be used as
       an effective disk usage accounting system.

   Users' View of Disk Quotas
       To most users, disk quotas are either of no concern or a fact of life that cannot be avoided.  There  are  two
       possible  quotas  that can be imposed - a limit can be set on the amount of space a user can occupy, and there
       may be a limit on the number of files (inodes) he can own.

       the superuser (i.e. a sufficiently capable process) can set the time limits and this is done on a per filesys‐
       tem basis.

   Surviving When the Quota Limit Is Reached
       In  most cases, the only way for a user to recover from over-quota conditions is to abort whatever activity is
       in progress on the filesystem that has reached its limit, remove sufficient files  to  bring  the  limit  back
       below quota, and retry the failed program.
       However,  if a user is in the editor and a write fails because of an over quota situation, that is not a suit‐
       able course of action.  It is most likely that initially attempting to write the file has truncated its previ‐
       ous  contents, so if the editor is aborted without correctly writing the file, not only are the recent changes
       lost, but possibly much, or even all, of the contents that previously existed.
       There are several possible safe exits for a user caught in this situation.  He can use the editor shell escape
       command  to  examine  his file space and remove surplus files.  Alternatively, using sh(1), he can suspend the
       editor, remove some files, then resume it.  A third possibility is to write the file to some other  filesystem
       (perhaps  to  a  file  on /tmp) where the user's quota has not been exceeded.  Then after rectifying the quota
       situation, the file can be moved back to the filesystem it belongs on.

       print  Lists all paths with devices/project identifiers.  The path list can come from  several  places  -  the
              command line, the mount table, and the /etc/projects file.

       df     See the free command.

       quota [ -g | -p | -u ] [ -bir ] [ -hnNv ] [ -f file ] [ ID | name ] ...
              Show  individual usage and limits, for a single user name or numeric user ID.  The -h option reports in
              a "human-readable" format similar to the df(1) command. The -n option reports the  numeric  IDs  rather
              than the name. The -N option omits the header. The -v option outputs verbose information. The -f option
              sends the output to file instead of stdout.

       free [ -bir ] [ -hN ] [ -f file ]
              Reports filesystem usage, much like the df(1) utility.  It can show usage  for  blocks,  inode,  and/or
              realtime  block space, and shows used, free, and total available.  If project quota are in use (see the
              DIRECTORY TREE QUOTA section below), it will also report  utilisation  for  those  projects  (directory
              trees).  The  -h  option  reports  in a "human-readable" format. The -N option omits the header. The -f
              option outputs the report to file instead of stdout.

       help [ command ]
              Online help for all commands, or one specific command.

       quit   Exit xfs_quota.

       q      See the quit command.

       The XFS quota system differs to that of other filesystems in a number of ways.  Most importantly, XFS  consid‐
       ers  quota  information as filesystem metadata and uses journaling to provide a higher level guarantee of con‐
       sistency.  As such, it is administered differently, in particular:

       1.     The quotacheck command has no effect on XFS filesystems.  The first time quota accounting is turned  on
              (at  mount time), XFS does an automatic quotacheck internally; afterwards, the quota system will always
              be completely consistent until quotas are manually turned off.

       2.     There is no need for quota file(s) in the root of the XFS filesystem.

       6.     There  is  a mechanism built into xfsdump that allows quota limit information to be backed up for later
              restoration, should the need arise.

       7.     Quota limits cannot be set before turning on quotas on.

       8.     XFS filesystems keep quota accounting on the superuser (user ID zero), and the tool  will  display  the
              superuser's  usage  information.   However,  limits  are  never enforced on the superuser (nor are they
              enforced for group and project ID zero).

       9.     XFS filesystems perform quota accounting whether the user has quota limits or not.

       10.    XFS supports the notion of project quota, which can be used to implement a form of directory tree quota
              (i.e.  to  restrict a directory tree to only being able to use up a component of the filesystems avail‐
              able space; or simply to keep track of the amount of space used, or number of inodes, within the tree).

       path [ N ]
              Lists all paths with devices/project identifiers or set the current path to the  Nth  list  entry  (the
              current  path is used by many of the commands described here, it identifies the filesystem toward which
              a command is directed).  The path list can come from several places - the command line, the  mount  ta‐
              ble, and the /etc/projects file.

       report [ -gpu ] [ -bir ] [ -ahntlLNU ] [ -f file ]
              Report  filesystem quota information.  This reports all quota usage for a filesystem, for the specified
              quota type (u/g/p and/or blocks/inodes/realtime).  It reports blocks in 1KB units by  default.  The  -h
              option  reports  in  a  "human-readable" format similar to the df(1) command. The -f option outputs the
              report to file instead of stdout. The -a option reports on all filesystems.  By  default,  outputs  the
              name  of  the user/group/project. If no name is defined for a given ID, outputs the numeric ID instead.
              The -n option outputs the numeric ID instead of the name. The -L and -U options specify lower and upper
              ID bounds to report on.  If upper/lower bounds are specified, then by default only the IDs will be dis‐
              played in output; with the -l option, a lookup will be performed to translate these IDs to  names.  The
              -N option reports information without the header line. The -t option performs a terse report.

       state [ -gpu ] [ -av ] [ -f file ]
              Report  overall quota state information.  This reports on the state of quota accounting, quota enforce‐
              ment, and the number of extents being used by quota metadata within the filesystem. The -f option  out‐
              puts  state  information  to file instead of stdout. The -a option reports state on all filesystems and
              not just the current path.

       limit [ -g | -p | -u ] bsoft=N | bhard=N | isoft=N | ihard=N | rtbsoft=N | rtbhard=N -d | id | name
              Set quota block limits (bhard/bsoft), inode count limits (ihard/isoft)  and/or  realtime  block  limits
              (rtbhard/rtbsoft).  The  -d  option  (defaults) can be used to set the default value that will be used,
              otherwise a specific user/group/project name or numeric identifier must be specified.

       timer [ -g | -p | -u ] [ -bir ] value
              Allows the quota enforcement timeout (i.e. the amount of time allowed to pass before  the  soft  limits
              are enforced as the hard limits) to be modified. The current timeout setting can be displayed using the
              state command. The value argument is a number of seconds, but units of 'minutes', 'hours', 'days',  and
              'weeks' are also understood (as are their abbreviations 'm', 'h', 'd', and 'w').

       warn [ -g | -p | -u ] [ -bir ] value -d | id | name
              Allows the quota warnings limit (i.e. the number of times a warning will be send to someone over quota)
              to be viewed and modified. The -d option (defaults) can be used to set the default time  that  will  be

       off [ -gpu ] [ -v ]
              Permanently  switches  quota  off for the filesystem identified by the current path.  Quota can only be
              switched back on subsequently by unmounting and then mounting again.

       remove [ -gpu ] [ -v ]
              Remove any space allocated to quota metadata from the filesystem identified by the current path.  Quota
              must not be enabled on the filesystem, else this operation will report an error.

       dump [ -g | -p | -u ] [ -f file ]
              Dump  out  quota  limit  information  for backup utilities, either to standard output (default) or to a
              file.  This is only the limits, not the usage information, of course.

       restore [ -g | -p | -u ] [ -f file ]
              Restore quota limits from a backup file.  The file must be in the format produced by the dump command.

       quot [ -g | -p | -u ] [ -bir ] [ -acnv ] [ -f file ]
              Summarize filesystem ownership, by user, group or project.  This command uses a special XFS  "bulkstat"
              interface  to quickly scan an entire filesystem and report usage information.  This command can be used
              even when filesystem quota are not enabled, as it is a full-filesystem scan (it may also  take  a  long
              time...).  The  -a  option  displays information on all filesystems. The -c option displays a histogram
              instead of a report. The -n option displays numeric IDs rather than names. The -v option displays  ver‐
              bose information. The -f option send the output to file instead of stdout.

       project [ -cCs [ -d depth ] [ -p path ] id | name ]
              The  -c,  -C,  and  -s options allow the directory tree quota mechanism to be maintained.  -d allows to
              limit recursion level when processing project directories and -p allows to  specify  project  paths  at
              command line ( instead of /etc/projects ). All options are discussed in detail below.

       The  project quota mechanism in XFS can be used to implement a form of directory tree quota, where a specified
       directory and all of the files and subdirectories below it (i.e. a tree) can be restricted to using  a  subset
       of the available space in the filesystem.

       A  managed tree must be setup initially using the -s option to the project command. The specified project name
       or identifier is matched to one or more trees defined in /etc/projects, and these trees are  then  recursively
       descended  to  mark  the  affected inodes as being part of that tree.  This process sets an inode flag and the
       project identifier on every file in the affected tree.  Once this has been done, new files created in the tree
       will  automatically  be  accounted to the tree based on their project identifier.  An attempt to create a hard
       link to a file in the tree will only succeed if the project identifier matches the project identifier for  the
       tree.   The  xfs_io utility can be used to set the project ID for an arbitrary file, but this can only be done
       by a privileged user.

       A previously setup tree can be cleared from project quota control through use of the project -C option,  which
       will recursively descend the tree, clearing the affected inodes from project quota control.

       Finally, the project -c option can be used to check whether a tree is setup, it reports nothing if the tree is
       correct, otherwise it reports the paths of inodes which do not have the project ID of the rest of the tree, or
       if the inode flag is not set.

       Option  -d  can be used to limit recursion level (-1 is infinite, 0 is top level only, 1 is first level ... ).
       Option -p adds possibility to specify project paths in command line without a need for /etc/projects to exist.
       Note that if projects file exists then it is also used.

            # echo logfiles:42 >> /etc/projid
            # xfs_quota -x -c 'project -s logfiles' /var
            # xfs_quota -x -c 'limit -p bhard=1g logfiles' /var

       Same as above without a need for configuration files.

            # rm -f /etc/projects /etc/projid
            # mount -o prjquota /dev/xvm/var /var
            # xfs_quota -x -c 'project -s -p /var/log 42' /var
            # xfs_quota -x -c 'limit -p bhard=1g 42' /var

       XFS implements delayed allocation (aka. allocate-on-flush) and this has implications for the quota  subsystem.
       Since quota accounting can only be done when blocks are actually allocated, it is possible to issue (buffered)
       writes into a file and not see the usage immediately updated.  Only when the data  is  actually  written  out,
       either  via  one  of the kernels flushing mechanisms, or via a manual sync(2), will the usage reported reflect
       what has actually been written.

       In addition, the XFS allocation mechanism will always reserve the maximum amount of space required before pro‐
       ceeding  with  an allocation.  If insufficient space for this reservation is available, due to the block quota
       limit being reached for example, this may result in the allocation failing even  though  there  is  sufficient
       space.   Quota  enforcement  can thus sometimes happen in situations where the user is under quota and the end
       result of some operation would still have left the user under quota had the operation been allowed to run  its
       course.  This additional overhead is typically in the range of tens of blocks.

       Both  of these properties are unavoidable side effects of the way XFS operates, so should be kept in mind when
       assigning block limits.

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

       /etc/projects       Mapping of numeric project identifiers to directories trees.
       /etc/projid         Mapping of numeric project identifiers to project names.

       quotaon(1M), xfs(4).

       warnquota(8), xfs(5).

       df(1), mount(1), sync(2), projid(5), projects(5).