Docker's user namespace remapping changes a basic assumption about container ownership. A process that sees UID 0 inside a container can map to an unprivileged subordinate UID on the host. This narrows the host authority of a container escape, but it also changes file ownership, volume access, and the meaning of host-side inspection.
What the remap does
The Docker daemon can start with --userns-remap or a userns-remap entry in daemon.json. In this mode, container UIDs and GIDs are translated to ranges assigned to a remap user. The daemon documentation describes the container root user as mapping to the first subordinate UID in the relevant /etc/subuid range, with later container IDs following that range.
The host therefore sees different numeric ownership from the process inside the container. A file that appears to be owned by root in the container may be owned by a high-numbered host UID. That is the intended protection: a process using container root does not automatically become host root.
Volumes are the hard part
The mapping does not apply only to the writable layer. Bind mounts and named volumes expose host files to the remapped namespace, and existing ownership may not grant the container process the access it expects. A service can start cleanly, then fail when it writes a log, rotates a cache file, or creates an upload directory.
Inventory every persistent path before the change. Record the current numeric UID and GID, not only the name. Check whether shared volumes are used by more than one service and whether an orchestration platform, backup agent, or host scanner expects a particular owner. Changing ownership to a high subordinate UID can break those readers.
The reverse case also deserves attention. A volume with permissive host permissions may remain useful to the container, but the host-side process that reads the same data now needs the remapped identity or an appropriate group mapping. Document that access path so a backup job does not fail after the next restart.
Check subordinate ranges
The host needs configured subordinate UID and GID ranges for the remap user. Confirm the ranges in /etc/subuid and /etc/subgid are present, stable, and not overlapping in a way that creates ownership confusion. Compare them with the daemon's chosen remap configuration and with other services that also use subordinate IDs.
A test host should create a container that writes a known file to a disposable bind mount. Inspect ownership inside and outside the container. Restart the daemon and repeat the test to confirm that the mapping is stable. Then test a read-only volume and a path that should be denied.
Do not treat the map as a full boundary
User namespace remapping reduces the consequence of some container-to-host transitions. It does not make every container safe. A container with excessive mounts, device access, or capabilities can still damage the resources it can reach. A privileged container is not made harmless by a remap setting that the daemon does not apply to it.
The host kernel, Docker daemon, and orchestration control plane remain part of the attack surface. Keep the Docker API off untrusted networks and limit who can create containers. Review images and run processes as non-root where the application allows it.
Change plan
- 1.
Inventory volumes, bind mounts, and host readers by numeric owner.
- 2.
Confirm subordinate UID and GID ranges.
- 3.
Test the daemon setting on a disposable host with a representative volume.
- 4.
Verify write, read, backup, and denial paths.
- 5.
Roll out during a maintenance window and keep the previous configuration ready.
The mapping provides its security benefit only when it is understood end to end. The operational risk comes from enabling the feature without testing the paths where names and numbers no longer agree.