User-namespace remapping

Map container root to an unprivileged host UID.

User-namespace remapping is the daemon feature that severs the root-in-container-equals-root-on-host equivalence for a normal, rooted daemon. With userns-remap enabled, the daemon maps the container’s UID range onto a high, unprivileged range on the host: container UID 0 becomes host UID 100000, container 1000 becomes 101000, and so on. Inside, processes see and behave as root; on the host they are a harmless unprivileged user with no power over anything they were not explicitly given.

# enable it (daemon.json: "userns-remap": "default"), restart, then observe the mapping
$ cat /etc/subuid
dockremap:100000:65536         # container UIDs 0-65535 map to host 100000-165535
$ docker run --rm alpine sleep 100 &
$ ps -o user,pid,cmd -C sleep   # inside it is "root"; on the host it is UID 100000
100000  4211  sleep 100

What it protects against

The concrete win shows up exactly where root-in-container is dangerous: a host bind mount. Without remapping, a rooted container writes host files as real root; with remapping, those same writes land as UID 100000, which cannot touch root-owned host files at all. A container breakout, likewise, escapes into an unprivileged host user rather than root — turning many would-be host takeovers into contained, low-privilege incidents.

# with userns-remap on: a "root" container can no longer write a root-owned host file
$ sudo touch /tmp/host/root-only && sudo chmod 600 /tmp/host/root-only
$ docker run --rm -v /tmp/host:/mnt alpine sh -c 'echo x > /mnt/root-only'
sh: can't create /mnt/root-only: Permission denied      # remapped UID has no rights—good

The tradeoffs to plan for

Remapping is not free. Existing named volumes and bind mounts may need ownership adjusted to the mapped range, some features are incompatible (sharing certain host namespaces, a few storage setups), and every container on the daemon shares the mapping. It is enabled daemon-wide, so test it against your workloads first. Where the daemon-wide switch is too coarse, rootless mode achieves the same UID-mapping benefit per user instead.