Repair Linux Quota Files Safely with quotacheck

quotacheck rebuilds the quota accounting files that quotaon and quotaoff both depend on, and a careless run can wipe out good data. This guide walks through a controlled check or rebuild on one filesystem, including how to pick between user and group quotas and which quota format to use. The examples match quota utilities version 4.06, installed here as Debian package quota 4.06-1build6.

Allow 15 to 30 minutes for a filesystem you know well, longer for a large one. You need root access, a maintenance window, and a clear idea of how quotas are configured on the target filesystem. quotacheck scans directories and writes quota data, so this is not something to run against production just to see what happens.

1. Confirm the command and the target

Start read-only. Confirm the installed version, list mounted filesystems and pin down the exact mount point you plan to scan:

$ quotacheck --version
Quota utilities version 4.06.
$ findmnt --target /srv
TARGET SOURCE     FSTYPE OPTIONS
/srv   /dev/...   ext4   rw,relatime,...

• Swap /srv for your real mount point everywhere below, using the path findmnt gave you.
• Do not pass a directory below the filesystem root. quotacheck expects a filesystem argument; its -a mode reads every mounted non-NFS filesystem listed in /etc/mtab instead.

Check whether the quota files already exist at the filesystem root:

$ sudo ls -l /srv/aquota.user /srv/aquota.group /srv/quota.user /srv/quota.group

Some of those paths will be missing, and that is fine. Version 2 files are named aquota.user or aquota.group; version 1 files are quota.user or quota.group. A missing file is not an error: quotacheck creates it when it scans.

2. Prepare a safe maintenance window

Record the current quota state first, then use the matching quotaoff operation for the filesystem, rather than copying a generic service command into production. After quotacheck finishes, restore the previous quota state with quotaon if your system uses it.

By default, quotacheck also tries to remount the filesystem read-only for the scan, then remounts it read-write afterwards. That is another reason to schedule this properly: a remount can disrupt processes using the mount. Leave that default alone, it is the safer behaviour.

3. Check existing user quota data

With quotas disabled and the filesystem quiet, run a normal user-quota check as root:

# quotacheck --user --verbose /srv
quotacheck: Scanning /dev/... [/srv] done
quotacheck: Checked 12345 directories and 67890 files

The exact progress text depends on the filesystem and its contents. Without --verbose, a clean run stays quiet. Under the hood, quotacheck builds a current usage table and compares it against the existing quota file, updating any inconsistent records. User quotas are the default, but spell out --user anyway so scripts and runbooks say what they mean.

Check the exit status immediately, before anything else runs:

# status=$?
# printf 'quotacheck exit status: %s\n' "$status"
quotacheck exit status: 0

Plausible-looking output is not proof of success. A non-zero status needs investigating before quotas go back on.

4. Rebuild a quota file when it is missing or unusable

Reach for --create-files when you deliberately want a fresh scan without reading the existing quota file:

# quotacheck --user --create-files --backup --verbose /srv

• This writes a fresh user quota file. --backup tells quotacheck to back up the old file before writing new data, which matters when you are repairing something questionable.
• A backup is not a recovery copy. Confirm where the utility places it and preserve it before you delete anything.

To rebuild group quotas instead, swap --group in for --user:

# quotacheck --group --create-files --backup --verbose /srv

Run these as separate, intentional checks when you need both kinds. It keeps the change, and any failure, clear in your maintenance record.

5. Pin the format only when detection needs help

Automatic format detection is normally enough. If an existing quota file is corrupted and you already know the format, pass --format explicitly:

# quotacheck --user --format=vfsv1 --backup --verbose /srv

This version supports vfsold, vfsv0, vfsv1, rpc and xfs. Pick the format the filesystem and quota setup actually use, not the largest-sounding number. If you are not sure, stop and check with the system documentation or whoever set the quotas up.

For corrupted files with duplicate entries, --interactive asks how to proceed each time. --use-first-dquot picks the first duplicate automatically, which can push an unattended repair through, but that is a data-recovery decision, not a routine one. Keep it out of everyday checks.

6. Handle remount and force options carefully

• --no-remount disables the read-only remount attempt. Only use it once you have independently stopped every writer and the mount genuinely cannot be remounted. It removes a safety measure.
• --try-remount lets quotacheck continue in read-write mode if the read-only remount fails. That can leave the scan out of sync with changes made during it; only accept that risk if you can prove nothing else is writing to the filesystem.
• --force permits checking and writing while quotas are enabled. The installed manpage explicitly discourages it because the resulting files may be out of sync.

Do not stack these switches just to force a failing maintenance window through. Fix the mount, service or quota state instead. If a command has already changed quota files and you need to undo it: stop, preserve the generated files and backups, restore the backed-up quota file only through your established recovery procedure, then verify it before running quotaon.

7. Restore and verify quota service

After a successful check, confirm the expected files exist with sensible ownership and timestamps:

# ls -l /srv/aquota.user /srv/aquota.group 2>/dev/null
# findmnt --target /srv
# quotaon -p /srv

The group file may be missing if you only checked user quotas. Use your distribution's quota-enabling procedure to restore the state recorded before maintenance, then query it with the matching status command. Finish with a representative read-only report such as repquota /srv if that is part of your normal workflow.