Convert Legacy Linux Quota Files Safely with convertquota

Get convertquota wrong on a live filesystem and every user's disk quota can go unenforced until the next reboot. You will finish with a legacy quota file converted to the newer aquota.user or aquota.group format, with a backup and a verification trail. The examples use convertquota from quota 4.06, installed here as package version 4.06-1build6.

Allow 15 to 30 minutes for one filesystem, plus more time if you need a maintenance window. You need root access, a mounted filesystem containing the old quota file, enough free space for a backup and a way to stop quota activity safely. This command changes quota metadata, so do not run it casually on a busy production filesystem.

1. Confirm the installed command

Start with read-only checks. These commands do not need elevated privileges unless your local permissions block access to the binary or package database:

$ command -v convertquota
/usr/sbin/convertquota
$ convertquota -V
Quota utilities version 4.06.
$ dpkg-query -W -f='${Package} ${Version}\n' quota
quota 4.06-1build6

The local help describes the positional argument as a mountpoint. The older manual calls it a filesystem. In both cases, supply the mounted filesystem whose quota files are being converted, not the path to quota.user itself.

Checkpoint: record the version and the exact mountpoint you intend to change. If convertquota -V reports a different version, stop and read that installed command's help before copying the examples below.

2. Identify the old quota file

Replace /srv with the actual mountpoint. The following inspection is read-only:

$ findmnt --target /srv -o TARGET,SOURCE,FSTYPE,OPTIONS
$ sudo find /srv -maxdepth 1 -type f \( -name 'quota.user' -o -name 'quota.group' \) -ls

A user quota conversion reads quota.user and writes aquota.user. A group quota conversion reads quota.group and writes aquota.group. The default is user quotas, so use --group when the source is quota.group.

Do not infer the answer from a directory name. Check the file that actually exists, and check whether a destination file is already present:

$ sudo ls -l -- /srv/quota.user /srv/aquota.user
ls: cannot access '/srv/aquota.user': No such file or directory

Your output will differ. If an aquota file already exists, do not overwrite it until you have established whether it is current and made a separate backup.

3. Make a recoverable backup

Stop here if you cannot preserve the source and any existing destination. Conversion writes new quota metadata and may leave you with a partially useful result if interrupted. Back up the files on the same filesystem only as a short-term safeguard, or copy them to separate storage for protection against filesystem damage:

$ sudo install -m 600 -o root -g root -- /srv/quota.user /srv/quota.user.before-convert
$ sudo stat --format='%n %s bytes mode=%a owner=%U:%G' -- /srv/quota.user /srv/quota.user.before-convert
/srv/quota.user 4096 bytes mode=600 owner=root:root
/srv/quota.user.before-convert 4096 bytes mode=600 owner=root:root

The size and ownership are examples, not fixed expectations. Keep the backup until the converted quotas have been checked and used successfully. If the conversion fails, do not delete the source or retry over an existing destination without finding the cause. Recovery normally means restoring the original file from the backup, then checking your quota service's documented activation procedure.

4. Stop quota consumers before the change

Use the normal service or maintenance procedure for your distribution. At minimum, identify whether quotas are enabled before touching their files:

$ sudo quotaon -p /srv
/srv [/dev/mapper/example-root]: user quotas are on

The exact wording depends on the installed quota tools. If quotas are active, schedule a maintenance window and disable them with your normal administrative command before conversion. Do not guess a service name, and do not stop an unrelated filesystem service merely to make this example fit. After conversion, re-enable quotas using the same procedure and verify them with quotaon -p.

This guide does not prescribe an automatic stop command because quota activation is distribution and filesystem specific. A running workload can also create a confusing result while you are inspecting or replacing quota metadata.

5. Convert a user quota file

Run the conversion as root. The command takes the mountpoint, not the old filename:

$ sudo convertquota --user /srv
$ sudo ls -l -- /srv/quota.user /srv/aquota.user
-rw------- 1 root root 4096 Sep 22 10:15 /srv/quota.user
-rw------- 1 root root 8192 Sep 22 10:15 /srv/aquota.user

A successful command may produce no standard output. The useful checkpoint is that the new file exists and is non-empty. Do not treat its exact size, timestamp or ownership as universal; those depend on the quota records and filesystem.

For a group quota file, use the explicit group option instead:

$ sudo convertquota --group /srv
$ sudo test -s /srv/aquota.group && echo 'group quota file is non-empty'
group quota file is non-empty

Do not supply both --user and --group for one run. Convert the other file separately, after checking its source, destination and backup.

6. Handle format and endian conversion deliberately

The normal command converts the old quota file to the newer format. Use --convert-format only when you have a specific old and new format pair required by your environment:

$ sudo convertquota --convert-format oldformat,newformat /srv

oldformat,newformat is a placeholder for values supported by your installed quota tools, not a literal pair to paste. The local help identifies this option as conversion to the VFSv0 quota format but does not list valid names, so do not invent them. Find the format names in the documentation for the software that produced the file or in the source and packaging documentation for your exact build.

Use --convert-endian only for a vfsv0 file that is known to have the old big-endian representation:

$ sudo convertquota --convert-endian /srv

This is a specialised compatibility operation, not a general repair switch. If you are unsure whether byte order is the problem, preserve the files and investigate first. Running it on the wrong input can make diagnosis harder.

7. Re-enable and verify quotas

Once the expected aquota file exists, use your system's normal quota activation command. On a host where quotaon is configured for this filesystem, a typical check is:

$ sudo quotaon -p /srv
/srv [/dev/mapper/example-root]: user quotas are on
$ sudo repquota -s /srv
*** Report for user quotas on device /dev/mapper/example-root

The device name and report rows are host-specific. Check that known users or groups have the expected usage and limits; an empty report is not proof that the conversion preserved useful records. If activation fails, leave the original backup in place, capture the error, and do not delete the generated file while diagnosing it.

There is no universal undo flag. To roll back, disable quotas through the normal procedure, move the generated aquota file out of the way, restore the backed-up legacy file to its original name and then re-enable quotas according to your distribution's documentation. Do not use a blind mv over a file whose status you have not checked.

Done means