This is a simple tool grown out of the simple fact that su
and sudo
have very strange and often annoying TTY and signal-forwarding behavior. They're also somewhat complex to setup and use (especially in the case of sudo
), which allows for a great deal of expressivity, but falls flat if all you need is "run this specific application as this specific user and get out of the pipeline".
The core of how gosu
works is stolen directly from how Docker/libcontainer itself starts an application inside a container (and in fact, is using the /etc/passwd
processing code directly from libcontainer's codebase).
$ gosu
Usage: ./gosu user-spec command [args]
eg: ./gosu cyrax13 bash
./gosu nobody:root bash -c 'whoami && id'
./gosu 1000:1 id
./gosu version: 1.17.5 (go1.22.7 on linux/amd64; gc)
Once the user/group is processed, we switch to that user, then we exec
the specified process and gosu
itself is no longer resident or involved in the process lifecycle at all. This avoids all the issues of signal passing and TTY, and punts them to the process invoking gosu
and the process being invoked by gosu
, where they belong.
The core use case for gosu
is to step down from root
to a non-privileged user during container startup (specifically in the ENTRYPOINT
, usually).
Uses of gosu
beyond that could very well suffer from vulnerabilities such as CVE-2016-2779 (from which the Docker use case naturally shields us); see tianon/gosu#37
for some discussion around this point.
High-level steps:
- download
gosu-$(dpkg --print-architecture | awk -F- '{ print $NF }')
asgosu
- download
gosu-$(dpkg --print-architecture | awk -F- '{ print $NF }').asc
asgosu.asc
- fetch my public key (to verify your download):
gpg --batch --keyserver hkps:https://keys.openpgp.org --recv-keys F4E743F8FFCB228B84812232E2E4EAF4164FF293
gpg --batch --verify gosu.asc gosu
chmod +x gosu
For explicit Dockerfile
instructions, see INSTALL.md
.
$ docker run -it --rm ubuntu:trusty su -c 'exec ps aux'
USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND
root 1 0.0 0.0 46636 2688 ? Ss+ 02:22 0:00 su -c exec ps a
root 6 0.0 0.0 15576 2220 ? Rs 02:22 0:00 ps aux
$ docker run -it --rm ubuntu:trusty sudo ps aux
USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND
root 1 3.0 0.0 46020 3144 ? Ss+ 02:22 0:00 sudo ps aux
root 7 0.0 0.0 15576 2172 ? R+ 02:22 0:00 ps aux
$ docker run -it --rm -v $PWD/gosu-amd64:/usr/local/bin/gosu:ro ubuntu:trusty gosu root ps aux
USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND
root 1 0.0 0.0 7140 768 ? Rs+ 02:22 0:00 ps aux
Additionally, due to the fact that gosu
is using Docker's own code for processing these user:group
, it has exact 1:1 parity with Docker's own --user
flag.
If you're curious about the edge cases that gosu
handles, see Dockerfile.test
for the "test suite" (and the associated test.sh
script that wraps this up for testing arbitrary binaries).
(Note that sudo
has different goals from this project, and it is not intended to be a sudo
replacement; for example, see this Stack Overflow answer for a short explanation of why sudo
does fork
+exec
instead of just exec
.)
As mentioned in INSTALL.md
, su-exec
is a very minimal re-write of gosu
in C, making for a much smaller binary, and is available in the main
Alpine package repository.
With the --userspec
flag, chroot
can provide similar benefits/behavior:
$ docker run -it --rm ubuntu:trusty chroot --userspec=nobody / ps aux
USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND
nobody 1 5.0 0.0 7136 756 ? Rs+ 17:04 0:00 ps aux
Available in newer util-linux
(>= 2.32.1-0.2
, in Debian; https://manpages.debian.org/buster/util-linux/setpriv.1.en.html):
$ docker run -it --rm buildpack-deps:buster-scm setpriv --reuid=nobody --regid=nogroup --init-groups ps faux
USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND
nobody 1 5.0 0.0 9592 1252 pts/0 RNs+ 23:21 0:00 ps faux
I'm not terribly familiar with them, but a few other alternatives I'm aware of include:
chpst
(part ofrunit
)