From: Nathan Scott Date: Mon, 6 Jun 2005 03:49:30 +0000 (+0000) Subject: Minor man page corrections, patch botch on xfs_quota.8 X-Git-Tag: v2.7.0~24 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=42cf2b9799a9ab02878dc9924673a050c7a8847c;p=thirdparty%2Fxfsprogs-dev.git Minor man page corrections, patch botch on xfs_quota.8 Merge of master-melb:xfs-cmds:22818a by kenmcd. --- diff --git a/man/man8/xfs_db.8 b/man/man8/xfs_db.8 index 87cccdc2d..c91bfc6dd 100644 --- a/man/man8/xfs_db.8 +++ b/man/man8/xfs_db.8 @@ -11,7 +11,7 @@ xfs_db \- debug an XFS filesystem \f2xfs_db\f1 is used to examine an XFS filesystem. Under rare circumstances it can also be used to modify an XFS filesystem, but that task is normally left to \f2xfs_repair\f1(8) or to -scripts such as \f2xfs_chver\f1 that run \f2xfs_db\f1. +scripts such as \f2xfs_admin\f1 that run \f2xfs_db\f1. .PP The options to \f2xfs_db\f1 are: .TP 10 @@ -1224,6 +1224,7 @@ Many messages can come from the \f3check\f1 (\f3blockget\f1) command; these are documented in \f2xfs_check\f1(8). .SH SEE ALSO mkfs.xfs(8), +xfs_admin(8), xfs_check(8), xfs_copy(8), xfs_logprint(8), diff --git a/man/man8/xfs_quota.8 b/man/man8/xfs_quota.8 index e69de29bb..ca0dc7da6 100644 --- a/man/man8/xfs_quota.8 +++ b/man/man8/xfs_quota.8 @@ -0,0 +1,459 @@ +.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).