Quotas

Per-user disk limits with quota-aware display in the dashboard Storage widget and the ruTorrent diskspace plugin.

The Quotas package enables Linux kernel-level user disk quotas on QuickBox Pro. Once installed, each user’s storage consumption is capped at their assigned limit. The dashboard Storage widget gains a Quota view showing per-user consumption against the cap, and ruTorrent’s built-in diskspace display reports each user’s quota allocation instead of the raw filesystem size.

Kernel-level enforcement

Uses Linux quota with usrjquota journal support (vfsv1). Limits are hard — once a user hits their cap, writes are refused at the filesystem level.

Per-user assignment

Each user gets an individual limit managed via qb user quota -u <user> -o <size>. Sizes use human-readable units: MB, GB, or TB. A server-wide default fills the gap for users whose limit is not yet set.

Dashboard Storage widget

When quotas are installed, the App Dashboard Storage widget shows a Quota view alongside System and Cloud. The Quota view shows how much of the assigned cap the user has consumed.

Quota-aware ruTorrent diskspace

The ruTorrent diskspace plugin is replaced with a quota-aware override that reports each user's quota total and free space instead of the full filesystem, giving accurate per-user capacity figures in the ruTorrent UI.

Fstab-safe installation

The installer backs up /etc/fstab before editing, edits the target mount with field-aware awk (no sed escaping issues), and restores the backup on removal.

Default quota from system configuration

The server_default_quota_size key in system_configuration sets the fallback limit applied to users whose per-user quota has not been explicitly assigned.

When to use Quotas

Good fit

You share the server with multiple users and want to prevent one user from consuming all available disk
You want the ruTorrent diskspace display to show each user their own cap rather than the full filesystem size
You want the dashboard Storage widget to show per-user quota consumption
You need hard disk limits enforced at the kernel level, not just monitored

Not needed

You have a single-user server with no need to cap storage
Your storage is managed at the volume or container level and kernel quotas would conflict
The filesystem hosting user data does not appear as a distinct mount point in fstab
You only need disk monitoring — Netdata or the System Dashboard provide usage data without enforced limits

Installation

Quotas is an admin-installed, server-wide system feature. It enables Linux disk quotas on one mount point.

Install from the Dashboard

Open App Dashboard → Package Management (/dashboard?mode=packages), find Quotas, and click Install. The install dialog presents a Quota Mount Point selector (it defaults to the server’s primary disk mount) with a live fstab preview showing exactly how /etc/fstab will be modified before you confirm. Reinstall and Remove are on the same panel. Quotas is admin-only — see App Management.

Install from the CLI (automation)

The CLI runs the same installer; the mount point maps to the -qm flag (defaults to the primary mount stored in dashboard_disk_mount):


qb install quota                 # primary disk mount
qb install quota -qm /mnt/data   # target a specific mount
qb reinstall quota               # re-run install (re-edits fstab, re-applies limits)
qb remove quota                  # stop service, restore fstab, purge package

-qm <mount>, --quota-mount <mount>

Mount point to enable quotas on. Defaults to the server's primary mount from dashboard_disk_mount in system_configuration.

qb install quota -qm /mnt/data

Full flag reference: CLI Reference.

Quotas install on a single mount

The quota package enables quotas on one mount point. If your server uses multiple data volumes, install once for the primary data mount and choose the correct path (the dashboard mount selector, or -qm on the CLI). Installing again against a different mount reinstalls the package on the new target.

How the system works

Fstab modification

The installer backs up /etc/fstab to /root/.quickbox/backups/fstab, adds usrjquota=aquota.user,jqfmt=vfsv1 to the target mount’s options, remounts it, builds the quota database, and turns quotas on. On removal, the backup is restored and the package is purged. You don’t run any of these steps yourself — the dashboard’s fstab preview shows the change before you install.

Sudoers grant for the dashboard

The installer grants the dashboard service user passwordless repquota access (via /etc/sudoers.d/dashboard). This is what lets the dashboard Storage widget and the ruTorrent diskspace plugin read per-user quota data.

Per-user quota assignment

At install time, the system iterates all users. For each user it reads quota_size from user_information. If the value is empty or 0, it falls back to server_default_quota_size from system_configuration. The limit is then applied via setquota.

To assign or update a user’s quota limit at any time after install:


qb user quota -u <username> -o <size>

Valid size formats: MB, GB, TB (e.g. 50GB, 500GB, 2TB). Do not use decimal values.


# Examples
qb user quota -u alice -o 100GB
qb user quota -u bob -o 2TB
qb user quota -u charlie -o 500MB

Size format

Sizes must be whole numbers followed immediately by MB, GB, or TB. Decimals are not supported — 1.5TB will produce an error. Use 1500GB instead.

With quotas installed, the App Dashboard Storage widget shows a Quota view. Selecting the Quota view displays a gauge of how much of the user’s assigned cap they have consumed. The System / Quota / Cloud toggle appears for admin users when more than one view is available.

See the App Management docs for full Storage widget details.

ruTorrent diskspace integration

