# xfs_quota

## NAME



           xfs_quota - manage use of quota on XFS filesystems
    


## SYNOPSIS



           **xfs_quota**[ **-x**] [ **-f**] [ **-p** _prog_ ] [ **-c** _cmd_ ] ... [ **-d** _project_ ]
           ... [ **-D** _projects_file_ ] [ **-P** _projid_file_ ] [ _path_ ... ]
           **xfs_quota -V**
    


## DESCRIPTION



           **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. Multiple **-c** arguments
                  may be given.  The commands are run in the sequence given,
                  then the program exits.
    
           **-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.
    
           **-f** Enable foreign filesystem mode.  A limited number of user
                  and administrative commands are available for use on some
                  foreign (non-XFS) filesystems.
    
           **-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 given.
    
           **-D** _projects_file_
                  Specify a file containing the mapping of numeric project
                  identifiers to directory trees.  _/etc/projects_ as default,
                  if this option is none.
    
           **-P** _projid_file_
                  Specify a file containing the mapping of numeric project
                  identifiers to project names.  _/etc/projid_ as default, if
                  this option is none.
    
           **-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 filesystems. The output of the
           individual **xfs_quota** commands will then be restricted to the set
           of filesystems specified.
    
           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 system.
    
           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" (**-r**).
    
           Many commands also have extensive online help. Use the **help**
           command for more details on any command.
    


## QUOTA OVERVIEW



           In most computing environments, disk space is not infinite.  The
           quota subsystem provides a mechanism to control 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) they can own.
    
           The **quota** command provides information on the quotas that have
           been set by the system administrators and current usage.
    
           There are four numbers for each limit:  current usage, soft limit
           (quota), hard limit, and time limit.  The soft limit is the number
           of 1K-blocks (or files) that the user is expected to remain below.
           The hard limit cannot be exceeded.  If a user's usage reaches the
           hard limit, further requests for space (or attempts to create a
           file) fail with the "Quota exceeded" (EDQUOT) error.
    
           When a user exceeds the soft limit, the timer is enabled.  Any
           time the quota drops below the soft limits, the timer is disabled.
           If the timer pops, the particular limit that has been exceeded is
           treated as if the hard limit has been reached, and no more
           resources are allocated to the user.  The only way to reset this
           condition, short of turning off limit enforcement or increasing
           the limit, is to reduce usage below quota.  Only the superuser
           (i.e. a sufficiently capable process) can set the time limits and
           this is done on a per filesystem 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 suitable course of action.
           It is most likely that initially attempting to write the file has
           truncated its previous 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.  They can use the editor shell escape command to
           examine their file space and remove surplus files.  Alternatively,
           using **sh**(1), they 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.
    
       **Default Quotas**
           The XFS quota subsystem allows a default quota to be enforced for
           any user, group or project which does not have a quota limit
           explicitly set.  These limits are stored in and displayed as ID
           0's limits, although they do not actually limit ID 0.
    


## USER COMMANDS



           **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 **b** locks, **i** node, and/or **r** ealtime 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.
    


## QUOTA ADMINISTRATION



           The XFS quota system differs to that of other filesystems in a
           number of ways.  Most importantly, XFS considers quota information
           as filesystem metadata and uses journaling to provide a higher
           level guarantee of consistency.  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.
    
           3.     XFS distinguishes between quota accounting and limit
                  enforcement.  Quota accounting must be turned on at the
                  time of mounting the XFS filesystem.  However, it is
                  possible to turn on/off limit enforcement any time quota
                  accounting is turned on.  The "quota" option to the **mount**
                  command turns on both (user) quota accounting and
                  enforcement.  The "uqnoenforce" option must be used to turn
                  on user accounting with limit enforcement disabled.
    
           4.     Turning on quotas on the root filesystem is slightly
                  different from the above.  For Linux XFS, the quota mount
                  flags must be passed in with the "rootflags=" boot
                  parameter.
    
           5.     It is useful to use the **state** to monitor the XFS quota
                  subsystem at various stages - it can be used to see if
                  quotas are turned on, and also to monitor the space
                  occupied by the quota system itself..
    
           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 available space; or simply to
                  keep track of the amount of space used, or number of
                  inodes, within the tree).
    


