platform/docs/filesystem-quotas.md

Filesystem quotas — the prerequisite for per-user and per-team storage limits

Status: planned, not done. Nothing in the platform reads or writes a quota yet.

This is the host-side half. It makes limits enforceable; it does not create any. The platform side — the owner declaring defaults and maxima, and provisioning applying them — is docs/roles-and-teams.md → "Quotas", and it is not built either. Do this first, because a policy nothing enforces is worse than no policy: it reads as a limit and is not one.

Why the kernel and not the platform

Members hold terminal at write and have their own Linux accounts. A quota the platform tracks by counting bytes through the file browser is decorative — a member opens a terminal, or connects over SSH with their own key, and writes past it without the platform seeing the write.

Only the filesystem can refuse. So this is a provisioning feature, not an accounting one.

Where it matters

edge-pertento. It is the first real multi-user deployment and the only host that will hold accounts that are not the owner's. It already has one account, which is the argument for doing this soon rather than carefully later: moving a home directory is easy once and tedious per person.

officer-dev is a development machine and will not be multi-user. alpha is the owner's own. Neither needs this, and neither can do it without the same downtime, so there is no reason to.

What to check BEFORE booting into rescue

Run these on the live machine. They decide whether the procedure below is the right one.

findmnt -no FSTYPE,SOURCE,TARGET /                 # expect ext4, and note the real device
findmnt -no OPTIONS / | tr ',' '\n' | grep -i quota  # expect nothing — that is why we are here
sudo tune2fs -l "$(findmnt -no SOURCE /)" | grep -iE 'features|Inode size'
lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINT
df -h /home

Three things decide the plan:

1. Is /home its own filesystem, or part of /? On a stock Hetzner image it is part of /, so the root filesystem is what gains the feature.
2. Inode size. Only matters if you use project quotas — they need 256 bytes and cannot be enabled on a 128-byte filesystem without recreating it. The plan below avoids project quotas for exactly this reason.
3. Is the device under LVM? alpha is; officer-dev is not. It changes only the device path.

The plan: user quotas and group quotas, not project quotas

Two mount options cover both cases and neither needs a feature the filesystem might lack:

• usrquota — a limit per Linux user. This is the per-account home directory limit.
• grpquota — a limit per Linux group. This is how a team's shared folder gets a limit, because a team is already a Linux group (see docs/roles-and-teams.md — the group is what keeps one team out of another's folder, not the permission grant).

Project quotas (prjquota) would let a directory carry a limit independent of ownership. That is more flexible and it is not needed: every case here is "this user" or "this team", both of which are already identities the kernel knows. Skipping it also skips the inode-size problem entirely.

For the group quota to work, the team folder must be setgid (chmod g+s), so files created inside it inherit the team's group and are charged to it. Without that, a member's files are charged to the member's own primary group and the team limit counts nothing. This is the single easiest thing to get wrong here.

Procedure

Downtime is roughly ten minutes, most of it reboots. The owner has said downtime is acceptable.

1. Install the tools, on the live machine.

sudo apt-get update && sudo apt-get install -y quota

2. Take note of the root device, from the pre-flight above — /dev/sda1 on a stock image, /dev/mapper/<vg>-<lv> under LVM. Every command below uses it.

3. Boot into Hetzner rescue from the Cloud console, and do not mount the filesystem.

4. Check it, then add the feature. tune2fs refuses on a filesystem that is not clean, and the check is worth running anyway before changing metadata:

e2fsck -f /dev/sda1
tune2fs -O quota /dev/sda1
tune2fs -l /dev/sda1 | grep -i features    # 'quota' must now appear

quota here is the ext4 journaled quota feature. It is what lets quotas come up with the filesystem rather than needing a quotacheck scan at every boot, which on 320 GB is not quick.

5. Add the mount options. Back on the normal system — or by mounting the root filesystem from rescue and editing it there — the / line in /etc/fstab gains usrquota,grpquota:

UUID=<unchanged>  /  ext4  defaults,usrquota,grpquota  0  1

6. Reboot into the normal system and confirm.

findmnt -no OPTIONS / | tr ',' '\n' | grep quota   # usrquota, grpquota
sudo quotaon -p /                                   # both should report "is on"
sudo repquota -s /                                  # a table, not an error

Verify it actually refuses

Enabling quotas and setting none is the failure that looks like success. Prove enforcement once, on a throwaway account, before trusting it:

sudo useradd -m quotaprobe
sudo setquota -u quotaprobe 10240 10240 0 0 /        # 10 MB soft and hard
sudo -u quotaprobe dd if=/dev/zero of=/home/quotaprobe/fill bs=1M count=50
# expect: "Disk quota exceeded" and a file of about 10 MB, NOT 50
sudo userdel -r quotaprobe

If that writes 50 MB, quotas are not on, whatever the mount options say.

What this does not do

• It sets no limits. Every existing account is unlimited until something assigns a quota. That is the correct intermediate state: the machine gains the ability, nobody's behaviour changes.
• It does not touch the platform. provision-os.ts does not call setquota yet, and there is nowhere for the owner to declare a default. That is the other half.
• It does not apply to the team folders, because there are no team folders yet. When they arrive they must be setgid or their group quota counts nothing.

When the platform half is built

POST /users/:id/provision-linux already exists as a retry path and is the natural home for this: it becomes "re-apply current policy to this account", covering both a new account and a changed limit.

On a host where quotas are not enabled, the platform must say so — "policy recorded, not enforceable on this host" — rather than storing numbers that do nothing. Same rule as the plugin dependency check: refuse or report, never silently no-op. quotaon -p is the check, and it is cheap enough to run per request.