xfs_quota(8)

💖 NAME 💖

Hiii bestie, this is the xfs_quota(8) page, and it's all about managing quota on XFS filesystems 🎀

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 🌸

okay so xfs_quota is a utility for reporting and editing all sorts of stuff about filesystem quota 💅

The options to xfs_quota are:

• -c cmd — you can run xfs_quota commands interactively (that's the default) or pass them as arguments on the command line. You can give several -c arguments, and they run in the order you wrote them, then the program exits 🍓
• -p prog — sets the program name used in prompts and some error messages. If you don't pick one, it's xfs_quota 🧚
• -x — turns on expert mode 👑 All of the administrative commands (see the ADMINISTRATOR COMMANDS section below) that let you modify the quota system are only available in expert mode, so don't go poking around without it 🙈
• -f — turns on foreign filesystem mode. A small handful of user and administrative commands work on some non-XFS filesystems 🫶
• -d project — project names or numeric IDs go here, and they limit the output of the individual xfs_quota commands to just the projects you specify. You can give multiple -d arguments 💜
• -D projects_file — points to a file that maps numeric project IDs to directory trees. If you don't set this option, it defaults to /etc/projects 🌈
• -P projid_file — points to a file that maps numeric project IDs to project names. If you don't set this option, it defaults to /etc/projid ⭐
• -V — prints the version number and exits. Quick and easy ✨

The optional path argument(s) can be used to point at mount points or device files that identify XFS filesystems. The output of the individual xfs_quota commands will then be limited to just the filesystems you name 🦋

This manual page is split into two sections. First up is info for users of filesystems with quota enabled, plus the xfs_quota commands that matter to them. Then comes the stuff that's only useful to administrators of XFS filesystems using quota, including the quota commands that let you change the quota system 👑

Heads up: almost every individual command below shares the options for choosing which quota types you care about. That's user quota (-u), group quota (-g), and/or project quota (-p). Several commands also let you work on "blocks used" (-b), "inodes used" (-i), and/or "realtime blocks used" (-r) 💅

Lots of commands also come with extensive online help. Use the help command for more details on any command 🎀

🌈 QUOTA OVERVIEW 🌈

Okay, real talk: in most computing environments, disk space is not infinite 😭 The quota subsystem is the thing that keeps usage in check. Quotas can be set for each individual user on any or all of the local filesystems. The quota subsystem warns users when they go over their allotted limit, but it gives them a little extra room for current work (hard limit/soft limit). Also, XFS filesystems with limit enforcement turned off can double as an effective disk usage accounting system 🧾

🥺 Users' View of Disk Quotas

To most users, disk quotas are either no concern at all or just a fact of life that can't be avoided 💀 Two kinds of quota can be imposed: a limit on how much space a user can occupy, and possibly a limit on how many files (inodes) they can own.

The quota command shows the quotas the system administrators have set, along with current usage ✨

Every limit has four numbers: current usage, soft limit (quota), hard limit, and time limit. The soft limit is the number of 1K-blocks (or files) the user is expected to stay below. The hard limit can never be exceeded. If a user hits the hard limit, any further requests for space (or attempts to create a file) fail with the "Quota exceeded" (EDQUOT) error 🚫

When a user goes over the soft limit, the timer starts. Any time the quota drops back below the soft limit, the timer turns off. If the timer pops, the limit that was exceeded gets treated as if the hard limit was reached, and no more resources get allocated to that user. The only ways to reset this condition are to turn off limit enforcement, increase the limit, or get usage back below quota. Only the superuser (that is, 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 an over-quota situation is to abort whatever activity is running on the filesystem that hit its limit, remove enough files to get back below quota, and retry the failed program 🏃‍♀️

Careful with the editor! If a user is in an editor and a write fails because of an over-quota situation, that is NOT a suitable course of action. Initially attempting to write the file has most likely already 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 existed before 😱

There are a few safe exits for someone stuck in this situation. They can use the editor's 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 option is to write the file to some other filesystem (maybe a file on /tmp) where the user's quota hasn't been exceeded. Then, after fixing the quota situation, the file can be moved back to the filesystem it belongs on 🫶

🎀 Default Quotas

The XFS quota subsystem can enforce a default quota for any user, group or project that doesn't have a quota limit explicitly set. These limits are stored in and displayed as ID 0's limits, even though they don't actually limit ID 0 💅

💅 USER COMMANDS 💅

These are the commands regular users get to play with 🌸

• 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 ] ... — shows 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 numeric IDs instead of names. The -N option leaves off the header. The -v option outputs verbose information. The -f option sends the output to a file instead of stdout 📊
• free [ -bir ] [ -hN ] [ -f file ] — reports filesystem usage, kinda like the df(1) utility. It can show usage for blocks, inodes, and/or realtime block space, and it shows used, free, and total available. If project quota is in use (see the DIRECTORY TREE QUOTA section below), it also reports utilisation for those projects (directory trees). The -h option gives you a "human-readable" format. The -N option omits the header. The -f option writes the report to a file instead of stdout 🍓
• help [ command ] — online help for all commands, or for one specific command 🧚
• quit — exits xfs_quota 👋
• q — see the quit command 🙈

👑 QUOTA ADMINISTRATION 👑

Okay, admins, listen up. The XFS quota system is different from other filesystems in a bunch of ways. The biggest one is that XFS treats quota information as filesystem metadata and uses journaling to give a higher-level guarantee of consistency. Because of that, it gets administered differently. Specifically:

1. The quotacheck command has no effect on XFS filesystems. The first time quota accounting gets turned on (at mount time), XFS does an automatic quotacheck internally. After that, the quota system stays completely consistent until quotas are manually turned off 🤌
2. There's no need for quota file(s) in the root of the XFS filesystem 🙅‍♀️
3. XFS keeps quota accounting and limit enforcement separate. Quota accounting has to be turned on when the XFS filesystem is mounted. However, you can turn limit enforcement on or off any time quota accounting is on. The quota option to the mount command turns on both (user) quota accounting and enforcement. To turn on user accounting with limit enforcement disabled, you have to use the uqnoenforce option 🎀
4. Turning on quotas on the root filesystem is a little different from the above. For Linux XFS, the quota mount flags must be passed in with the rootflags= boot parameter 🐧
5. It's useful to use the state to monitor the XFS quota subsystem at various stages. It can show whether quotas are turned on, and it can also monitor the space occupied by the quota system itself.. 🔍
6. There's a mechanism built into xfsdump that lets quota limit information get backed up for later restoration, should the need ever arise 💾
7. Quota limits can't be set before quotas are turned 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 on group and project ID zero) 👑
9. XFS filesystems perform quota accounting whether or not the user has quota limits 📈
10. XFS supports project quota, which can be used to implement a form of directory tree quota. That means you can restrict a directory tree to only using up a portion of the filesystem's available space, or simply keep track of how much space, or how many inodes, the tree uses 🌳

✨ ADMINISTRATOR COMMANDS ✨

okay so these are the admin-only commands 👑 they basically control the whole quota system, so be careful with them bestie 🫶

• path [ N ] 🗺️ — lists every path that has a device or project identifier, or sets the current path to the Nth list entry. The current path is what most of the commands below use to decide which filesystem they're talking to. The list can come from a few places: the command line, the mount table, and the /etc/projects file.
• report [ -gpu ] [ -bir ] [ -ahntlLNU ] [ -f file ] 📊 — reports filesystem quota info for the filesystem you're on. It shows all the quota usage, filtered by the type you pick (u/g/p and/or blocks/inodes/realtime). Blocks show up in 1KB units unless you say otherwise. The -h option switches to a human-readable format, similar to df(1). The -f option sends the report to a file instead of stdout, and -a reports on all filesystems. By default you get the user, group or project name, but if an ID doesn't have a name it falls back to the numeric one. -n forces numeric IDs. -L and -U set lower and/or upper ID bounds. When you use bounds, you only see IDs by default, so add -l if you want those IDs looked up and turned into names. -N drops the header line, and -t gives you a terse report.
• state [ -gpu ] [ -av ] [ -f file ] 🔍 — reports the overall quota state: whether accounting and enforcement are on, and how many extents the quota metadata is using on the filesystem. -f sends it to a file instead of stdout, and -a checks every filesystem, not just the current path. The current timeout setting also shows up here.
• limit [ -g | -p | -u ] bsoft=N | bhard=N | isoft=N | ihard=N | rtbsoft=N | rtbhard=N -d | id | name 🚧 — sets the block limits (bhard/bsoft), inode count limits (ihard/isoft) and/or realtime block limits (rtbhard/rtbsoft) to N. N is a number of bytes or inodes. For block limits you can also use an s/b/k/m/g/t/p/e suffix, the same way mkfs.xfs(8) does it. Inode limits are plain numbers, no suffixes. The -d option sets the default that gets used when nothing more specific is set. Otherwise you have to name a specific user, group or project, or give its numeric ID.
• timer [ -g | -p | -u ] [ -bir ] value [ -d | id | name ] ⏰ — changes the enforcement timeout, which is how long soft limits can be exceeded before they get enforced as hard limits. You can see the current timeout with the state command. When you set the default timer with -d, or for ID 0, or if there's no argument after value, value is a number of seconds counted from when the soft limit gets exceeded, before the hard limit kicks in. For any other individual timer, set by ID or name, value is the number of seconds from now when the hard limits will be enforced. This is how you give a specific user who's gone over their soft limit some extra grace time 🥹 For value, minutes, hours, days, and weeks are understood too, plus their short forms m, h, d, and w.
• warn [ -g | -p | -u ] [ -bir ] value -d | id | name 🔔 — is supposed to let you view and change the warning limit, which is how many times someone over quota gets warned. The -d option sets the default time, otherwise you name a user, group or project, or give a numeric ID. > NOTE: this feature is not currently implemented. so it's a vibe for later bestie, not something that works right now 🙈
• enable [ -gpu ] [ -v ] ✅ — turns quota enforcement on for the filesystem you're on. This needs the filesystem to be mounted with quota enabled, and accounting has to be active right now. -v (verbose) shows the state once it's done.
• disable [ -gpu ] [ -v ] 🚫 — turns enforcement off but leaves accounting running. -v (verbose) shows the state once it's done.
• off [ -gpu ] [ -v ] 🛑 — permanently switches quota off for the filesystem you're on. The only way to turn it back on is to unmount and then mount the filesystem again.
• remove [ -gpu ] [ -v ] 🧹 — removes any space that's been allocated to quota metadata on the filesystem you're on. Quota has to be off first though, or this errors out 😬
• dump [ -g | -p | -u ] [ -L | -U ] [ -f file ] 💾 — dumps the quota limit info for backup tools, either to stdout (the default) or to a file. -L and -U set lower and/or upper ID bounds. It's only the limits, not the usage info, obviously.
• restore [ -g | -p | -u ] [ -f file ] ♻️ — restores quota limits from a backup file. The file has to be in the format that the dump command makes.
• quot [ -g | -p | -u ] [ -bir ] [ -acnv ] [ -f file ] 🥧 — summarises who owns what on the filesystem, by user, group or project. It uses a special XFS "bulkstat" interface to scan the whole filesystem quickly. This works even when filesystem quota isn't enabled, since it's a full-filesystem scan, so yeah it can take a long time 🐢 -a covers all filesystems, -c gives a histogram instead of a report, -n shows numeric IDs instead of names, -v makes it verbose, and -f sends the output to a file instead of stdout.
• project [ -cCs [ -d depth ] [ -p path ] id | name ] 🌳 — the -c, -C and -s options keep the directory tree quota mechanism running. -d limits how deep the recursion goes when processing project directories, and -p lets you give project paths on the command line instead of using /etc/projects. All of this gets explained in detail below.

---

🌳 DIRECTORY TREE QUOTA 🌳

okay this part is so cool 😭 the project quota mechanism in XFS can be used as a kind of directory tree quota. You pick a directory, and it plus everything inside it (files, subdirectories, the whole tree) gets limited to a slice of the space on the filesystem 🫧

You have to set up a managed tree first, using the -s option with the project command. The project name or ID you give gets matched to one or more trees defined in /etc/projects, and those trees get walked recursively so every affected inode gets marked as part of the tree. This sets an inode flag and the project ID on every file in the tree. After that, any new file made in the tree is automatically counted against the tree, based on its project ID. A hard link to a file in the tree will only work if the project ID matches the tree's project ID 🔗 The xfs_io utility can set the project ID on any file, but only a privileged user can do that.

To take a tree back out of project quota control, use project -C. It walks the tree recursively and clears the inodes from project quota control.

The project -c option checks whether a tree is set up. If everything's correct it prints nothing 🤍 If not, it prints the paths of inodes that either don't have the tree's project ID or don't have the inode flag set.

The -d option limits how deep the recursion goes: -1 is infinite, 0 is the top level only, 1 is the first level, and so on. The -p option lets you specify project paths on the command line, so you don't need /etc/projects to exist at all. Heads up though: if a projects file does exist, it gets used too ✨

---

🎀 EXAMPLES 🎀

Enabling quota enforcement on an XFS filesystem, to 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, to restrict files in the log file directories to only 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, but without needing any config 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 ⚠️

okay this one is important bestie 🥺 The XFS allocation mechanism always reserves the maximum amount of space it needs before it goes ahead with an allocation. If there isn't enough space for that reservation, for example because the block quota limit has been reached, the allocation can fail even though there's actually enough space. So quota enforcement can sometimes kick in when the user is still under quota, and the end result of the operation would have stayed under quota if it had been allowed to finish. This extra overhead is usually in the range of tens of blocks.

Both of these things are unavoidable side effects of how XFS works, so keep them in mind when you're setting block limits 🧠

---

🐛 BUGS 🐛

Quota support for filesystems with realtime subvolumes isn't implemented yet 😢 The quota warning mechanism isn't there either. On Linux, the warnquota(8) tool can give you similar functionality though 🐧

---

📁 FILES 📁

• /etc/projects — maps numeric project identifiers to directory trees 🌲
• /etc/projid — maps numeric project identifiers to project names 🏷️

---

🔗 SEE ALSO 🔗

df(1), mount(1), sync(2), projid(5), projects(5), xfs(5), warnquota(8)

---

📜 And that's the whole xfs_quota(8) page, bestie! The footer on the original was just the page name, so there's no version or date to share, but you now officially know your quotas better than most people 💖🦋