User Namespace Remapping, UID/GID Mapping, Non-Root Images, Filesystem Ownership, and Least Privilege: Concepts, Architecture, and Mental Model

1. The practical problem: “non-root” is not one identity

Dockerfiles, containers, user namespaces, and host files all use the word “user,” but Linux ultimately authorizes filesystem access with numeric UIDs, GIDs, supplementary groups, capabilities, ACLs, and security policy. A container may display the username app while the host sees only UID 10001—or a remapped high-number UID such as 231073.

The operational goal is therefore not “make the prompt stop saying permission denied.” It is to establish a traceable identity contract: which numeric identity the process has, how that identity maps to the host, which path it must write, and which paths it must not write.

2. Mental model: image identity → runtime identity → optional namespace translation → inode check

USER in a Dockerfile writes a default user into the image config. docker run --user or Compose user: can override it at runtime. The resulting process has numeric UID/GID values inside its container namespace. If user namespaces are disabled, those numeric IDs exist directly in the initial host user namespace. If userns-remap or rootless mode is active, Linux translates them into other host IDs before the kernel evaluates host filesystem ownership.

A bind mount does not magically “belong to the container.” The underlying host inode still has an owner, group, mode bits, optional ACLs, and possibly SELinux/AppArmor policy. Those checks happen after any namespace translation.

flowchart TD
  A[Dockerfile USER / image config] --> B[Runtime --user / Compose user override]
  B --> C[Container numeric UID:GID + supplementary groups]
  C --> D{User namespace?}
  D -->|No| E[Same numeric IDs in initial host user namespace]
  D -->|userns-remap| F[Container IDs translated through remap subuid/subgid]
  D -->|rootless| G[UID 0 -> host user; other IDs -> subordinate range]
  E --> H[Bind/volume inode ownership + mode/ACL/LSM checks]
  F --> H
  G --> H
  H --> I[Read/write allowed or denied]
            

3. Names are labels; numeric IDs are the durable evidence

4. Three mapping models you must keep separate

Ordinary rootful daemon without userns-remap: container UID 10001 is host UID 10001 for host filesystem checks.

Rootful daemon with userns-remap: container UID 0 maps to the first subordinate UID assigned to the remap user; container UID n maps to subordinate-start + n. The daemon itself still runs as root.

Rootless Docker: container UID 0 maps to the host UID of the user running rootless Docker. Container IDs ≥1 map into that user’s subordinate range using Docker’s documented offset rule. Both daemon and containers run without host-root privilege.

5. Read-only baseline inspection

docker version
docker context show
docker info --format 'Security={{json .SecurityOptions}} Root={{.DockerRootDir}}'

# Image configured identity (read-only)
docker image inspect alpine:3.22.1 --format 'User={{json .Config.User}}' 2>/dev/null || true

# Host identity/ranges on Linux
id
cat /etc/subuid 2>/dev/null | head
cat /etc/subgid 2>/dev/null | head

Do not infer daemon mode from a context name. docker info security options plus socket/data-root evidence are stronger proof.

6. Dockerfile USER and COPY --chown are different controls

USER chooses the default identity for later build instructions that honor it and, critically, the default runtime process. COPY --chown sets ownership on files added to the image. They solve different problems: one controls process identity; the other prepares filesystem state.

Docker resolves named --chown values through the image’s /etc/passwd and /etc/group. Numeric IDs avoid name lookup and are useful when you need an explicit cross-image contract.

7. DevOps contract: identity must survive rebuild, replacement, and restore

A reproducible deployment records at least: image digest, configured runtime user, any runtime override, writable paths, volume/bind ownership contract, user-namespace mode, and the expected numeric IDs. If a restored volume suddenly needs root or world-write access, that is evidence that the identity contract was never captured or was changed.

Knowledge check

Official references and version notes

• User namespace remapping — current prerequisites, mapping behavior, daemon configuration, limitations, and migration cautions.
• Rootless UID/GID mapping — precise difference between userns-remap and rootless host-ID translation.
• Rootless mode — daemon-level non-root execution and subordinate-ID prerequisites.
• Dockerfile reference — USER and COPY --chown semantics, including numeric versus name lookup.
• Compose services reference — service user override and user namespace configuration surface.
• Bind mounts — host-path ownership, read/write authority, and daemon-host path semantics.
• Volumes — Docker-managed persistent storage and container mount behavior.
• Docker Engine 29 release notes — current Engine baseline and user-namespace-related fixes/changes.