search..
No manual entry for -- in section 8
xfs_quota(8)		    System Manager's Manual		   xfs_quota(8)

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 modifi-
		 cations 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 iden-
		 tifiers to directory trees.  /etc/projects as default, if this
		 option is none.

       -P projid_file
		 Specify a file containing the mapping of numeric project iden-
		 tifiers to project names.  /etc/projid as default, if this op-
		 tion is none.

       -V	 Prints the version number and exits.

       The optional path argument(s) can be used to specify mount points or de-
       vice  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 ad-
       ministrators 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  be-
       low  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), "in-
       odes 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 im-
       posed - 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 condi-
       tions  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	 situa-
       tion.   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 pos-
       sibility	 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  nu-
	      meric  user ID.  The -h option reports in a "human-readable" for-
	      mat similar to the df(1) command. The -n option reports  the  nu-
	      meric  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.

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 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 man-
	      ually 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 en-
	      forcement 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  informa-
	      tion.   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  di-
	      rectory  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 cur-
	      rent path to the Nth list entry (the current path is used by many
	      of the commands described here, it identifies the filesystem  to-
	      ward  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 us-
	      age for a filesystem, for the specified quota type (u/g/p	 and/or
	      blocks/inodes/realtime).	 It  reports blocks in 1KB units by de-
	      fault. 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
	      user/group/project name or numeric identifier must be  specified.

       timer [ -g | -p | -u ] [ -bir ] value [ -d | id | name ]
	      Allows the quota enforcement timeout (i.e. the amount of time al-
	      lowed  to	 pass  before  the soft limits are enforced as the hard
	      limits) to be modified. The current timeout setting can  be  dis-
	      played 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 num-
	      ber 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 in-
	      dividual 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 warn-
	      ing  will	 be  send to someone over quota) to be viewed and modi-
	      fied. The -d 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.

       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 op-
	      eration has completed.

       disable [ -gpu ] [ -v ]
	      Disables quota enforcement, while leaving	 quota	accounting  ac-
	      tive. The -v option (verbose) displays the state after the opera-
	      tion has completed.

       off [ -gpu ] [ -v ]
	      Permanently  switches  quota off for the filesystem identified by
	      the current path.	 Quota can only	 be  switched  back  on	 subse-
	      quently 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 in-
	      formation. The -f option send the output to file instead of  std-
	      out.

       project [ -cCs [ -d depth ] [ -p path ] id | name ]
	      The  -c, -C, and -s options allow the directory tree quota mecha-
	      nism 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 re-
       cursively 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	 privi-
       leged 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 spec-
       ify  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 some-
       times happen in situations where the user is under quota and the end re-
       sult 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 op-
       erates, so should be kept in mind when assigning block limits.

BUGS
       Quota support for filesystems with realtime subvolumes is not yet imple-
       mented, 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 directo-
			   ries trees.
       /etc/projid	   Mapping of numeric project  identifiers  to	project
			   names.

SEE ALSO
       df(1),	mount(1),  sync(2),  projid(5),	 projects(5).	xfs(5).	  warn-
       quota(8),

								   xfs_quota(8)