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 different uid.

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 ps 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.


Boris Burkov

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