Set and Verify XFS User and Project Quotas with xfs_quota

You will inspect an XFS filesystem's quota state, set a limit for one user or project, and verify the result without guessing what the command changed. The examples match xfs_quota 6.6.0 from xfsprogs 6.6.0-1ubuntu2.1. Allow about 15 minutes for an existing quota-enabled mount. Enabling quota at mount time is a separate, service-affecting change and may need a maintenance window.

This guide assumes an XFS mount at /srv/data. Replace that path with a real XFS mount. Commands that only inspect state are normally unprivileged, but changing quota configuration, mounting with quota options, and walking a project tree require root or equivalent filesystem privileges.

1. Confirm the command and the target mount

Check which executable will run, then confirm that the target is an XFS filesystem:

$ command -v xfs_quota
/usr/sbin/xfs_quota
$ findmnt -no SOURCE,FSTYPE,TARGET /srv/data
/dev/mapper/vg-data xfs /srv/data
$ xfs_quota -V
xfs_quota version 6.6.0

The exact device name will differ. Stop if the filesystem type is not xfs. The -f option is for limited operation on some foreign filesystems; it does not turn a non-XFS filesystem into an XFS quota target.

2. Inspect quota state before changing anything

Use expert mode for the administrative state command, and restrict it to the mount you checked:

$ sudo xfs_quota -x -c 'state -gpu' /srv/data

Expect a report describing accounting and enforcement for the requested quota types, together with quota metadata details. Accounting and enforcement are different states. XFS must have accounting active before limits can be set, while enforcement can be enabled or disabled independently.

For a compact report of current usage and limits, run:

$ sudo xfs_quota -x -c 'report -h -gpu' /srv/data

report uses 1K blocks unless -h requests human-readable values. If a quota type is not enabled, its report may be empty or unavailable. Do not infer that a missing user row means the user has no files: the report is about quota records, not a full ownership scan.

3. Enable accounting at the mount boundary

If state shows that the required accounting is off, quota cannot be repaired by adding another limit command. XFS quota accounting is enabled when the filesystem is mounted. User, group and project accounting use mount options such as uquota, gquota and prjquota.

$ findmnt -no OPTIONS /srv/data
rw,relatime,attr2,inode64,logbufs=8

Use your normal mount-management system to add the required option. A direct example for a filesystem that is being mounted, not a command to run blindly on a live service, is:

# mount -o uquota,prjquota /dev/mapper/vg-data /srv/data

Do not copy that device name or overwrite an existing option list without checking it. After the planned mount change, repeat step 2. The XFS quota system performs its consistency check when accounting is first turned on; it does not use the traditional quotacheck workflow described for some other filesystems.

4. Set a user quota

Once user accounting is active, set a soft and hard block limit. The hard limit is the ceiling. The soft limit starts the grace period when crossed. This example gives user alice a 5 GiB soft limit and a 5.5 GiB hard limit:

# xfs_quota -x -c 'limit -u bsoft=5g bhard=5500m alice' /srv/data
# xfs_quota -x -c 'report -h -u' /srv/data

The command changes quota metadata, so keep the -x expert flag visible. Block values accept unit suffixes; inode limits use counts and do not accept those suffixes. For example, an inode limit would use isoft=100000 ihard=110000.

To undo this particular user limit, set the values back to zero, then verify the row:

# xfs_quota -x -c 'limit -u bsoft=0 bhard=0 alice' /srv/data
# xfs_quota -x -c 'report -h -u alice' /srv/data

Check the output rather than assuming the undo succeeded. A limit is not the same as current usage: removing the limit does not delete files or reduce the user's existing consumption.

5. Define and enforce a project tree

Project quotas account for a directory tree rather than a single login. The two optional configuration files keep the numeric project ID, its directory tree and its readable name separate:

# /etc/projects
42:/srv/data/logs

# /etc/projid
logs:42

Each non-comment /etc/projects line is number:path. Each non-comment /etc/projid line is name:number. These files are optional. The -D and -P options can select alternative files, and project -p can supply a path directly.

# xfs_quota -x -c 'project -s logs' /srv/data
# xfs_quota -x -c 'project -c logs' /srv/data

The check command is quiet when the tree is correct. Any paths it prints need investigation. A direct-path setup avoids the mapping files, but it still changes inode project metadata:

# xfs_quota -x -c 'project -s -p /srv/data/logs 42' /srv/data

Now apply a project block limit and verify project usage:

# xfs_quota -x -c 'limit -p bhard=1g logs' /srv/data
# xfs_quota -x -c 'report -h -p' /srv/data

To remove the project quota from the tree, first disable or remove its limit as appropriate, then use project -C. This recursively clears project control from the managed tree; it does not remove the directory contents:

# xfs_quota -x -c 'project -C logs' /srv/data
# xfs_quota -x -c 'project -c logs' /srv/data

6. Diagnose the common traps

• Limit rejected: check state -gpu and the mount options. Limits cannot be set before the relevant accounting is enabled.
• Names appear as numbers: check the spelling and location of /etc/projects and /etc/projid. An unmapped project ID is displayed numerically, which is not itself a quota failure.
• Project check prints paths: the tree is inconsistent. Do not ignore the list. Re-run the setup for the intended path after confirming that the mapping points to the right directory.
• A nearly-empty filesystem still refuses an allocation: XFS may reserve more space for an operation than its final result needs. Leave headroom when choosing a hard block limit.
• Removing a limit does not reclaim space: quota metadata and file data are separate. Inspect ownership and usage with report or, when quotas are disabled, use the full-filesystem quot scan. That scan can take a long time.