2.3.1.6 Kernel User Namespace

The kernel user namespace allows a process inside a container to appear to run as root within its own namespace, while actually mapping to an unprivileged, non-root user ID on the host — narrowing what a compromised container process could do even if it managed to act as root within its own isolated view.

The Mapping Between Container and Host User IDs

A user namespace defines a mapping between user and group IDs as seen inside the namespace and the corresponding IDs as seen on the host. A process can be UID 0 (root) inside its container while actually being an unprivileged UID on the host.

docker run --userns-remap=default alpine id

Run with user namespace remapping enabled, this might report UID 0 inside the container while the corresponding host-level process runs as a much higher, unprivileged UID.

Why This Matters for Security

Without user namespace remapping, a container process running as root inside its namespace is, by default, also UID 0 on the host — meaning a successful container escape would grant the attacker actual root privileges on the host. With remapping enabled, the same escape would only grant the privileges of an ordinary, unprivileged host user.

docker run --userns-remap=default --rm alpine sh -c "id; cat /etc/shadow"

Even if a container believes it is running as root, with remapping enabled it lacks the actual host-level privileges that would be needed to read a file like /etc/shadow on the host outside the container's mapped filesystem.

Configuring the Daemon for User Namespace Remapping

User namespace remapping is typically configured at the daemon level, defining the range of host UIDs that container UIDs map into, applied consistently across every container the daemon manages unless explicitly overridden.

{
  "userns-remap": "default"
}

This daemon configuration enables remapping using an automatically managed range of UIDs reserved specifically for this purpose.

Tradeoffs of User Namespace Remapping

Enabling user namespace remapping can interact awkwardly with volumes and bind mounts, since file ownership as seen by the container's remapped UIDs may not match what is expected on the host filesystem, which is part of why it is not always enabled by default despite its security benefit.

Why User Namespace Isolation Matters

User namespace remapping is one of the more impactful security hardening measures available for container isolation, specifically because it limits the consequences of the most severe kind of failure — a successful escape from container isolation into the host.