Secure Docker Containers with Linux User Namespaces: A Practical Guide

Understanding Linux User Namespace

Linux user namespaces provide security isolation for running processes, including UID and GID, limiting their access to system resources while the processes remain unaware of these restrictions.

For containers, the best way to prevent privilege‑escalation attacks is to run applications with non‑root privileges. When an application must run as root inside a container, user namespaces map a regular host user to the container's root, granting root‑like capabilities inside the namespace but only ordinary user permissions on the host.

User Namespace User Mapping

Before enabling Docker daemon user namespaces, understand subordinate user/group IDs and their mappings, controlled by /etc/subuid and /etc/subgid. Example entries:

For subuid, a line such as nick:100000-165535 (65536 IDs) means user nick has 65,536 subordinate IDs that map to 0‑65535 inside a child user namespace. subgid works similarly.

By assigning a subordinate ID (e.g., 100000) to a container's user namespace and mapping it to UID 0, the container’s root user is confined to the permissions of the host’s nick user.

nick:100000:65536
dockeruser:165536:65536

Configure Docker daemon:

{
  "userns-remap": "dockeruser"
}

Alternatively, let Docker handle the mapping automatically:

{
  "userns-remap": "default"
}

Configuring Docker Daemon for User Isolation

Create or edit /etc/docker/daemon.json and add the userns‑remap setting, then restart Docker:

sudo touch /etc/docker/daemon.json

{
  "userns-remap": "default"
}

sudo systemctl restart docker.service

Verification steps:

Check that Docker created a dockremap user.

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

Observe a new directory 165536.165536 under /var/lib/docker with appropriate permissions.

UID Mapping Between Host and Container

Run a test container:

docker run -d --name sleepme ubuntu sleep infinity

Inside the container, UID 0 maps to host UID 165536 (a subordinate ID of dockremap ), giving the container root limited host permissions.

New Containers Create Their Own User Namespace

Before enabling user isolation, container processes share the host user namespace. After enabling, Docker creates a new user namespace for each container, granting root inside the container but restricting host access.

Accessing Files in a Volume

Create files owned by root, UID 165536, and user nick , then mount the directory as a volume and inspect access from the container. The container root can only read/write files owned by UID 165536 and the world‑writable test file.

docker run -it --name test -w=/testv -v $(pwd)/testv:/testv ubuntu

Disabling User Namespace for a Single Container

If Docker daemon has userns-remap enabled globally, you can disable it per container with --userns=host on docker container create, run, or exec.

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

In this mode, the process retains host root privileges and no new user namespace is created.

Known Issues

Sharing host PID or network namespace ( --pid=host or --network=host) is incompatible.

External storage drivers or volume plugins may not support user namespaces.

Using --privileged without --userns=host can cause conflicts.

Conclusion

Docker supports user namespaces and configuring them is straightforward. Enabling this feature improves security but introduces limitations for certain functionalities, requiring careful consideration of trade‑offs.