+.TH xfs_quota 8
+.SH NAME
+xfs_quota \- manage use of quota on XFS filesystems
+.SH SYNOPSIS
+.nf
+\f3xfs_quota\f1 [ \f3\-x\f1 ] [ \f3\-p\f1 prog ] [ \f3\-c\f1 cmd ] ...
+ [ \f3\-d\f1 project ] ... [path...]
+.fi
+.SH DESCRIPTION
+\f2xfs_quota\f1 is a utility for reporting and editing various
+aspects of filesystem quota.
+.PP
+The options to \f2xfs_quota\f1 are:
+.TP 10
+\f3\-c\f1 \f2cmd\f1
+\f2xfs_quota\f1 commands may be run interactively (the default)
+or as arguments on the command line.
+Multiple \f3\-c\f1 arguments may be given.
+The commands are run in the sequence given, then the program exits.
+.TP
+\f3\-p\f1 \f2prog\f1
+Set the program name for prompts and some error messages,
+the default value is \f2xfs_quota\f1.
+.TP
+\f3\-x\f1
+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.
+.TP
+\f3\-d\f1 \f2project\f1
+Project names or numeric identifiers may be specified with this option,
+which restricts the output of the individual \f3xfs_quota\f1 commands
+to the set of projects specified.
+Multiple \f3\-d\f1 arguments may be given.
+.PP
+The optional \f2path\f1 argument(s) can be used to specify mount
+points or device files which identify XFS filesystems.
+The output of the individual \f3xfs_quota\f1 commands will then
+be restricted to the set of filesystems specified.
+.PP
+This manual page is divided into two sections \- firstly,
+information for users of filesystems with quota enabled, and the
+.B 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.
+.PP
+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 (\f2\-u\f1), group quota (\f2\-g\f1), and/or project
+quota (\f2\-p\f1).
+Also, several commands provide options to operate on "blocks used"
+(\f2\-b\f1), "inodes used" (\f2\-i\f1), and/or "realtime blocks used"
+(\f2\-r\f1).
+.PP
+Many commands also have extensive online help.
+Use the \f3help\f1 command for more details on any command.
+.SH QUOTA OVERVIEW
+.PP
+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.
+.SS 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.
+.br
+The \f2quota\f1 command provides information on the quotas that have been
+set by the system administrators and current usage.
+.br
+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.
+.br
+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.
+.SS 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.
+.br
+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.
+.br
+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
+.BR 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 \f2/tmp\f1) 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.
+.SH USER COMMANDS
+.TP
+\f3path\f1 [ \f2N\f1 ]
+Lists all paths with devices/project identifiers or set the current
+path to the \f2N\f1th 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 \f2/etc/projects\f1 file.
+.TP
+\f3df\f1
+See the \f3free\f1 command.
+.TP
+\f3quota\f1 [ \f2\-gpu\f1 ] [ \f2\-bir\f1 ] [ \f2\-hnNv\f1 ] [ id|name ] ...
+Show individual usage and limits, for a single user name or numeric
+user ID.
+The \f2\-h\f1 option reports in a "human-readable" format similar
+to the
+.BR df (1)
+command.
+.TP
+\f3free\f1 [ \f2\-bir\f1 ] [ \f2\-hN\f1 ]
+Reports filesystem usage, much like the
+.BR df (1)
+utility.
+It can show usage for blocks, inode, and/or realtime block space,
+and shows used, free, and total available.
+If directory quota are in use (see the DIRECTORY QUOTA section below),
+it will also report utilisation for those directory trees.
+The \f2\-h\f1 option reports in a "human-readable" format,
+.TP
+\f3help\f1 [ \f2command\f1]
+Online help for all commands, or one specific \f2command\f1.
+.TP
+\f3quit\f1
+Exit \f2xfs_quota\f1.
+.TP
+\f3q\f1
+See the \f3quit\f1 command.
+.SH 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:
+.TP
+1.
+.BR quotacheck (8)
+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.
+.TP
+2.
+There is no need for quota file(s) in the root of the XFS filesystem.
+.TP
+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
+.BR mount (8)
+command turns on both (user) quota accounting and enforcement.
+The "uqnoenforce" option must be used to turn on user accounting with
+limit enforcement disabled.
+.TP
+4.
+Turning on quotas on the root filesystem is slightly different from
+the above.
+For IRIX XFS, refer to
+.BR quotaon (1)
+For Linux XFS, the quota mount flags must be passed in with the
+"rootflags=" boot parameter.
+.TP
+5.
+It is useful to use the \f2state\f1 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..
+.TP
+6.
+There is a mechanism built into
+.BR xfsdump (8)
+that allows quota limit information to be backed up for later
+restoration, should the need arise.
+.TP
+7.
+Quota limits cannot be set before turning on quotas on.
+.TP
+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).
+.TP
+9.
+XFS filesystems perform quota accounting whether the user has quota
+limits or not.
+.TP
+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).
+.SH ADMINISTRATOR COMMANDS
+.TP
+\f3report\f1 [ \f2\-gpu\f1 ] [ \f2\-bir\f1 ] [ \f2\-ahnNt\f1 ]
+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 \f2\-h\f1 option reports in a "human-readable" format similar
+to the
+.BR df (1)
+command.
+.TP
+\f3state\f1 [ \f2\-gpu\f1 ]
+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.
+.TP
+\f3limit\f1 [ \f2\-gpu\f1 ] \\
+\f2bsoft\f1=N | \f2bhard\f1=N | \f2isoft\f1=N | \f2ihard\f1=N | \f2rtbsoft\f1=N | \f2rtbhard\f1=N... \-d|id|name
+.br
+Set quota block limits (bhard/bsoft), inode count limits (ihard/isoft)
+and/or realtime block limits (rtbhard/rtbsoft).
+The \f2\-d\f1 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.
+.TP
+\f3timer\f1 [ \f2\-gpu\f1 ] [ \f2\-bir\f1 ] 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 \f3state\f1 command.
+The value argument is a number of seconds, but units of 'seconds',
+'minutes', 'hours', 'days', and 'weeks' are also understood
+(as are their abbreviations, 's', 'm', 'h', 'd', and 'w').
+.TP
+\f3warn\f1 [ \f2\-gpu\f1 ] [ \f2\-bir\f1 ] 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 \f2\-d\f1 option (defaults) can be used to set the default time
+that will be used, otherwise a specific user/group/project name or
+numeric identifier must be specified.
+NOTE: this feature is not currently implemented.
+.TP
+\f3enable\f1 [ \f2\-gpu\f1 ] [ \f2\-v\f1 ]
+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 \f2\-v\f1 option (verbose) displays the state after the operation
+has completed.
+.TP
+\f3disable\f1 [ \f2\-gpu\f1 ] [ \f2\-v\f1 ]
+Disables quota enforcement, while leaving quota accounting active.
+The \f2\-v\f1 option (verbose) displays the state after the operation
+has completed.
+.TP
+\f3off\f1 [ \f2\-gpu\f1 ] [ \f2\-v\f1 ]
+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.
+.TP
+\f3remove\f1 [ \f2\-gpu\f1 ] [ \f2\-v\f1 ]
+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.
+.TP
+\f3dump\f1 [ \f2\-gpu\f1 ] [ \f2\-f\f1 \f2file\f1 ]
+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.
+.TP
+\f3restore\f1 [ \f2\-gpu\f1 ] [ \f2\-f\f1 \f2file\f1 ]
+Restore quota limits from a backup \f2file\f1.
+The file must be in the format produced by the \f3dump\f1 command.
+.TP
+\f3quot\f1 [ \f2\-gpu\f1 ] [ \f2\-bir\f1 ] [ \f2\-av\f1 ] [ \f2\-c\f1 ]
+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...).
+.TP
+\f3project\f1 [ \f2\-cds\f1 id|name ]
+Without arguments, this command lists known project names and identifiers
+(based on entries in the
+.I /etc/projects
+and
+.I /etc/projid
+files).
+The \f2\-c\f1, \f2\-C\f1, and \f2\-s\f1 options allow the directory
+tree quota mechanism, discussed in detail below, to be maintained.
+.SH 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.
+.PP
+A managed tree must be setup initially using the
+\f2\-c\f1 option to the \f3project\f1 command.
+The specified project name or identifier is matched to one or more trees
+defined in
+.IR /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
+.B 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.
+.PP
+A previously setup tree can be cleared from project quota control through
+use of the \f3project\f1 \f2\-C\f1 option, which will recursively descend
+the tree, clearing the affected inodes from project quota control.
+.PP
+Finally, the \f3project\f1 \f2\-c\f1 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.
+.SH FILE FORMATS
+There are two files involved with the tree quota mechanism, namely
+.I /etc/projects
+and
+.IR /etc/projid .
+The latter is optional.
+The
+.I projects
+file provides a mapping between numeric project identifiers and those
+directories which are the roots of the quota tree.
+Its format is simply:
+.nf
+.sp .8v
+.in +5
+# comments are hash-prefixed
+# ...
+10:/export/cage
+42:/var/log
+.in -5
+.fi
+.PP
+The
+.I projid
+file provides a mapping between numeric project identifiers and a
+simple human readable name (similar relationship to the one that
+exists between usernames and uids).
+Its format is simply:
+.nf
+.sp .8v
+.in +5
+# comments are hash-prefixed
+# ...
+10:cage
+42:logfiles
+.in -5
+.fi
+.PP
+This file is optional, if a project identifier cannot be mapped to
+a name, it will be displayed as a number only.
+.PP
+.SH EXAMPLES
+Enabling quota enforcement on an XFS filesystem (restrict a user
+to a set amount of space).
+.nf
+.sp .8v
+.in +5
+# mount -o uquota /dev/xvm/home /home
+# xfs_quota -c 'edit bsoft=500m bhard=550m tanya' /home
+# xfs_quota -c report /home
+.in -5
+.fi
+.PP
+Enabling directory quota on an XFS filesystem (restrict files in
+log file directories to only using 1 gigabyte of space).
+.nf
+.sp .8v
+.in +5
+# mount -o pquota /dev/xvm/var /var
+# echo 42:/var/log >> /etc/projects
+# echo logfiles:42 >> /etc/projid
+# xfs_quota -c 'projects -c logfiles' /home
+# xfs_quota -c 'edit -p bhard=1g logfiles' /home
+.in -5
+.fi
+.SH CAVEATS
+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
+.BR sync (2),
+will the usage reported reflect what has actually been written.
+.PP
+In addition, 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.
+.PP
+Both of these properties are unavoidable side effects of the way XFS
+operates, so should be kept in mind when assigning block limits.
+.SH BUGS
+Quota support for filesystems with realtime subvolumes is not yet
+implemented, nor is the quota warning mechanism (the Linux
+.BR warnquota (8)
+tool can be used to provide similar functionality on that platform).
+.SH FILES
+.PD 0
+.TP 20
+.BR /etc/projects
+Mapping of numeric project identifiers to directories trees.
+.TP
+.BR /etc/projid
+Mapping of numeric project identifiers to project names.
+.PD
+.SH SEE ALSO
+df(1),
+mount(1),
+sync(2),
+xfs(5).