User namespaces and rootless Docker

The most dangerous statement in container security is “the container runs as root”. Inside the container’s PID namespace, the process looks like UID 0. On the host filesystem, the same process is whatever UID the host maps it to. User namespaces are the mechanism that makes this mapping happen.

The mapping

flowchart LR
  subgraph Container["Inside the container"]
    C0[UID 0 root]
    C1[UID 1000 alice]
  end
  subgraph Host["On the host"]
    H0[UID 100000 unprivileged]
    H1[UID 101000 unprivileged]
  end
  C0 -. mapped via uid_map .-> H0
  C1 -. mapped via uid_map .-> H1

A user namespace remaps UIDs. Inside the namespace, the process sees the conventional 0–65535 UID space. On the host, the same process is some higher UID range. The kernel performs the mapping on every filesystem operation.

Default Linux user-namespace configuration in Docker (modern versions):

• The container’s UID 0 maps to a host UID in the dockremap/configured range (default: 100000–165535).
• The container’s UID 1000 maps to a host UID 100000 higher.

A process inside the container that thinks it is writing /etc/nginx/nginx.conf as root is actually writing to a host file that the host UID 100000 can write. If the file’s host UID is 0 (root-owned) and host mode is 600, the container cannot modify it.

Rootless Docker

Rootless Docker runs the entire Docker daemon as a non-root user. Combined with user namespaces for the daemon’s containers, the daemon has no path to host root even if the daemon itself is compromised.

To enable:

# One-time setup
dockerd-rootless-setuptool.sh check
dockerd-rootless-setuptool.sh install
# Run as a systemd user service
systemctl --user enable docker
systemctl --user start docker
# Verify
echo "DOCKER_HOST=unix:///run/user/$(id -u)/docker.sock""

cat /etc/subuid /etc/subgid

ps -o user,pid,comm -p $(pgrep -f dockerd-rootless)

Mapping without going full rootless

You can use user namespaces on a rootful daemon by setting --userns-remap=default in daemon.json. The daemon then maps container UID 0 to the host UID range configured for the dockremap user (the default user Docker creates for this purpose).

sudo tee /etc/docker/daemon.json <<'EOF'
{
"userns-remap": "default"
}
EOF
sudo systemctl restart docker

docker info --format 'root={{.DockerRootDir}}{{"\n"}}userns={{json .SecurityOptions}}'
ls -1d /var/lib/docker/*.* 2>/dev/null
getent passwd dockremap; grep '^dockremap:' /etc/subuid /etc/subgid

root=/var/lib/docker/231072.231072
userns=["name=seccomp,profile=builtin","name=userns"]
/var/lib/docker/231072.231072
dockremap:x:998:998::/home/dockremap:/usr/sbin/nologin
/etc/subuid:dockremap:231072:65536
/etc/subgid:dockremap:231072:65536

name=userns in SecurityOptions is the positive confirmation that remapping is active. On a host without it, DockerRootDir is plain /var/lib/docker and name=userns is absent — those two facts together distinguish “remapping is on” from “the data is gone” in under a second.

What stops working under remapping

The Docker documentation lists these as incompatible with user namespaces, and they fail at docker run time rather than silently:

--userns=host on an individual container opts it out of the mapping while the rest of the host keeps it. That is the escape hatch for the one legacy workload that cannot be remapped — and it is also a hole, so it belongs in a change record with a name against it, not in a script.

What to do in production

1. On shared hosts (CI runners, build hosts, developer laptops): enable rootless.
2. On production hosts where you control everything: evaluate rootless vs rootful + userns-remap.
3. Always pair user namespaces with capability dropping. Capabilities are useless without them.
4. Test that the workload behaves correctly under the mapping. Mount paths, file ownership, signals.
5. Document the choice and the rationale.

Knowledge check