## ADMINISTRATOR COMMANDS



    
           **path**[ _N_ ]
                  Lists all paths with devices/project identifiers or set the
                  current path to the _N_ th 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 table, 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 **b** locks/**i** nodes/**r** ealtime).  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/or upper ID bounds to report on.
                  If upper/lower bounds are specified, then by default only
                  the IDs will be displayed 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 enforcement, and the
                  number of extents being used by quota metadata within the
                  filesystem. The **-f** option outputs 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) to N, where N is a number representing
                  bytes or inodes.  For block limits, a number with a
                  s/b/k/m/g/t/p/e multiplication suffix as described in
                  **mkfs.xfs**(8) is also accepted.  For inode limits, no
                  suffixes are allowed.  The **-d** option (defaults) can be used
                  to set the default value that will be used, otherwise a
                  specific **u** ser/**g** roup/**p** roject _name_ or numeric _id_ entifier must
                  be specified.
    
           **timer**[ **-g** | **-p** | **-u**] [ **-bir**] _value_ [ **-d** | _id_ | _name_ ]
                  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.
                  When setting the default timer via the **-d** option, or for **id**
                  0, or if no argument is given after _value_ the _value_
                  argument is a number of seconds indicating the relative
                  amount of time after soft limits are exceeded, before hard
                  limits are enforced.
                  When setting any other individual timer by _id_ or _name,_ the
                  _value_ is the number of seconds from now, at which time the
                  hard limits will be enforced.  This allows extending the
                  grace time of an individual user who has exceeded soft
                  limits.
                  For _value,_ 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 used, otherwise a specific
                  **u** ser/**g** roup/**p** roject _name_ or numeric _id_ entifier must be
                  specified.  **NOTE: this feature is not currently**
                  **implemented.**
    
           **enable**[ **-gpu**] [ **-v**]
                  Switches on quota enforcement for the filesystem identified
                  by the current path.  This requires the filesystem to have
                  been mounted with quota enabled, and for accounting to be
                  currently active. The **-v** option (verbose) displays the
                  state after the operation has completed.
    
           **disable**[ **-gpu**] [ **-v**]
                  Disables quota enforcement, while leaving quota accounting
                  active. The **-v** option (verbose) displays the state after
                  the operation has completed.
    
           **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**] [ **-L** | **-U**] [ **-f** _file_ ]
                  Dump out quota limit information for backup utilities,
                  either to standard output (default) or to a _file_.  The **-L**
                  and **-U** options specify lower and/or upper ID bounds to
                  dump.  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
                  verbose 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 one to limit
                  recursion level when processing project directories and **-p**
                  allows one to specify project paths at command line (
                  instead of _/etc/projects_ ). All options are discussed in
                  detail below.
    


## DIRECTORY TREE QUOTA



           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.
    


## EXAMPLES



           Enabling quota enforcement on an XFS filesystem (restrict a user
           to a set amount of space).
    
                # mount -o uquota /dev/xvm/home /home
                # xfs_quota -x -c 'limit bsoft=500m bhard=550m tanya' /home
                # xfs_quota -x -c report /home
    
           Enabling project quota on an XFS filesystem (restrict files in log
           file directories to only using 1 gigabyte of space).
    
                # mount -o prjquota /dev/xvm/var /var
                # echo 42:/var/log >> /etc/projects
                # 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
    


## CAVEATS



           The XFS allocation mechanism will always reserve the maximum
           amount of space required before proceeding 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.
    


## BUGS



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


## FILES



           _/etc/projects_
                  Mapping of numeric project identifiers to directories
                  trees.
           _/etc/projid_
                  Mapping of numeric project identifiers to project names.
    


* * *