Enable and verify Btrfs quotas without losing the accounting model

You will enable Btrfs subvolume quotas, check whether the feature is active, and run a controlled accounting rescan. The guide also explains the choice between full qgroup accounting and simple quotas, so you know what the numbers mean before using them for limits or monitoring. Allow about 15 minutes for the commands, plus the time needed for a rescan on a large filesystem.

You need the btrfs-progs package and a Btrfs filesystem mounted at a path such as /srv/btrfs. The installed command used for this guide is btrfs from btrfs-progs version 6.6.3. Enabling or disabling quotas changes filesystem state and normally requires root. Reading the help text does not.

1. Check the installed command and target filesystem

Start by confirming the binary and choosing the mount point. Replace the example path with the mount point of the filesystem you intend to manage:

$ btrfs --version
btrfs-progs v6.6.3
$ findmnt --target /srv/btrfs

The target passed to btrfs quota is a path on the filesystem, not a block-device path. A subdirectory under the mount point is also suitable, but using the mount point makes the operation easier to review. If findmnt reports another filesystem type, stop here and correct the path.

Checkpoint: the first command should identify btrfs-progs, and findmnt should show btrfs in its filesystem-type column. Neither command changes the filesystem.

2. Enable full qgroup accounting

Full accounting is the default mode. It tracks referenced and exclusive space through the qgroup hierarchy, which is useful when snapshots share extents and you need to understand what space would be freed by deletion:

$ sudo btrfs quota enable /srv/btrfs

A successful command normally produces no output and returns status 0. Enablement affects extent processing across the filesystem, so it can add overhead to filesystem operations. The local manual explicitly advises against activating quotas unless you intend to use them.

Do not interpret this command as a user-quota setup. Btrfs qgroups are not traditional per-user quotas. They track subvolumes and groups of subvolumes. Use btrfs qgroup afterwards to inspect or limit those groups.

Verify the command's status immediately if you need to distinguish success from a shell or privilege error:

$ printf '%s\n' "$?"
0

For a repeatable check, ask the qgroup command to list the current hierarchy:

$ sudo btrfs qgroup show /srv/btrfs

The exact table depends on the filesystem's subvolumes and qgroups. The important checkpoint is that the command accepts the path and returns a table or a clear diagnostic, rather than silently proving that a particular limit exists.

3. Choose simple quotas only when their accounting fits

Simple quotas, also called squotas, use the same qgroup interface but do not maintain the full shared-versus-exclusive calculation. Space is accounted to the subvolume that first allocated the extent. This reduces the cost of back-reference calculations, but it changes how snapshots and later writes are represented.

Choose simple quotas at enablement time with the explicit option:

$ sudo btrfs quota enable --simple /srv/btrfs

Use this mode for a workload where its accounting rule is acceptable, such as image snapshots whose original extents are treated as immutable. Do not select it merely because the option is shorter or sounds faster. With snapshots, full qgroups can show shared space and exclusive space separately, while simple quotas continue attributing extents to their first owner.

There is no command in this interface for changing the accounting mode in place. Treat mode selection as a filesystem design decision. Record it in the host's operating notes before building alerts around qgroup values.

4. Watch and complete a rescan

After enabling quotas, or after a change that leaves accounting out of date, run a rescan. A rescan discards the current qgroup numbers and scans the metadata again using the current configuration. That is a repair or reconciliation operation, not a harmless display command.

Start a rescan and return to the shell:

$ sudo btrfs quota rescan /srv/btrfs

Check whether it is running:

$ sudo btrfs quota rescan --status /srv/btrfs

If you need a command that does not return until the work is complete, start a rescan and wait:

$ sudo btrfs quota rescan --wait /srv/btrfs

If another process has already started it, --wait can wait for that operation too. To wait without starting a new rescan, use --wait-norescan:

$ sudo btrfs quota rescan --wait-norescan /srv/btrfs

Do not repeatedly launch rescans from a monitoring loop. Check status first, and use a single waiting command where a maintenance job needs a definite completion point. A rescan can take time and its accounting work can add load to a busy filesystem.

5. Inspect qgroups before adding limits

Quota activation creates level-0 qgroups for subvolumes. Their identifiers correspond to subvolume IDs, and the path can be used with qgroup operations where the command supports it. Higher-level groups can contain lower-level groups, which lets you model a user, project, or collection of snapshots.

List qgroups and their limits after the rescan has completed:

$ sudo btrfs qgroup show /srv/btrfs

Read the values as two different questions. Referenced space is data reachable from the qgroup. Exclusive space is data that would be freed if all subvolumes contained in that qgroup were removed. Shared snapshot data can therefore appear in referenced space without being exclusive to either individual subvolume.

Only after this inspection should you use the separate btrfs qgroup limit commands. A referenced-space limit can cause writes to fail with a quota-exceeded error. Test the planned limit with a non-critical subvolume first, and keep the qgroup layout in your change record.

6. Recover from an unwanted configuration

Disabling quotas is a privileged, filesystem-wide change. It removes subvolume quota support for the filesystem:

$ sudo btrfs quota disable /srv/btrfs

Use that only when you have decided that the accounting overhead and qgroup data are no longer wanted. It does not restore a previous qgroup layout for later use. If you only need to correct stale numbers, run a rescan instead of disabling the feature.

If a command fails, capture the exact error and check the mount point, root privileges, filesystem type, and whether another maintenance operation is already active. Do not respond to a quota-exceeded error by disabling quotas on a production filesystem. First identify the affected qgroup and decide whether raising or removing its limit is safe.