When the quota package is installed and ruTorrent is also present on the server, the installer copies a quota-aware action.php to /srv/rutorrent/plugins/diskspace/action.php. This override replaces the default diskspace plugin behaviour:

It reads the primary disk mount from system_configuration via the shared database
It runs repquota (via the sudoers grant) to look up the authenticated user’s quota data
If the user has quota data, it returns the quota total and free values — so ruTorrent shows the user’s cap and remaining space
If no quota data is found (quota not active for that user), it falls back to PHP disk_total_space / disk_free_space against the full filesystem

The net effect: ruTorrent’s disk-space indicator in the bottom status bar reflects each user’s personal quota, not the shared filesystem.

Alongside the action.php override, the installer also deploys a PHP-FPM systemd drop-in at /etc/systemd/system/php<VERSION>-fpm.service.d/quickbox-quota.conf. This drop-in sets PrivateDevices=no on the PHP-FPM service. The default PHP-FPM service unit ships with PrivateDevices=true, which prevents FPM workers from seeing block device nodes — causing repquota to return nothing and the diskspace plugin to fall back to whole-filesystem totals. The drop-in corrects this by restoring block-device visibility to PHP-FPM.

Install order

Both the action.php override and the PHP-FPM drop-in are applied automatically when both quota and ruTorrent are installed. If you install quota before ruTorrent, run qb reinstall quota after ruTorrent is present to apply both.

Directory layout

etc/

├── fstab# Edited by the installer to add usrjquota=aquota.user,jqfmt=vfsv1 to the target mount options

├── sudoers.d/

│ └── dashboard# Grants the qbxdashboard service user passwordless repquota access for the dashboard Storage widget

└── systemd/

│ └── system/

│ │ └── php<VERSION>-fpm.service.d/

│ │ │ └── quickbox-quota.conf# PHP-FPM drop-in: sets PrivateDevices=no so repquota can read quota data from inside FPM workers (present when ruTorrent is installed)

root/

└── .quickbox/

│ └── backups/

│ │ └── fstab# Pre-install backup of /etc/fstab — restored on removal

srv/

└── rutorrent/

│ └── plugins/

│ │ └── diskspace/

│ │ │ └── action.php# Quota-aware diskspace override — reports per-user quota total/free instead of filesystem totals (present when ruTorrent is installed)

Service management

The Linux quota subsystem runs as quota.service:


# Check quota service status
systemctl status quota.service
 
# Start / stop / restart
systemctl start quota.service
systemctl stop quota.service
systemctl restart quota.service
 
# Check quota usage for all users on all filesystems
repquota -a
 
# Check quota for a specific user
repquota -u /          # replace / with your mount point if different
 
# Check whether quotas are active on a mount
quotaon -p /           # prints "user quotas on / ... are on/off"

Troubleshooting

Mount point not found in fstab

If the installer reports that the specified mount point was not found in fstab, verify the target mount with df -h or mount | grep <mount>. The installer requires an exact match against the mount point column in fstab. Pass the correct path via -qm and reinstall.

Quotas installed but ruTorrent shows filesystem size

Step 1 — Confirm the quota system itself is working.

Check two things before looking at the plugin:

Does /etc/fstab have usrjquota=aquota.user,jqfmt=vfsv1 on your data mount?
Does the dashboard Storage widget show the Quota view with correct per-user consumption?

If both are yes, the kernel quota subsystem is working correctly and the problem is isolated to the ruTorrent diskspace plugin. If either is missing, see the other troubleshooting entries on this page.

Step 2 — Verify which action.php is installed.

Check whether the QuickBox override is in place:


grep -c "quota-aware" /srv/rutorrent/plugins/diskspace/action.php

A result of 1 means the QuickBox override is present. A result of 0 means the file is the stock upstream ruTorrent plugin — a ruTorrent update or reinstall can overwrite it.

Step 3 — Check the PHP-FPM drop-in is present.

The quota installer also deploys a systemd drop-in that allows repquota to run inside PHP-FPM workers. Without it, repquota returns nothing and the plugin falls back to whole-filesystem totals even if action.php is the correct version.

Find your active PHP version first:


find /etc/php -maxdepth 3 -name "rutorrent.conf" -path "*/fpm/pool.d/*" | awk -F/ '{print $4}' | head -1

Then verify the drop-in exists (replace <VERSION> with the output above):


cat /etc/systemd/system/php<VERSION>-fpm.service.d/quickbox-quota.conf

It should contain PrivateDevices=no. If the file is missing or contains different content, the drop-in was not applied.

Step 4 — Restore both files.

If either check in Step 2 or Step 3 showed a missing or incorrect file, restore them now.

Path A — manual restore (surgical):


# 1. Restore the quota-aware diskspace plugin
cp -f /opt/quickbox/config/software/rutorrent/plugins/diskspace/action.php \
      /srv/rutorrent/plugins/diskspace/action.php
 
# 2. Restore the PHP-FPM drop-in
#    Replace <VERSION> with the value returned in Step 3
mkdir -p /etc/systemd/system/php<VERSION>-fpm.service.d
cp -f /opt/quickbox/config/software/quota/php-fpm-quota.conf \
      /etc/systemd/system/php<VERSION>-fpm.service.d/quickbox-quota.conf
 
