docker
Add/clarify how subuids and subgids are mapped in rootless docker compared to userns-remap mode
Is this a docs issue?
- [x] My issue is about the documentation content or website
Type of issue
Other
Description
The documentation page for rootless docker has a couple of paragraphs that discuss user/group ID mapping.
Rootless mode executes the Docker daemon and containers inside a user namespace. This is similar to userns-remap mode, except that with userns-remap mode, the daemon itself is running with root privileges, whereas in rootless mode, both the daemon and the container are running without root privileges.
The linked userns-remap documentation explains how UIDs within the container get mapped to subuids
This means that testuser is assigned a subordinate user ID range of 231072 and the next 65536 integers in sequence. UID 231072 is mapped within the namespace (within the container, in this case) as UID 0 (root). UID 231073 is mapped as UID 1, and so forth. If a process attempts to escalate privilege outside of the namespace, the process is running as an unprivileged high-number UID on the host, which does not even map to a real user. This means the process has no privileges on the host system at all.
It explains that UID 0 in the container gets mapped to the first subordinate UID specified in /etc/subuid, but this is only true for userns-remap. It is not true for rootless Docker.
In rootless mode, the mapping looks like:
| uid (container) | subuid (host) | notes |
|---|---|---|
| 0 (root) | $(id -u) (e.g. 100:john) |
container's root maps to the actual UID of the user running the rootless Docker service |
| 1 | 165536 (subuid + 0) |
/etc/subuid: john:165536:100000 -- so 165536 is the first sub uid |
| 2 | 165537 (subuid + 1) |
|
| n | subuid + n - 1 |
This difference is important when attempting to set file permissions on the host to grant a non-root user in the container permissions to read or write mounted files or folders
The mapping of 0 (root) to $UID (and not the first subuid) is documented in several issues, but it is not easy to locate. The clearest documentation of this behavior is https://github.com/moby/moby/issues/42134#issuecomment-797335148
tagging @AkihiroSuda and @thaJeztah as this relates to a number of open issues regarding permissions and bind mounts in rootless containers.
Location
https://docs.docker.com/engine/security/rootless/
Suggestion
Include the above or similar table in the ID mapping section of the rootless Docker docs.
