xfs_quota(inc) - phpMan

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

NAME
       xfs_quota - manage use of quota on XFS filesystems
SYNOPSIS
       xfs_quota  [  -x ] [ -p prog ] [ -c cmd ] ... [ -d project ] ... [ 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.
       -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.
       -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 individ-
       ual  xfs_quota  commands will then be restricted to the set of filesys-
       tems 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 filesys-
       tems.  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 con-
       ditions 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.  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  possi-
       bility 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 rec-
       tifying the quota situation, the file can be moved back to the filesys-
       tem it belongs on.
USER COMMANDS
       print  Lists all paths with devices/project identifiers.  The path list
              can  come  from several places - the command line, the mount ta-
              ble, 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.
QUOTA ADMINISTRATION
       The XFS quota system differs to that of other filesystems in  a  number
       of ways.  Most importantly, XFS considers quota information as filesys-
       tem 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  enforce-
              ment.   Quota accounting must be turned on at the time of mount-
              ing 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  "root-
              flags=" 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
              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 cur-
              rent  path  to  the  Nth list entry (the current path is used by
              many of the commands described here, it identifies the  filesys-
              tem 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  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 filesys-
              tems. 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 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  |  rtb-
              soft=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 dis-
              played 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   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 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 ] [ -f file ]
              Dump out quota limit information for backup utilities, either to
              standard  output  (default) or to a file.  This is only the lim-
              its, 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 mecha-
              nism  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.
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
       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 maxi-
       mum  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 alloca-
       tion 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 directo-
                           ries 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), projid(5), projects(5).

                                                                  xfs_quota(8)