userTransfer: rootless Docker ownership breaks when source/target subuid ranges differ (data-root keeps foreign sub-IDs, bind mounts get flattened)

[MagnaCapax]

Problem

A user moved with userTransfer.php can come out the other side with broken rootless Docker containers when the user's subordinate ID range (/etc/subuid, /etc/subgid) differs between the source and target hosts.

Observed in a production migration. The source user had subuid/subgid = 100000:65536; the target user (same username) had 165536:65536. After a complete transfer (31 passes plus the final volatile sync, with the user's Docker stopped on the source first):

• Inside the Docker data-root (~/.local/share/docker, synced by the final volatile pass): ownership kept the source's numeric sub-IDs (e.g. 100999, 100041, 100502). Those IDs have no name, so rsync keeps them as numbers. On the target they fall outside the user's range and inside another tenant's subordinate range. One of six containers then failed to start: lstat .../rootfs/overlayfs/<id>/app: permission denied.
• Outside the data-root, in directories the containers bind-mount from the home: the source had ~1,600 files owned by container sub-IDs, and the target ended up with 3. The rest were owned by the plain user. Inside the container those files appear root-owned, which breaks apps that run as a non-root container UID. Which post-transfer step flattened them is not yet traced. The candidates are the Normalising user permissions step (util/userPermissions.php, called from lib/userTransfer/postSetup.php) and the payload-ownership handling added for userTransfer: bulk data payload not chowned to target user on cross-username migration; userPermissions.php excludes payload, so data stays owned by the source uid #787.

Expected

Container-owned files keep the same container-relative ownership after a move. For every uid/gid inside the source user's subordinate range: target_id = id - source_range_start + target_range_start. This applies both inside the data-root and in the rest of the home. Files owned by the user itself map to the target user, as today.

Suggested fix (for review)

1. Before the final sync, read the source user's subuid/subgid start (remote) and the target user's (local).
2. After the final sync: for every path under the home whose uid/gid lies in the source range, chown -h it to the offset ID. Whichever post-transfer step flattens those files to the user must skip them.
3. Log how many files were remapped, and assert that no file under the home is left owned by an ID in another user's range.

Impact

This affects any Docker-using account moved between hosts whose subordinate ranges differ. Containers that write to bind mounts, or whose image layers contain non-root-owned paths, break or misbehave. Ownership also points at another tenant's ID range. Home-directory permissions stop access across tenants, but the files are still owned by the wrong IDs.

Related

#787 (closed) fixed data ownership when the username changes between hosts. This is a different case: the same username, but container-owned sub-IDs that need an offset instead of a flatten.

(Container IDs are relative. The ranges aren't.)

---

_{Tier-3 declared at filing: --why multi-file — GH#631 tier gate. Declared fix size: 90 lines vs 28-line body — size gate (operator directive 2026-07-29). Owner: scripts/lib/userTransfer/postSetup.php in MagnaCapax/PMSS — owner gate.}

[MagnaCapax]

Traced: the flattening is util/userPermissions.php, and it is not specific to migrations

The body left open which step flattened the bind-mounted files. I have now read it in source:

• scripts/util/userPermissions.php:240-258 builds find /home/<user> -mindepth 1. It prunes only ~/.local and ~/data, skips symlinks, and runs chown <uid>:<gid> on everything matching -not -uid <uid>.
• A file owned by a container sub-ID (for example host uid 100999 = container uid 999) is -not -uid <uid>, so it gets chowned to the user. The container then sees it as root-owned.
• ~/.local (the data-root) is pruned, which is why the store kept its numeric sub-IDs while the bind-mount directories next to it were flattened.

The same script has five callers:

Caller	When it runs
etc/seedbox/config/template.rc.local:44	every boot, for every user
lib/update/users/permissions.php (pmssUserRefreshPermissions)	every update.php user pass
lib/user/add/postProvision.php:48	after addUser
recreateUser.php:189	after recreateUser
lib/userTransfer.php:68, lib/userTransfer/postSetup.php:39	after a transfer

So this is wider than the subuid-offset problem. Any rootless Docker user with container-owned files bind-mounted from outside ~/.local and ~/data loses that ownership on every host reboot and every PMSS update, with no migration involved. On the migration path, the offset remap in the suggested fix is still needed. It also has to happen after this chown, or the chown has to leave sub-ID-owned paths alone.

The smallest change I see: make the find exclude paths whose uid/gid falls inside the user's own /etc/subuid and /etc/subgid range. Those are container-owned by definition, and they are exactly the files the user cannot chown back without rootlesskit/nsenter. Anything owned by an ID outside both the user's uid and the user's sub-range would still be normalised as today.

Manual repair on the affected account (for reference)

This was done once, by hand, with a before-image of every changed inode kept:

1. On the source, before flattening: a map of every home path outside the data-root whose owner was in the source sub-range. That came to 1,626 entries.
2. On the target: offset remap inside the data-root (id - 100000 + 165536 for ids in [100000, 165536)), 6,988 inodes. Then the map applied outside the data-root, 1,623 inodes (3 had been legitimately removed). There were 0 failures, and 0 ids were left in the source range afterwards.
3. After userDocker.php start, container state matched the source baseline (the same running/restarting split, no permission denied).

A second trap from the same move is covered in #962. PMSS's checkRootlessDocker watchdog restarts a user's Docker within 5 minutes of a manual stop, so a quiesced data-root does not stay quiesced unless --docker-enabled=false is set first.

(Ownership is a number until a namespace says otherwise.)

[MagnaCapax]

Commit 1a6aaf2 on main completes part (b): I updated the targeted userPermissions.php owner repair to preserve the account's /etc/subuid and /etc/subgid ranges, and to run chown -h through find -execdir. The new range and predicate tests pass. The development suite reports 3,193 tests, 2 unrelated existing failures, and 18 skips. The transfer remapping work described elsewhere in this issue remains open.

[MagnaCapax]

Status and design convergence with #964.

Part (b): flattening outside the data-root. The flattening step is the targeted owner repair in util/userPermissions.php. It runs at every boot and in every update pass, so a manual repair only lasts until the next of either. As of 1a6aaf2 the owner repair treats files owned by IDs inside the account's own /etc/subuid / /etc/subgid ranges as correctly owned (ADR 0071). Behaviour for accounts without subordinate ranges is unchanged.

Part (a) + #964: proposed shape. Run the transfer rsync inside a user namespace laid out the way rootless Docker lays out its own: ns 0 = the account, ns 1..N = the account's first subordinate block. The IDs on the wire are then container-relative. That is the same property the offset remap needs.

• Sender (source, runs as the account): --rsync-path='unshare --map-root-user --map-users=1:<src_start>:<count> --map-groups=1:<src_gstart>:<count> rsync'. This also covers userTransfer: source-side rsync runs as the user, so rootless-Docker files owned by sub-UIDs with owner-only modes are silently not copied #964: owner-only files owned by container IDs become readable, because the sender is namespace-root over them.
• Use explicit --map-users=1:<start>:<count>, not --map-auto. Per unshare(1), combining --map-auto with --map-root-user punches a hole at ns 0 instead of shifting the block. IDs would then come out one higher than Docker's layout, and the range's first ID would be unmapped. (This is from the man page and has not been exercised yet.)

Open design questions (receiver side):

1. Receiver in its own namespace with the target layout (--map-users=0:<uid>:1, 1:<dst_start>:<count>, set directly by root). With -o -g --numeric-ids this writes dst_start + (id - src_start) and needs no post-pass. Caveat: the local ssh transport would run inside that namespace too. Root's ssh files would then show the overflow owner, and ssh's ownership checks may reject them. This needs a test, or the transport must be kept outside the namespace.
2. Receiver as root plus an offset pass afterwards. This is simpler, but between write and remap the received files carry raw namespace IDs, i.e. low host IDs that belong to real system accounts or other accounts. Not acceptable unless the pass works on a staging tree that nothing else can reach.
3. Overflow ambiguity. Inside the namespace, any owner outside the account's IDs reads as the overflow ID (65534). That is the same number as container nobody (ns 65534). Source-side owner repair normally leaves no such files. The residual needs a decision: map into the range (Docker semantics) or flatten to the account.
4. --map-users / --map-groups need util-linux 2.38+. Older hosts need a newuidmap-based wrapper or the current path plus the offset pass.
5. After the final pass, assert that no file under the home is owned by an ID outside {uid} ∪ target range.
6. Ordering: userTransfer: rootless Docker data-root is copied live and Docker is never started on the target (stop on source before the final sync, start on target after) #962 (stop the account's Docker before the final sync, start it on the target) is a precondition for both.