95

Docker kind of always had a USER command to run a process as a specific user, but in general a lot of things had to run as ROOT.

I have seen a lot of images that use an ENTRYPOINT with gosu to de-elevate the process to run.

I'm still a bit confused about the need for gosu. Shouldn't USER be enough?

I know quite a bit has changed in terms of security with Docker 1.10, but I'm still not clear about the recommended way to run a process in a docker container.

Can someone explain when I would use gosu vs. USER?

EDIT:

The Docker best practice guide is not very clear: It says if the process can run without privileges, use USER, if you need sudo, you might want to use gosu. That is confusing because one can install all sorts of things as ROOT in the Dockerfile, then create a user and give it proper privileges, then finally switch to that user and run the CMD as that user. So why would we need sudo or gosu then?

3 Answers 3

77

Dockerfiles are for creating images. I see gosu as more useful as part of a container initialization when you can no longer change users between run commands in your Dockerfile.

After the image is created, something like gosu allows you to drop root permissions at the end of your entrypoint inside of a container. You may initially need root access to do some initialization steps (fixing uid's, host mounted volume permissions, etc). Then once initialized, you run the final service without root privileges and as pid 1 to handle signals cleanly.


Edit: Here's a simple example of using gosu in an image for docker and jenkins: https://github.com/bmitch3020/jenkins-docker

The entrypoint.sh looks up the gid of the /var/lib/docker.sock file and updates the gid of the docker user inside the container to match. This allows the image to be ported to other docker hosts where the gid on the host may differ. Changing the group requires root access inside the container. Had I used USER jenkins in the dockerfile, I would be stuck with the gid of the docker group as defined in the image which wouldn't work if it doesn't match that of the docker host it's running on. But root access can be dropped when running the app which is where gosu comes in.

At the end of the script, the exec call prevents the shell from forking gosu, and instead it replaces pid 1 with that process. Gosu in turn does the same, switching the uid and then exec'ing the jenkins process so that it takes over as pid 1. This allows signals to be handled correctly which would otherwise be ignored by a shell as pid 1.

10
  • When you run this and the gid of the runner is 0, the groupmod command in entrypoint.sh fails with groupmod: GID '0' already exists and the script keeps running. At that point, the jenkins user cannot run docker in the container. Any suggestions?
    – Mike D
    Apr 28, 2018 at 15:32
  • In this case, I would build two images. A base image where root is required and a jenkins image the pulls from the first image. You could do a multi-stage build to keep it all wrapped up in a single file. Then you could start the 2nd build with your user. This lets you work out permissions out earlier too. Feb 14, 2019 at 21:19
  • 1
    @MichaelNoe Not sure I'm following the multi-stage example. gosu is needed here because the permission and user id changes depend on runtime knowledge that you can't calculate at build time. The same Jenkins image may run on multiple hosts with different docker GID's on the host.
    – BMitch
    Feb 14, 2019 at 21:54
  • 1
    @JohanBoulé Does the readme on the gosu repo help? github.com/tianon/gosu
    – BMitch
    Jun 9, 2021 at 13:01
  • 1
    @Arber there's a -u option for exec. That works both ways, allowing you to be root in a non-root image, or allowing you to be a user in a root image. You could also configure the bashrc to run gosu on interactive logins. For the most part, I don't fix it, because the gosu is restricting the app, not the developer with exec access.
    – BMitch
    Apr 5 at 10:00
15

I am using gosu and entrypoint.sh because I want the user in the container to have the same UID as the user that created the container.

Docker Volumes and Permissions.

The purpose of the container I am creating is for development. I need to build for linux but I still want all the connivence of local (OS X) editing, tools, etc. My keeping the UIDs the same inside and outside the container it keeps the file ownership a lot more sane and prevents some errors (container user cannot edit files in mounted volume, etc)

3
  • 1
    I am not sure I follow here: gosu runs in the container; It runs as ROOT impersonating another user. This user had itself to be defined in the image. So how is this related to the user who 'created' the image? I can see that if you create the same user as a local user, and then use gosu to run as this user, this will avoid conflicts with a local mounted volume, but only because the user is the same name.
    – MrE
    Jun 20, 2016 at 23:01
  • 2
    @MrE: The user does not have to be defined in the image. It can be created with useradd inside the container on startup. When username, uid and gid are passed as environment variables into the container, they can be set to match the values on the host. Sep 6, 2016 at 9:01
  • 1
    I would add that this answer helps to avoid recursively changing permissions on volumes mounted from host (outside the container), whose user gets inherited by all the mounted files. This prevents the editing of files, as mentioned in the answer. – E.g. this happens when mounting Kubernetes's Pod volumes.hostPath on Minikube, inheriting UID & GID of the docker user from the Virtual Machine, on macOS or Windows; meehh); using gosu, in the ENTRYPOINT, helps with that. Nov 9, 2020 at 21:19
3

Advantage of using gosu is also signal handling. You may trap for instance SIGHUP for reloading the process as you would normally achieve via systemctl reload <process> or such.

2
  • 2
    I think this is the purpose of /sbin/tini
    – Mike D
    Apr 28, 2018 at 16:09
  • 2
    This is why gosu is better than su since it's doing an exec rather than a fork. But it misses the OP's question of why you'd want gosu over just setting the USER in the Dockerfile.
    – BMitch
    Dec 3, 2021 at 15:13

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.