| 1 |
.TH xfs_quota 8 |
| 2 |
.SH NAME |
| 3 |
xfs_quota \- manage use of quota on XFS filesystems |
| 4 |
.SH SYNOPSIS |
| 5 |
.B xfs_quota |
| 6 |
[ |
| 7 |
.B \-x |
| 8 |
] [ |
| 9 |
.B \-f |
| 10 |
] [ |
| 11 |
.B \-p |
| 12 |
.I prog |
| 13 |
] [ |
| 14 |
.B \-c |
| 15 |
.I cmd |
| 16 |
] ... [ |
| 17 |
.B \-d |
| 18 |
.I project |
| 19 |
] ... [ |
| 20 |
.B \-D |
| 21 |
.I projects_file |
| 22 |
] [ |
| 23 |
.B \-P |
| 24 |
.I projid_file |
| 25 |
] [ |
| 26 |
.IR path " ... ]" |
| 27 |
.br |
| 28 |
.B xfs_quota \-V |
| 29 |
.SH DESCRIPTION |
| 30 |
.B xfs_quota |
| 31 |
is a utility for reporting and editing various aspects of filesystem quota. |
| 32 |
.PP |
| 33 |
The options to |
| 34 |
.B xfs_quota |
| 35 |
are: |
| 36 |
.TP 1.0i |
| 37 |
.BI \-c " cmd" |
| 38 |
.B xfs_quota |
| 39 |
commands may be run interactively (the default) or as arguments on |
| 40 |
the command line. Multiple |
| 41 |
.B \-c |
| 42 |
arguments may be given. |
| 43 |
The commands are run in the sequence given, then the program exits. |
| 44 |
.TP |
| 45 |
.BI \-p " prog" |
| 46 |
Set the program name for prompts and some error messages, |
| 47 |
the default value is |
| 48 |
.BR xfs_quota . |
| 49 |
.TP |
| 50 |
.B \-x |
| 51 |
Enable expert mode. |
| 52 |
All of the administrative commands (see the ADMINISTRATOR COMMANDS |
| 53 |
section below) which allow modifications to the quota system are |
| 54 |
available only in expert mode. |
| 55 |
.TP |
| 56 |
.B \-f |
| 57 |
Enable foreign filesystem mode. |
| 58 |
A limited number of user and administrative commands are available for |
| 59 |
use on some foreign (non-XFS) filesystems. |
| 60 |
.TP |
| 61 |
.BI \-d " project" |
| 62 |
Project names or numeric identifiers may be specified with this option, |
| 63 |
which restricts the output of the individual |
| 64 |
.B xfs_quota |
| 65 |
commands to the set of projects specified. Multiple |
| 66 |
.B \-d |
| 67 |
arguments may be given. |
| 68 |
.TP |
| 69 |
.BI \-D " projects_file" |
| 70 |
Specify a file containing the mapping of numeric project identifiers |
| 71 |
to directory trees. |
| 72 |
.I /etc/projects |
| 73 |
as default, if this option is none. |
| 74 |
.TP |
| 75 |
.BI \-P " projid_file" |
| 76 |
Specify a file containing the mapping of numeric project identifiers |
| 77 |
to project names. |
| 78 |
.I /etc/projid |
| 79 |
as default, if this option is none. |
| 80 |
.TP |
| 81 |
.B \-V |
| 82 |
Prints the version number and exits. |
| 83 |
.PP |
| 84 |
The optional |
| 85 |
.I path |
| 86 |
argument(s) can be used to specify mount points or device files |
| 87 |
which identify XFS filesystems. The output of the individual |
| 88 |
.B xfs_quota |
| 89 |
commands will then be restricted to the set of filesystems specified. |
| 90 |
.PP |
| 91 |
This manual page is divided into two sections \- firstly, |
| 92 |
information for users of filesystems with quota enabled, and the |
| 93 |
.B xfs_quota |
| 94 |
commands of interest to such users; and then information which is |
| 95 |
useful only to administrators of XFS filesystems using quota and the |
| 96 |
quota commands which allow modifications to the quota system. |
| 97 |
.PP |
| 98 |
Note that common to almost all of the individual commands described |
| 99 |
below are the options for specifying which quota types are of interest |
| 100 |
\- user quota |
| 101 |
.RB ( \-u ), |
| 102 |
group quota |
| 103 |
.RB ( \-g ), |
| 104 |
and/or project quota |
| 105 |
.RB ( \-p ). |
| 106 |
Also, several commands provide options to operate on "blocks used" |
| 107 |
.RB ( \-b ), |
| 108 |
"inodes used" |
| 109 |
.RB ( \-i ), |
| 110 |
and/or "realtime blocks used" |
| 111 |
.RB ( \-r ). |
| 112 |
.PP |
| 113 |
Many commands also have extensive online help. Use the |
| 114 |
.B help |
| 115 |
command for more details on any command. |
| 116 |
.SH QUOTA OVERVIEW |
| 117 |
.PP |
| 118 |
In most computing environments, disk space is not infinite. |
| 119 |
The quota subsystem provides a mechanism to control usage of disk space. |
| 120 |
Quotas can be set for each individual user on any/all of the local |
| 121 |
filesystems. |
| 122 |
The quota subsystem warns users when they exceed their allotted limit, |
| 123 |
but allows some extra space for current work (hard limit/soft limit). |
| 124 |
In addition, XFS filesystems with limit enforcement turned off can be |
| 125 |
used as an effective disk usage accounting system. |
| 126 |
.SS Users' View of Disk Quotas |
| 127 |
To most users, disk quotas are either of no concern or a fact of life |
| 128 |
that cannot be avoided. |
| 129 |
There are two possible quotas that can be imposed \- a limit can be set |
| 130 |
on the amount of space a user can occupy, and there may be a limit on |
| 131 |
the number of files (inodes) they can own. |
| 132 |
.PP |
| 133 |
The |
| 134 |
.B quota |
| 135 |
command provides information on the quotas that have been |
| 136 |
set by the system administrators and current usage. |
| 137 |
.PP |
| 138 |
There are four numbers for each limit: current usage, soft limit |
| 139 |
(quota), hard limit, and time limit. |
| 140 |
The soft limit is the number of 1K-blocks (or files) that the user is |
| 141 |
expected to remain below. |
| 142 |
The hard limit cannot be exceeded. |
| 143 |
If a user's usage reaches the hard limit, further requests for space |
| 144 |
(or attempts to create a file) fail with the "Quota exceeded" (EDQUOT) |
| 145 |
error. |
| 146 |
.PP |
| 147 |
When a user exceeds the soft limit, the timer is enabled. |
| 148 |
Any time the quota drops below the soft limits, the timer is disabled. |
| 149 |
If the timer pops, the particular limit that has been exceeded is treated |
| 150 |
as if the hard limit has been reached, and no more resources are allocated |
| 151 |
to the user. |
| 152 |
The only way to reset this condition, short of turning off limit |
| 153 |
enforcement or increasing the limit, is to reduce usage below quota. |
| 154 |
Only the superuser (i.e. a sufficiently capable process) can set the |
| 155 |
time limits and this is done on a per filesystem basis. |
| 156 |
.SS Surviving When the Quota Limit Is Reached |
| 157 |
In most cases, the only way for a user to recover from over-quota |
| 158 |
conditions is to abort whatever activity is in progress on the filesystem |
| 159 |
that has reached its limit, remove sufficient files to bring the limit |
| 160 |
back below quota, and retry the failed program. |
| 161 |
.br |
| 162 |
However, if a user is in the editor and a write fails because of an over |
| 163 |
quota situation, that is not a suitable course of action. |
| 164 |
It is most likely that initially attempting to write the file has truncated |
| 165 |
its previous contents, so if the editor is aborted without correctly writing |
| 166 |
the file, not only are the recent changes lost, but possibly much, or even |
| 167 |
all, of the contents that previously existed. |
| 168 |
.br |
| 169 |
There are several possible safe exits for a user caught in this situation. |
| 170 |
They can use the editor shell escape command to examine their file space |
| 171 |
and remove surplus files. Alternatively, using |
| 172 |
.BR sh (1), |
| 173 |
they can suspend |
| 174 |
the editor, remove some files, then resume it. |
| 175 |
A third possibility is to write the file to some other filesystem (perhaps |
| 176 |
to a file on |
| 177 |
.IR /tmp ) |
| 178 |
where the user's quota has not been exceeded. |
| 179 |
Then after rectifying the quota situation, the file can be moved back to the |
| 180 |
filesystem it belongs on. |
| 181 |
.SS Default Quotas |
| 182 |
The XFS quota subsystem allows a default quota to be enforced |
| 183 |
for any user, group or project which does not have a quota limit |
| 184 |
explicitly set. |
| 185 |
These limits are stored in and displayed as ID 0's limits, although they |
| 186 |
do not actually limit ID 0. |
| 187 |
.SH USER COMMANDS |
| 188 |
.TP |
| 189 |
.B print |
| 190 |
Lists all paths with devices/project identifiers. |
| 191 |
The path list can come from several places \- the command line, |
| 192 |
the mount table, and the |
| 193 |
.I /etc/projects |
| 194 |
file. |
| 195 |
.TP |
| 196 |
.B df |
| 197 |
See the |
| 198 |
.B free |
| 199 |
command. |
| 200 |
.HP |
| 201 |
.B quota |
| 202 |
[ |
| 203 |
.BR \-g " | " \-p " | " \-u |
| 204 |
] [ |
| 205 |
.B \-bir |
| 206 |
] [ |
| 207 |
.B \-hnNv |
| 208 |
] [ |
| 209 |
.B \-f |
| 210 |
.I file |
| 211 |
] [ |
| 212 |
.I ID |
| 213 |
| |
| 214 |
.I name |
| 215 |
] ... |
| 216 |
.br |
| 217 |
Show individual usage and limits, for a single user |
| 218 |
.I name |
| 219 |
or numeric user |
| 220 |
.IR ID . |
| 221 |
The |
| 222 |
.B \-h |
| 223 |
option reports in a "human-readable" format similar to the |
| 224 |
.BR df (1) |
| 225 |
command. The |
| 226 |
.B \-n |
| 227 |
option reports the numeric IDs rather than the name. The |
| 228 |
.B \-N |
| 229 |
option omits the header. The |
| 230 |
.B \-v |
| 231 |
option outputs verbose information. The |
| 232 |
.B \-f |
| 233 |
option sends the output to |
| 234 |
.I file |
| 235 |
instead of stdout. |
| 236 |
.HP |
| 237 |
.B free |
| 238 |
[ |
| 239 |
.B \-bir |
| 240 |
] [ |
| 241 |
.B \-hN |
| 242 |
] [ |
| 243 |
.B \-f |
| 244 |
.I file |
| 245 |
] |
| 246 |
.br |
| 247 |
Reports filesystem usage, much like the |
| 248 |
.BR df (1) |
| 249 |
utility. |
| 250 |
It can show usage for |
| 251 |
.BR b locks, |
| 252 |
.BR i node, |
| 253 |
and/or |
| 254 |
.BR r ealtime |
| 255 |
block space, and shows used, free, and total available. |
| 256 |
If project quota are in use (see the DIRECTORY TREE QUOTA section below), |
| 257 |
it will also report utilisation for those projects (directory trees). The |
| 258 |
.B \-h |
| 259 |
option reports in a "human-readable" format. The |
| 260 |
.B \-N |
| 261 |
option omits the header. The |
| 262 |
.B \-f |
| 263 |
option outputs the report to |
| 264 |
.I file |
| 265 |
instead of stdout. |
| 266 |
.HP |
| 267 |
.B help |
| 268 |
[ |
| 269 |
.I command |
| 270 |
] |
| 271 |
.br |
| 272 |
Online help for all commands, or one specific |
| 273 |
.IR command . |
| 274 |
.TP |
| 275 |
.B quit |
| 276 |
Exit |
| 277 |
.BR xfs_quota . |
| 278 |
.TP |
| 279 |
.B q |
| 280 |
See the |
| 281 |
.B quit |
| 282 |
command. |
| 283 |
.SH QUOTA ADMINISTRATION |
| 284 |
The XFS quota system differs to that of other filesystems |
| 285 |
in a number of ways. |
| 286 |
Most importantly, XFS considers quota information as |
| 287 |
filesystem metadata and uses journaling to provide a higher level |
| 288 |
guarantee of consistency. |
| 289 |
As such, it is administered differently, in particular: |
| 290 |
.IP 1. |
| 291 |
The |
| 292 |
.B quotacheck |
| 293 |
command has no effect on XFS filesystems. |
| 294 |
The first time quota accounting is turned on (at mount time), XFS does |
| 295 |
an automatic quotacheck internally; afterwards, the quota system will |
| 296 |
always be completely consistent until quotas are manually turned off. |
| 297 |
.IP 2. |
| 298 |
There is no need for quota file(s) in the root of the XFS filesystem. |
| 299 |
.IP 3. |
| 300 |
XFS distinguishes between quota accounting and limit enforcement. |
| 301 |
Quota accounting must be turned on at the time of mounting the XFS |
| 302 |
filesystem. |
| 303 |
However, it is possible to turn on/off limit enforcement any time |
| 304 |
quota accounting is turned on. |
| 305 |
The "quota" option to the |
| 306 |
.B mount |
| 307 |
command turns on both (user) quota accounting and enforcement. |
| 308 |
The "uqnoenforce" option must be used to turn on user accounting with |
| 309 |
limit enforcement disabled. |
| 310 |
.IP 4. |
| 311 |
Turning on quotas on the root filesystem is slightly different from |
| 312 |
the above. |
| 313 |
For Linux XFS, the quota mount flags must be passed in with the |
| 314 |
"rootflags=" boot parameter. |
| 315 |
.IP 5. |
| 316 |
It is useful to use the |
| 317 |
.B state |
| 318 |
to monitor the XFS quota subsystem |
| 319 |
at various stages \- it can be used to see if quotas are turned on, |
| 320 |
and also to monitor the space occupied by the quota system itself.. |
| 321 |
.IP 6. |
| 322 |
There is a mechanism built into |
| 323 |
.B xfsdump |
| 324 |
that allows quota limit information to be backed up for later |
| 325 |
restoration, should the need arise. |
| 326 |
.IP 7. |
| 327 |
Quota limits cannot be set before turning on quotas on. |
| 328 |
.IP 8. |
| 329 |
XFS filesystems keep quota accounting on the superuser (user ID zero), |
| 330 |
and the tool will display the superuser's usage information. |
| 331 |
However, limits are never enforced on the superuser (nor are they |
| 332 |
enforced for group and project ID zero). |
| 333 |
.IP 9. |
| 334 |
XFS filesystems perform quota accounting whether the user has quota |
| 335 |
limits or not. |
| 336 |
.IP 10. |
| 337 |
XFS supports the notion of project quota, which can be used to |
| 338 |
implement a form of directory tree quota (i.e. to restrict a |
| 339 |
directory tree to only being able to use up a component of the |
| 340 |
filesystems available space; or simply to keep track of the |
| 341 |
amount of space used, or number of inodes, within the tree). |
| 342 |
.SH ADMINISTRATOR COMMANDS |
| 343 |
.HP |
| 344 |
.B path |
| 345 |
[ |
| 346 |
.I N |
| 347 |
] |
| 348 |
.br |
| 349 |
Lists all paths with devices/project identifiers or set the current |
| 350 |
path to the |
| 351 |
.IR N th |
| 352 |
list entry (the current path is used by many |
| 353 |
of the commands described here, it identifies the filesystem toward |
| 354 |
which a command is directed). |
| 355 |
The path list can come from several places \- the command line, |
| 356 |
the mount table, and the |
| 357 |
.I /etc/projects |
| 358 |
file. |
| 359 |
.HP |
| 360 |
.B report |
| 361 |
[ |
| 362 |
.B \-gpu |
| 363 |
] [ |
| 364 |
.B \-bir |
| 365 |
] [ |
| 366 |
.B \-ahntlLNU |
| 367 |
] [ |
| 368 |
.B \-f |
| 369 |
.I file |
| 370 |
] |
| 371 |
.br |
| 372 |
Report filesystem quota information. |
| 373 |
This reports all quota usage for a filesystem, for the specified |
| 374 |
quota type |
| 375 |
.RB ( u / g / p |
| 376 |
and/or |
| 377 |
.BR b locks/ i nodes/ r ealtime). |
| 378 |
It reports blocks in 1KB units by default. The |
| 379 |
.B \-h |
| 380 |
option reports in a "human-readable" format similar to the |
| 381 |
.BR df (1) |
| 382 |
command. The |
| 383 |
.B \-f |
| 384 |
option outputs the report to |
| 385 |
.I file |
| 386 |
instead of stdout. The |
| 387 |
.B \-a |
| 388 |
option reports on all filesystems. By default, outputs the name of |
| 389 |
the user/group/project. If no name is defined for a given ID, outputs |
| 390 |
the numeric ID instead. The |
| 391 |
.B \-n |
| 392 |
option outputs the numeric ID instead of the name. The |
| 393 |
.B \-L |
| 394 |
and |
| 395 |
.B \-U |
| 396 |
options specify lower and/or upper ID bounds to report on. If upper/lower |
| 397 |
bounds are specified, then by default only the IDs will be displayed |
| 398 |
in output; with the |
| 399 |
.B \-l |
| 400 |
option, a lookup will be performed to translate these IDs to names. The |
| 401 |
.B \-N |
| 402 |
option reports information without the header line. The |
| 403 |
.B \-t |
| 404 |
option performs a terse report. |
| 405 |
.HP |
| 406 |
.B state |
| 407 |
[ |
| 408 |
.B \-gpu |
| 409 |
] [ |
| 410 |
.B \-av |
| 411 |
] [ |
| 412 |
.B \-f |
| 413 |
.I file |
| 414 |
] |
| 415 |
.br |
| 416 |
Report overall quota state information. |
| 417 |
This reports on the state of quota accounting, quota enforcement, |
| 418 |
and the number of extents being used by quota metadata within the |
| 419 |
filesystem. The |
| 420 |
.B \-f |
| 421 |
option outputs state information to |
| 422 |
.I file |
| 423 |
instead of stdout. The |
| 424 |
.B \-a |
| 425 |
option reports state on all filesystems and not just the current path. |
| 426 |
.HP |
| 427 |
.B limit |
| 428 |
[ |
| 429 |
.BR \-g " | " \-p " | " \-u |
| 430 |
] |
| 431 |
.BI bsoft= N |
| 432 |
| |
| 433 |
.BI bhard= N |
| 434 |
| |
| 435 |
.BI isoft= N |
| 436 |
| |
| 437 |
.BI ihard= N |
| 438 |
| |
| 439 |
.BI rtbsoft= N |
| 440 |
| |
| 441 |
.BI rtbhard= N |
| 442 |
.B \-d |
| 443 |
| |
| 444 |
.I id |
| 445 |
| |
| 446 |
.I name |
| 447 |
.br |
| 448 |
Set quota block limits (bhard/bsoft), inode count limits (ihard/isoft) |
| 449 |
and/or realtime block limits (rtbhard/rtbsoft) to N, where N is a |
| 450 |
number representing bytes or inodes. |
| 451 |
For block limits, a number with a s/b/k/m/g/t/p/e multiplication suffix |
| 452 |
as described in |
| 453 |
.BR mkfs.xfs (8) |
| 454 |
is also accepted. |
| 455 |
For inode limits, no suffixes are allowed. |
| 456 |
The |
| 457 |
.B \-d |
| 458 |
option (defaults) can be used to set the default value |
| 459 |
that will be used, otherwise a specific |
| 460 |
.BR u ser/ g roup/ p roject |
| 461 |
.I name |
| 462 |
or numeric |
| 463 |
.IR id entifier |
| 464 |
must be specified. |
| 465 |
.HP |
| 466 |
.B timer |
| 467 |
[ |
| 468 |
.BR \-g " | " \-p " | " \-u |
| 469 |
] [ |
| 470 |
.B \-bir |
| 471 |
] |
| 472 |
.I value |
| 473 |
[ |
| 474 |
.B -d |
| 475 |
| |
| 476 |
.I id |
| 477 |
| |
| 478 |
.I name |
| 479 |
] |
| 480 |
.br |
| 481 |
Allows the quota enforcement timeout (i.e. the amount of time allowed |
| 482 |
to pass before the soft limits are enforced as the hard limits) to |
| 483 |
be modified. The current timeout setting can be displayed using the |
| 484 |
.B state |
| 485 |
command. |
| 486 |
.br |
| 487 |
When setting the default timer via the |
| 488 |
.B \-d |
| 489 |
option, or for |
| 490 |
.B id |
| 491 |
0, or if no argument is given after |
| 492 |
.I value |
| 493 |
the |
| 494 |
.I value |
| 495 |
argument is a number of seconds indicating the relative amount of time after |
| 496 |
soft limits are exceeded, before hard limits are enforced. |
| 497 |
.br |
| 498 |
When setting any other individual timer by |
| 499 |
.I id |
| 500 |
or |
| 501 |
.I name, |
| 502 |
the |
| 503 |
.I value |
| 504 |
is the number of seconds from now, at which time the hard limits will be enforced. |
| 505 |
This allows extending the grace time of an individual user who has exceeded soft |
| 506 |
limits. |
| 507 |
.br |
| 508 |
For |
| 509 |
.I value, |
| 510 |
units of \&'minutes', 'hours', 'days', and 'weeks' are also understood |
| 511 |
(as are their abbreviations 'm', 'h', 'd', and 'w'). |
| 512 |
.br |
| 513 |
.HP |
| 514 |
.B warn |
| 515 |
[ |
| 516 |
.BR \-g " | " \-p " | " \-u |
| 517 |
] [ |
| 518 |
.B \-bir |
| 519 |
] |
| 520 |
.I value |
| 521 |
.B -d |
| 522 |
| |
| 523 |
.I id |
| 524 |
| |
| 525 |
.I name |
| 526 |
.br |
| 527 |
Allows the quota warnings limit (i.e. the number of times a warning |
| 528 |
will be send to someone over quota) to be viewed and modified. The |
| 529 |
.B \-d |
| 530 |
option (defaults) can be used to set the default time |
| 531 |
that will be used, otherwise a specific |
| 532 |
.BR u ser/ g roup/ p roject |
| 533 |
.I name |
| 534 |
or numeric |
| 535 |
.IR id entifier |
| 536 |
must be specified. |
| 537 |
.B NOTE: this feature is not currently implemented. |
| 538 |
.TP |
| 539 |
.BR enable " [ " \-gpu " ] [ " \-v " ]" |
| 540 |
Switches on quota enforcement for the filesystem identified by the |
| 541 |
current path. |
| 542 |
This requires the filesystem to have been mounted with quota enabled, |
| 543 |
and for accounting to be currently active. The |
| 544 |
.B \-v |
| 545 |
option (verbose) displays the state after the operation has completed. |
| 546 |
.TP |
| 547 |
.BR disable " [ " \-gpu " ] [ " \-v " ]" |
| 548 |
Disables quota enforcement, while leaving quota accounting active. The |
| 549 |
.B \-v |
| 550 |
option (verbose) displays the state after the operation has completed. |
| 551 |
.TP |
| 552 |
.BR off " [ " \-gpu " ] [ " \-v " ]" |
| 553 |
Permanently switches quota off for the filesystem identified by the |
| 554 |
current path. |
| 555 |
Quota can only be switched back on subsequently by unmounting and |
| 556 |
then mounting again. |
| 557 |
.TP |
| 558 |
.BR remove " [ " \-gpu " ] [ " \-v " ]" |
| 559 |
Remove any space allocated to quota metadata from the filesystem |
| 560 |
identified by the current path. |
| 561 |
Quota must not be enabled on the filesystem, else this operation will |
| 562 |
report an error. |
| 563 |
.HP |
| 564 |
.B dump |
| 565 |
[ |
| 566 |
.BR \-g " | " \-p " | " \-u |
| 567 |
] [ |
| 568 |
.BR \-L " | " \-U |
| 569 |
] [ |
| 570 |
.B \-f |
| 571 |
.I file |
| 572 |
] |
| 573 |
.br |
| 574 |
Dump out quota limit information for backup utilities, either to |
| 575 |
standard output (default) or to a |
| 576 |
.IR file . |
| 577 |
The |
| 578 |
.B \-L |
| 579 |
and |
| 580 |
.B \-U |
| 581 |
options specify lower and/or upper ID bounds to dump. |
| 582 |
This is only the limits, not the usage information, of course. |
| 583 |
.HP |
| 584 |
.B restore |
| 585 |
[ |
| 586 |
.BR \-g " | " \-p " | " \-u |
| 587 |
] [ |
| 588 |
.B \-f |
| 589 |
.I file |
| 590 |
] |
| 591 |
.br |
| 592 |
Restore quota limits from a backup |
| 593 |
.IR file . |
| 594 |
The file must be in the format produced by the |
| 595 |
.B dump |
| 596 |
command. |
| 597 |
.HP |
| 598 |
.B quot |
| 599 |
[ |
| 600 |
.BR \-g " | " \-p " | " \-u |
| 601 |
] [ |
| 602 |
.B \-bir |
| 603 |
] [ |
| 604 |
.B \-acnv |
| 605 |
] [ |
| 606 |
.B \-f |
| 607 |
.I file |
| 608 |
] |
| 609 |
.br |
| 610 |
Summarize filesystem ownership, by user, group or project. |
| 611 |
This command uses a special XFS "bulkstat" interface to quickly scan |
| 612 |
an entire filesystem and report usage information. |
| 613 |
This command can be used even when filesystem quota are not enabled, |
| 614 |
as it is a full-filesystem scan (it may also take a long time...). The |
| 615 |
.B \-a |
| 616 |
option displays information on all filesystems. The |
| 617 |
.B \-c |
| 618 |
option displays a histogram instead of a report. The |
| 619 |
.B \-n |
| 620 |
option displays numeric IDs rather than names. The |
| 621 |
.B \-v |
| 622 |
option displays verbose information. The |
| 623 |
.B \-f |
| 624 |
option send the output to |
| 625 |
.I file |
| 626 |
instead of stdout. |
| 627 |
.HP |
| 628 |
.B project |
| 629 |
[ |
| 630 |
.B \-cCs |
| 631 |
[ |
| 632 |
.B \-d |
| 633 |
.I depth |
| 634 |
] |
| 635 |
[ |
| 636 |
.B \-p |
| 637 |
.I path |
| 638 |
] |
| 639 |
.I id |
| 640 |
| |
| 641 |
.I name |
| 642 |
] |
| 643 |
.br |
| 644 |
The |
| 645 |
.BR \-c , |
| 646 |
.BR \-C , |
| 647 |
and |
| 648 |
.B \-s |
| 649 |
options allow the directory tree quota mechanism to be maintained. |
| 650 |
.BR \-d |
| 651 |
allows one to limit recursion level when processing project directories |
| 652 |
and |
| 653 |
.BR \-p |
| 654 |
allows one to specify project paths at command line ( instead of |
| 655 |
.I /etc/projects |
| 656 |
). All options are discussed in detail below. |
| 657 |
.SH DIRECTORY TREE QUOTA |
| 658 |
The project quota mechanism in XFS can be used to implement a form of |
| 659 |
directory tree quota, where a specified directory and all of the files |
| 660 |
and subdirectories below it (i.e. a tree) can be restricted to using |
| 661 |
a subset of the available space in the filesystem. |
| 662 |
.PP |
| 663 |
A managed tree must be setup initially using the |
| 664 |
.B \-s |
| 665 |
option to the |
| 666 |
.B project |
| 667 |
command. The specified project name or identifier is matched to one |
| 668 |
or more trees defined in |
| 669 |
.IR /etc/projects , |
| 670 |
and these trees are then recursively descended |
| 671 |
to mark the affected inodes as being part of that tree. |
| 672 |
This process sets an inode flag and the project identifier on every file |
| 673 |
in the affected tree. |
| 674 |
Once this has been done, new files created in the tree will automatically |
| 675 |
be accounted to the tree based on their project identifier. |
| 676 |
An attempt to create a hard link to a file in the tree will only succeed |
| 677 |
if the project identifier matches the project identifier for the tree. |
| 678 |
The |
| 679 |
.B xfs_io |
| 680 |
utility can be used to set the project ID for an arbitrary file, but this |
| 681 |
can only be done by a privileged user. |
| 682 |
.PP |
| 683 |
A previously setup tree can be cleared from project quota control through |
| 684 |
use of the |
| 685 |
.B project \-C |
| 686 |
option, which will recursively descend |
| 687 |
the tree, clearing the affected inodes from project quota control. |
| 688 |
.PP |
| 689 |
Finally, the |
| 690 |
.B project \-c |
| 691 |
option can be used to check whether a |
| 692 |
tree is setup, it reports nothing if the tree is correct, otherwise it |
| 693 |
reports the paths of inodes which do not have the project ID of the rest |
| 694 |
of the tree, or if the inode flag is not set. |
| 695 |
.PP |
| 696 |
Option |
| 697 |
.B \-d |
| 698 |
can be used to limit recursion level (\-1 is infinite, 0 is top level only, |
| 699 |
1 is first level ... ). |
| 700 |
Option |
| 701 |
.B \-p |
| 702 |
adds possibility to specify project paths in command line without a need |
| 703 |
for |
| 704 |
.I /etc/projects |
| 705 |
to exist. Note that if projects file exists then it is also used. |
| 706 |
|
| 707 |
.SH EXAMPLES |
| 708 |
Enabling quota enforcement on an XFS filesystem (restrict a user |
| 709 |
to a set amount of space). |
| 710 |
.nf |
| 711 |
.sp |
| 712 |
.in +5 |
| 713 |
# mount \-o uquota /dev/xvm/home /home |
| 714 |
# xfs_quota \-x \-c 'limit bsoft=500m bhard=550m tanya' /home |
| 715 |
# xfs_quota \-x \-c report /home |
| 716 |
.in -5 |
| 717 |
.fi |
| 718 |
.PP |
| 719 |
Enabling project quota on an XFS filesystem (restrict files in |
| 720 |
log file directories to only using 1 gigabyte of space). |
| 721 |
.nf |
| 722 |
.sp |
| 723 |
.in +5 |
| 724 |
# mount \-o prjquota /dev/xvm/var /var |
| 725 |
# echo 42:/var/log >> /etc/projects |
| 726 |
# echo logfiles:42 >> /etc/projid |
| 727 |
# xfs_quota \-x \-c 'project \-s logfiles' /var |
| 728 |
# xfs_quota \-x \-c 'limit \-p bhard=1g logfiles' /var |
| 729 |
.in -5 |
| 730 |
.fi |
| 731 |
.PP |
| 732 |
Same as above without a need for configuration files. |
| 733 |
.nf |
| 734 |
.sp |
| 735 |
.in +5 |
| 736 |
# rm \-f /etc/projects /etc/projid |
| 737 |
# mount \-o prjquota /dev/xvm/var /var |
| 738 |
# xfs_quota \-x \-c 'project \-s \-p /var/log 42' /var |
| 739 |
# xfs_quota \-x \-c 'limit \-p bhard=1g 42' /var |
| 740 |
.in -5 |
| 741 |
.fi |
| 742 |
.SH CAVEATS |
| 743 |
.PP |
| 744 |
The XFS allocation mechanism will always reserve the |
| 745 |
maximum amount of space required before proceeding with an allocation. |
| 746 |
If insufficient space for this reservation is available, due to the |
| 747 |
block quota limit being reached for example, this may result in the |
| 748 |
allocation failing even though there is sufficient space. |
| 749 |
Quota enforcement can thus sometimes happen in situations where the |
| 750 |
user is under quota and the end result of some operation would still |
| 751 |
have left the user under quota had the operation been allowed to run |
| 752 |
its course. |
| 753 |
This additional overhead is typically in the range of tens of blocks. |
| 754 |
.PP |
| 755 |
Both of these properties are unavoidable side effects of the way XFS |
| 756 |
operates, so should be kept in mind when assigning block limits. |
| 757 |
.SH BUGS |
| 758 |
Quota support for filesystems with realtime subvolumes is not yet |
| 759 |
implemented, nor is the quota warning mechanism (the Linux |
| 760 |
.BR warnquota (8) |
| 761 |
tool can be used to provide similar functionality on that platform). |
| 762 |
.SH FILES |
| 763 |
.PD 0 |
| 764 |
.TP 20 |
| 765 |
.I /etc/projects |
| 766 |
Mapping of numeric project identifiers to directories trees. |
| 767 |
.TP |
| 768 |
.I /etc/projid |
| 769 |
Mapping of numeric project identifiers to project names. |
| 770 |
.PD |
| 771 |
|
| 772 |
.SH SEE ALSO |
| 773 |
.BR df (1), |
| 774 |
.BR mount (1), |
| 775 |
.BR sync (2), |
| 776 |
.BR projid (5), |
| 777 |
.BR projects (5). |
| 778 |
.BR xfs (5). |
| 779 |
.BR warnquota (8), |