cv4pve-cli-tui/docs/plans/lxc-shrink.md

Shrink a container's root disk

Problem

Proxmox only grows disks (resize_vm dies with "unable to shrink disk size"). A container whose rootfs was sized too large cannot be made smaller from the web UI or this TUI. Two routes exist, verified against pve-container 6.1.18 (master) source:

1. API: restore a backup with an explicit rootfs=<storage>:<GiB> ("advanced restore mode", pct.adoc). Reachable through cv4pve-cli (do restore ct ... --rootfs S:N forwards the key; checked with --dry-run).
2. Node shell: copy the files into a new, smaller volume and swap it in.

Both are dangerous; the TUI must say so plainly.

Approach

A. TUI: smaller rootfs on restore (container backups only)

• RestoreScreen gets an optional field "Root disk GiB" for lxc backups. Empty = today's behaviour, unchanged.
• With a size set, only New guest is allowed. Overwrite + size is refused: with force=1 PVE destroys every old volume before it extracts, and a failed extraction then deletes the new disks and the config too; the container is gone.
• cli.restore() gets rootfs_gb: int | None; when set it checks it with _positive (a size of 0 makes PVE allocate an unlimited subvol on ZFS/dir) and adds --rootfs <storage>:<N> (same storage as the dialog's choice). Never ignore-unpack-errors.
• The confirm screen for a shrink restore is a separate, red warning:
  • every mpX of the backup is dropped from the new config; files of backup=1 mount points land inside the root disk and count against its size; backup=0 mount points are not in the backup at all;
  • raw lxc.* lines (including lxc.mount.entry bind mounts) may come back when cv4pve-cli runs as root@pam: do not run both guests at once;
  • rootfs options (acl, quota, mountoptions, replicate) are not carried over;
  • names the guest's current mount points, saying the backup may differ;
  • shows rootfs used space when the guest is running (status/current disk; 0 when stopped, shown as "unknown"), and says this is not a fit check: the backup may be older, mount point data and ext4 overhead (5 % reserve, inodes) come on top;
  • a too-small disk makes the restore task fail; the original is untouched because this is always a new VMID.
• Hard refusal only where it is certain: size not a positive integer, or size <= used rootfs GiB of a running guest.
• Known limit, unchanged from today's restore: run(timeout=3600) can give up while the PVE task still runs.

B. Node script scripts/pct-shrink-rootfs (bash, run as root on the node)

Usage: pct-shrink-rootfs [--yes] <vmid> <new-size-GiB>. Without --yes it only measures and prints the plan; measuring runs pct mount/pct unmount, which sets and clears lock: mounted (so even a dry run touches the config briefly).

Refuses (exit non-zero, nothing changed) when: not root; pct missing; CT not stopped; config has any [...] section (snapshots, [pve:pending]); lock: set; template: 1 or protection: 1; HA-managed (ha-manager status); a replication job exists (pvesr list); rootfs is not a volume; any mpN or lxc.mount.entry (rootfs-only CTs: no shadowed files, df measures rootfs alone, pct mount cannot fail on another storage); new size >= current size; size not a positive integer.

Fit check after pct mount (df -B1 and df -i on the rootfs): used bytes * 1.1 <= N GiB * 0.93 (5 % root reserve + ~2 % ext4 metadata), and used inodes * 1.1 <= the new disk's inodes (N * 65536, mkfs.ext4 default ratio). On any error after pct mount the trap runs pct unmount; if that fails it stops and prints the manual cleanup (pct unmount, pct unlock), touching nothing else.

Steps (copy route, any storage):

1. pct set <id> --mp9 <storage>:<N>,mp=/.shrink-new - PVE allocates and formats; the script reads back mp9's volid and size=.
2. pct mount <id>; rsync -aHAX --numeric-ids --whole-file --sparse --one-file-system --exclude=/.shrink-new old rootfs -> new; pct unmount <id>. On rsync failure: unmount, then free the new volume explicitly - pct set --delete mp9 only moves it to unusedN, so the script then deletes the unusedK whose value is exactly the new volid (found by value, never by index).
3. Swap, under PVE's config flock (flock /run/lock/lxc/pve-config-<id>.lock): copy the config to /root/pct-shrink-<id>-<timestamp>.conf; rewrite the main section with awk (exact string compare, no regex on volids) into <conf>.tmp.<pid> and rename it, as PVE's file_set_contents does on pmxcfs; refuse if rootfs or mp9 changed since the copy: rootfs: gets the new volid with the old options and mp9's size=, the mp9: line goes, and unusedK: <old volid> is added at the first free K. No pct rescan: the script knows both volids and the size, so rescan's side effects (every orphan of the VMID added as unused, size=0 on pve-container < 6.1.9) are avoided.
4. Print the exact unusedK key and value of the old rootfs: start the CT, check it, then pct set <id> --delete unusedK. The script never deletes the old volume.

The in-place ZFS refquota shortcut is left out: one route for every storage is less code to get wrong, and the copy keeps the original until the user deletes it. chattr flags (+i, +a) are not copied by rsync; the script says so.

Tests: pytest runs the script with stub pct, df, rsync, flock, ha-manager, pvesr on PATH and a temp config dir (PCT_CONF_DIR override, default /etc/pve/lxc; the plan output prints the directory used). bats is not installed and CI only runs pytest. ShellCheck via the edit hook.

Out of scope

• Shrinking mpX volumes, and containers that have any mount point (script).
• Overwrite-in-place restore with a smaller disk.
• Restoring back to the original VMID (second backup/restore cycle).
• Running the node script from the TUI (it needs a root shell on the node).
• Moving backup=0 mount points to the new guest.

Steps

• cli.restore(rootfs_gb=...) adds --rootfs S:N; tests in test_cli.py.
• RestoreScreen: size field for lxc, refuse with overwrite, refuse <= used of a running guest; shrink confirm text with the warnings above; tests in test_app.py.
• scripts/pct-shrink-rootfs + tests/test_pct_shrink.py: each refusal, dry run changes no config, happy path (exact new config, unusedK at first free K with existing unused0), dir-style volid with / and ., rsync failure frees the new volume by value, unmount failure stops.
• README: key table row and a warning paragraph; script usage.
• Full uv run pytest, ruff, shellcheck green.

Open questions

• Should a shrink restore pass --unique 1 (new MACs)? Today's restore does not, it warns instead. Proposal: keep that, the warning already covers it.