# 3. Reload systemd and restart PHP-FPM
systemctl daemon-reload
systemctl restart php<VERSION>-fpm

After these commands, re-run the Step 2 and Step 3 checks to confirm both files are in place. The PHP-FPM restart is required for the drop-in to take effect and also clears PHP’s opcode cache so the restored action.php is picked up immediately.

Path B — one command:


qb reinstall quota

qb reinstall quota re-applies the action.php override and the PHP-FPM drop-in and restarts PHP-FPM in a single operation. The end state is identical to Path A.

Step 5 — If the problem persists after reinstalling quota.

Collect the following and open a support request:

Output of grep -c "quota-aware" /srv/rutorrent/plugins/diskspace/action.php
Output of cat /etc/systemd/system/php<VERSION>-fpm.service.d/quickbox-quota.conf
Your ruTorrent version (shown in the dashboard Package Management tab)

repquota returns empty for a user

If repquota shows no data for a user, the user’s quota may not have been set. Run qb user quota -u <username> -o <size> to assign a limit. Also confirm the quota service is running (systemctl status quota.service) and that quotas are active on the mount (quotaon -p /).

Server already had quotas before QuickBox install

If your server had user quotas enabled before QuickBox was installed, the fstab options line may already contain usrjquota. The installer detects this and skips the fstab edit for that mount to avoid duplicating options. In this case the installer still installs the quota package and applies per-user limits.

Best practices

Do

Set a sensible server_default_quota_size in the dashboard General Settings before installing quotas — every new user will inherit it automatically.
After adding a new user, assign their quota explicitly with qb user quota -u <user> -o <size> if their allocation differs from the default.
Run repquota -a periodically to review actual usage against assigned limits before users hit their caps.
If you reinstall ruTorrent after quotas are already installed, run qb reinstall quota afterward to restore the quota-aware diskspace override.
Use whole-number sizes (e.g. 100GB, 2TB) — decimal values are not supported by the quota assignment command.

Don't

Do not edit /etc/fstab manually while quotas are enabled — always run qb reinstall quota to let the installer manage the options field safely.
Do not run quotaoff -a manually while the quota service is enabled — use systemctl stop quota.service to stop quotas cleanly.
Do not set per-user limits below the amount of data the user has already stored — this will immediately make their account exceed quota and may affect running services.
Do not confuse the quota mount limit with storage monitoring — the Netdata integration and System Dashboard track disk usage independently of kernel quota enforcement.

FAQ

Once a user reaches their hard limit, the kernel rejects further writes to the filesystem for that user. Running applications (torrent clients, media servers) will start logging write errors. Reduce the user's current data below the cap, or increase their quota with `qb user quota -u -o ` to restore write access.

Whole numbers followed immediately by MB, GB, or TB — for example: `500MB`, `100GB`, `2TB`. Decimals are not supported. If you need 1.5 TB, use `1500GB`. Sizes are stored in uppercase in the database.

It is the fallback quota size applied to any user whose `quota_size` field in `user_information` is empty or 0. It is stored in `system_configuration` and can be configured from **Settings → General** in the dashboard. At install time, any user with no quota set gets this value applied automatically.

The Quota view only appears when the quota package is installed. Check that it is listed as installed in App Dashboard → Package Management. If it shows as installed but the Quota toggle is missing, verify that the quota service is running (`systemctl status quota.service`) and try reloading the dashboard.

Yes. Pass the `-qm` flag with the target mount path: `qb install quota -qm /mnt/data`. The mount must appear in `/etc/fstab` as a distinct entry. Verify the exact mount point with `df -h` or `mount` before running the install.

Yes. Removal copies `/root/.quickbox/backups/fstab` back to `/etc/fstab`, turns off quotas (`quotaoff -a`), stops and disables `quota.service`, and purges the quota package. The aquota.user files created by quotacheck are not removed — they can be deleted manually if needed.

First confirm the quota system is working: `/etc/fstab` should have `usrjquota=aquota.user,jqfmt=vfsv1` on your data mount, and the dashboard Storage widget should show the Quota view. If both are fine, two things need to be in place: (1) the QuickBox quota-aware `action.php` at `/srv/rutorrent/plugins/diskspace/action.php` — check with `grep -c "quota-aware" /srv/rutorrent/plugins/diskspace/action.php`, expecting `1`; (2) the PHP-FPM systemd drop-in at `/etc/systemd/system/php-fpm.service.d/quickbox-quota.conf` containing `PrivateDevices=no` — without this, `repquota` cannot read quota data from inside FPM workers and the plugin falls back to filesystem totals. Run `qb reinstall quota` to restore both files in one step. If the problem persists, collect the output of both checks and your ruTorrent version and open a support request.

The removal script does not restore the original ruTorrent diskspace plugin. After removing quotas, reinstall ruTorrent (`qb reinstall rutorrent -u `) to restore the stock plugin. The quota-aware action.php will gracefully fall back to standard filesystem totals even if quotas are turned off, so the plugin remains functional.