Docker users and user namespaces
October 09, 2018 2 min read
After taking a break from DevOps for a few months and switching to other fields, I would always forget the details of how users within a docker container map to users on the host machine. This is a condensed recap of user mappings that should save me time, upon switching the contexts.
Suppose that you're running a docker container. Normally, you'd have a
docker group on your machine
that your user (e.g.
boris) belongs to.
Normally, uid/pids within the container are the same uids and pids as in your host system, cause containers and the host machine share the same kernel.
E.g. when you run a docker container, normally processes within the container run as root user with uid 0. Files, owned by those processes (e.g. through a mounted volume), are seen as owned by root on the host, they have uid of 0 as well.
If you run a process as a non-root user within the container (e.g. stock
postgres image does
gosu to uid 999 before running, on the host machine postgres-owned files will be owned by uid=999.
uids for non-system users normally start with 1000,
so if you're running some process within the docker container as uid 1001,
In a Dockerfile you can use
USER instruction to specify that some commands might need to be run under a
You can pass a
--user option to
docker run, e.g.
docker run -d --user 1001 ubuntu:latest sleep infinity,
and in that case process within your container process will run as user 1001. This option overrides the
USER command in your container.
Read more examples in this excellent posts by Marc Campbell.
Take note that examples, provided in the post, work on true Linux machines, but not on Mac OS, where
doesn't show docker processes, due to implementation details of docker machine on macs.
User namespaces and remapping
There's a mechanism in Linux kernel called user namespaces, which allows you to improve security of your containers.
Basically, you can remap a range of uids, used within a docker container, to regular users uids on your host machine, when configuring the docker daemon. Read more in the official documentation.
Written by Boris Burkov who lives in Moscow, Russia and Cambridge, UK, loves to take part in development of cutting-edge technologies, reflects on how the world works and admires the giants of the past. You can follow me on Telegram