Provided by: xfsprogs_2.7.7-1_i386 bug

NAME

       xfs_quota - manage use of quota on XFS filesystems

SYNOPSIS

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

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.

       -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.

       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) he 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.   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.

USER COMMANDS

       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
              table, and the /etc/projects file.

       df     See the free command.

       quota [ -gpu ] [ -bir ] [ -hnNv ] [ 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.

       free [ -bir ] [ -hN ]
              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 directory  quota  are
              in  use  (see  the  DIRECTORY QUOTA section below), it will also
              report utilisation for those directory  trees.   The  -h  option
              reports in a "human-readable" format,

       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 IRIX XFS, refer to quotaon(1M).  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

       report [ -gpu ] [ -bir ] [ -ahnNt ]
              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.

       state [ -gpu ]
              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.

       limit [ -gpu ] \
              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 [ -gpu ] [ -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  ’seconds’,  (as  are their
              abbreviations, ’s’, ’m’, ’h’, ’d’, and ’w’).

       warn [ -gpu ] [ -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
              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
              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 [ -gpu ] [ -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 [ -gpu ] [ -f file ]
              Restore  quota  limits  from a backup file.  The file must be in
              the format produced by the dump command.

       quot [ -gpu ] [ -bir ] [ -av ] [ -c ]
              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...).

       project [ -cds id|name ]
              Without arguments, this command lists known  project  names  and
              identifiers   (based   on   entries  in  the  /etc/projects  and
              /etc/projid files).  The  -c,  -C,  and  -s  options  allow  the
              directory tree quota mechanism, discussed in detail below, to be
              maintained.

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 -c 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.

FILE FORMATS

       There  are  two  files  involved  with the tree quota mechanism, namely
       /etc/projects and /etc/projid.  The latter is optional.   The  projects
       file  provides  a mapping between numeric project identifiers and those
       directories which are the roots of  the  quota  tree.   Its  format  is
       simply:

            # comments are hash-prefixed
            # ...
            10:/export/cage
            42:/var/log

       The  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:

            # comments are hash-prefixed
            # ...
            10:cage
            42:logfiles

       This  file  is  optional, if a project identifier cannot be mapped to a
       name, it will be displayed as a number only.

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 -c report /home

       Enabling  directory  quota  on an XFS filesystem (restrict files in log
       file directories to only using 1 gigabyte of space).

            # mount -o pquota /dev/xvm/var /var
            # echo 42:/var/log >> /etc/projects
            # echo logfiles:42 >> /etc/projid
            # xfs_quota -x -c ’projects -c logfiles’ /home
            # xfs_quota -x -c ’limit -p bhard=1g logfiles’ /home

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 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 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.

IRIX SEE ALSO

       quotaon(1M), xfs(4).

LINUX SEE ALSO

       warnquota(8), xfs(5).

SEE ALSO

       df(1), mount(1), sync(2),

                                                                  xfs_quota(8)