How Linux User Namespaces Secure Docker Containers and How to Configure Them

What is a Linux User Namespace?

Linux user namespaces provide per‑process isolation of user and group IDs, allowing a process to believe it runs as root while the host sees it as an unprivileged user, which is essential for preventing privilege‑escalation attacks in containers.

User Mapping with subuid/subgid

Docker’s user namespace support relies on subordinate UID/GID ranges defined in /etc/subuid and /etc/subgid. Each line maps a host user to a range of IDs that appear as 0‑65535 inside the container.

nick:100000:65536
dockeruser:165536:65536

For example, the host user nick can have a subordinate ID 100000 mapped to UID 0 inside the container, giving the container root privileges that are limited on the host.

Enabling User Namespace in Docker

Configure Docker’s daemon JSON to enable user namespace remapping. You can either specify a dedicated user (e.g., dockeruser) or let Docker create a default mapping.

{
  "userns-remap": "dockeruser"
}

Or the simplified default:

{
  "userns-remap": "default"
}

After editing /etc/docker/daemon.json, restart Docker:

sudo systemctl restart docker.service

Verification Steps

Check that Docker created the dockremap user.

Confirm entries for dockremap appear in /etc/subuid and /etc/subgid.

Observe the new directory 165536.165536 under /var/lib/docker, which holds container files with the mapped UID.

UID Mapping Inside a Container

Run a container and inspect the UID mapping:

docker run -d --name sleepme ubuntu sleep infinity

Inside the container, the process runs as UID 0 (root), but on the host it corresponds to UID 165536, a subordinate ID with limited permissions.

File Access Tests

Create files with different owners (root, 165536, nick) on the host, mount them as a volume, and check access from the container. The container’s root can only read/write files owned by its mapped UID (165536) and world‑writable files, confirming the isolation.

Disabling User Namespace for a Single Container

If you need to run a container without user namespace isolation, use the --userns=host flag with docker run, docker container create, or docker container exec.

docker run -d --userns=host --name sleepme ubuntu sleep infinity

Known Issues

Sharing the host PID or network namespace (e.g., --pid=host or --network=host) is incompatible.

Some external storage drivers may not support user namespaces.

Using --privileged without --userns=host can cause unexpected behavior.

Conclusion

Docker fully supports Linux user namespaces, and enabling them improves container security by limiting host‑side privileges. However, certain features may break, so evaluate the trade‑offs and apply user namespace isolation where it best fits your workload.