Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Docker Rootless Mode: Setup, Security Model, and Limitations

Running dockerd inside a user namespace removes the root daemon. What that buys, what it forbids, and the four prerequisites setup fails on.

~4 min readDocker
#Docker#Security#Containers
3D illustration of a user-namespace sandbox wrapping the Docker daemon inside an unprivileged host account

Quick Summary

Rootless mode runs the entire Docker stack — dockerd, containerd, the container runtime — inside a user namespace under your own unprivileged account. Nothing on the host runs as root, so a container escape lands in a namespace where the "root" user maps to a hard-to-use subordinate UID outside it. That single change removes the largest blast radius in a default Docker install: a root daemon with root-owned socket access.

The setup is three facts. The kernel must allow unprivileged user namespaces. The user needs a range of subordinate IDs in /etc/subuid and /etc/subgid (created by useradd for normal accounts, sometimes missing on minimal images or when the account was added by hand). And the tooling needs newuidmap/newgidmap from the uidmap package. With those in place, dockerd-rootless-setuptool.sh install creates a systemd user unit, and docker talks to unix://$XDG_RUNTIME_DIR/docker.sock instead of /var/run/docker.sock.

The limitations are real and mostly about privilege the namespace cannot have. Resource limits need cgroups v2 (a v1 host degrades to no CPU/memory limits), privileged containers and most --cap-add calls are refused, binding ports below 1024 requires an explicit sysctl or the rootlesskit driver, and host networking means the host network of the namespace rather than the machine. Network throughput through the default port driver is measurably lower than rootful.

Basic syntax and query signatures

bash
# Prerequisites (Debian/Ubuntu) sudo apt-get install -y uidmap dbus-user-session grep "$USER" /etc/subuid /etc/subgid # must show a range, e.g. user:100000:65536 sysctl kernel.unprivileged_userns_clone # Debian: must be 1 (or absent) sysctl kernel.apparmor_restrict_unprivileged_userns # Ubuntu 24.04: must be 0 or have a profile # Install as the current user, no sudo for the daemon itself dockerd-rootless-setuptool.sh install # Talk to it export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/docker.sock docker info | grep -i rootless # Keep the user daemon alive without an active login session sudo loginctl enable-linger "$USER" systemctl --user status docker

The setup script also installs a Docker CLI context, which is the cleaner way to switch than exporting variables.

bash
docker context ls docker context use rootless docker run --rm hello-world

rootlesskit is the wrapper that creates the namespace; its port driver decides how published ports reach the host.

bash
# Inspect and choose the port driver rootlesskit --version DOCKERD_ROOTLESS_ROOTLESSKIT_NET=pasta dockerd-rootless.sh --experimental docker info --format '{{.Driver}} {{.CgroupDriver}} {{.CgroupVersion}}'

Key comparison table

AspectRootfulRootless
Daemon userrootYour user
Socket/var/run/docker.sock (root:docker)$XDG_RUNTIME_DIR/docker.sock
Container root maps tohost rootsubordinate UID (e.g. 100999)
Privileged containersYesNo
Ports below 1024YesNeeds ip_unprivileged_port_start or driver config
Resource limitscgroups v1 or v2cgroups v2 required
Storage driveroverlay2overlay2 (kernel 5.11+) or fuse-overlayfs
Networkingkernel bridge directlybridge inside a netns, slirp4netns/pasta
NFS/CIFS volumesYesGenerally not (mount not permitted)
--net=hostHost networkNamespace's network
PerformanceBaselineLower throughput, higher syscall overhead
RequirementCheckFailure symptom
Subordinate IDsgrep $USER /etc/subuidnewuidmap: write to uid_map failed
uidmap packagecommand -v newuidmapcannot set up namespace
Unprivileged usernssysctl kernel.unprivileged_userns_cloneoperation not permitted at start
cgroups v2stat -fc %T /sys/fs/cgroup → cgroup2fs--memory silently ignored
XDG_RUNTIME_DIRecho $XDG_RUNTIME_DIRCannot connect to the daemon
Linger enabledloginctl show-user $USER -p LingerContainers stop after logout

Practical edge cases and deep dives

1. Setup fails on uid_map: the subuid range is missing

text
newuidmap: write to uid_map failed: Operation not permitted

This is almost always a missing subordinate ID range, not a kernel problem. Minimal cloud images and manually created accounts often skip it.

bash
sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 "$USER" # verify, then re-run the setup script grep "$USER" /etc/subuid /etc/subgid

On systems where /etc/subuid is managed by subuid from a directory service, the fix belongs there; adding a local line can be overwritten at the next login.

2. Publish a privileged port without root

bash
# Fails by default: cannot bind 80 inside the namespace docker run -d -p 80:80 nginx:alpine # docker: Error response from daemon: failed to expose ports: cannot expose privileged port 80 # Option A: allow the whole system to bind low ports for unprivileged users sudo sysctl net.ipv4.ip_unprivileged_port_start=0 # Option B: publish a high port and put a reverse proxy in front docker run -d -p 8080:80 nginx:alpine

Option A widens a host-wide policy for every process; option B keeps the change local to your proxy configuration. On a multi-user host, prefer B.

3. Resource limits silently do nothing on cgroups v1

bash
docker run --rm --memory=256m alpine free -m # shows host memory, not 256 MB

Rootless mode needs cgroup v2 for delegation. Check with docker info --format '{{.CgroupVersion}}'. On a v1 host, limits are accepted and ignored, which is worse than an error because a runaway container can take the machine down.

4. Storage driver: overlay on 5.11+, fuse-overlayfs below

Rootless overlay works natively from kernel 5.11 thanks to user-namespace overlay support. Older kernels fall back to fuse-overlayfs, which works but adds a userspace hop on every filesystem operation.

bash
docker info --format '{{.Driver}}' # overlay2 (native) # fuse-overlayfs (compatibility path, slower) sudo apt-get install -y fuse-overlayfs

If builds that take 40 seconds rootful take three minutes rootless, the driver is the first thing to check.

5. The socket path breaks every tool that hardcodes /var/run/docker.sock

Mounting the rootless socket into a container for a "Docker-in-Docker CI" trick does not grant root, but it does grant full control of your daemon — which can read your files through bind mounts. Treat the rootless socket as a credential.

bash
# Point compatible tools at it explicitly export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/docker.sock export TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/run/user/$(id -u)/docker.sock

For tools that cannot be configured, docker context use rootless helps only those that read the context.

6. Networking throughput and the port driver

The default slirp4netns driver terminates TCP in userspace, so throughput tops out well below line rate and ICMP behaves oddly. pasta (newer rootlesskit) is faster and handles more protocols.

bash
systemctl --user edit docker # [Service] # Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_NET=pasta" # Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_PORT_DRIVER=pasta" systemctl --user daemon-reload && systemctl --user restart docker

Host networking in rootless mode shares the namespace's network, so a container on --net=host and the daemon can reach each other, but the container sees the namespace's interfaces rather than the host's physical ones.

7. Migrating an existing rootful install

Stop the root daemon, move or re-pull images (they live under ~/.local/share/docker for rootless users), and keep the two apart. Volumes are not shared: /var/lib/docker/volumes belongs to root and is not readable through the namespace.

bash
sudo systemctl disable --now docker docker.socket dockerd-rootless-setuptool.sh install docker context use rootless docker volume ls # empty: re-create from backups or compose files

Plan the data migration as a copy through an intermediate export, not as a directory move. A rootless daemon that points at root-owned files will fail with permission errors that are easy to misread as corruption.

Common mistakes and runtime errors

Error / symptomCauseFix
newuidmap: write to uid_map failedNo subordinate ID rangeusermod --add-subuids/--add-subgids
operation not permitted starting the daemonUnprivileged userns disabledEnable the sysctl or an AppArmor profile
Cannot connect to the Docker daemonDOCKER_HOST unsetdocker context use rootless
Containers stop after logoutNo lingeringloginctl enable-linger $USER
--memory ignoredcgroups v1Use cgroup v2 host
cannot expose privileged portPorts below 1024High port + proxy, or sysctl
--privileged rejectedNot permitted by designRemove it; add specific capabilities
NFS volume mount failsMount not allowed in the namespaceBind-mount on the host, or --mount type=bind
Builds 3× slowerfuse-overlayfs fallbackKernel 5.11+, native overlay2
docker -v inside container emptySocket not mountedMount the rootless socket path
Volume data missing after migrationVolumes remain in /var/lib/dockerExport and restore explicitly

Try matching browser tools

All tools

Small utilities that fit Docker work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Docker guides

More in Docker

All Docker guides

The guides filed next to this one in Docker, in library order.