Back to Blog
Articles

Switch Container Users with gosu

Use gosu in an entrypoint and inspect signal delivery and terminal boundaries.

A container entrypoint may need root privileges to prepare a directory or fix ownership of a mounted volume. The application itself can then run under an ordinary UID and GID. gosu handles that handoff and directly executes the target process.

Common problems

File ownership and interactive terminals

Files written by root into a host-mounted directory may remain root-owned on the host. Running the workload under the intended UID and GID reduces the need to repair ownership later.

An entrypoint that starts an interactive program through sudo also needs to account for its process tree and terminal handling. These details depend on configuration; switching users alone does not guarantee identical TTY behavior.

Signal delivery

When a container stops, SIGTERM reaches its main process. If the entrypoint leaves a parent process running, the application receives the signal only if that parent forwards it. With exec gosu user server, the shell is replaced by the server, so the application becomes the main process.

What is gosu?

The gosu project describes how it resolves the requested user and group, changes identity, and then executes the command. It does not remain as a separate signal-forwarding process.

Example entrypoint

The Dockerfile installs gosu and sets an entrypoint:

Dockerfile
# Base the image on an existing base image
FROM some_base_image:latest

WORKDIR /app

# Install gosu
RUN apt-get update && apt-get install -y gosu && rm -rf /var/lib/apt/lists/*

# Prepare the entrypoint script
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

ENTRYPOINT ["/entrypoint.sh"]
CMD ["default_command"]

The entrypoint can create a user from the requested UID and GID before starting the workload:

bash
#!/bin/bash
# Check if USER_ID and GROUP_ID environment variables are set
if [ ! -z "$USER_ID" ] && [ ! -z "$GROUP_ID" ]; then
    # Create user group and user
    groupadd -g "$GROUP_ID" usergroup
    useradd -u "$USER_ID" -g usergroup -m user
    # Use gosu to execute the command
    exec gosu user "$@"
else
    exec "$@"
fi

The example illustrates process handoff. In a real image, validate the UID and GID values and align mounted-directory permissions with the image's base system.

Security considerations

The gosu TTY discussion concerns keeping a terminal across a privilege boundary. A lower-privilege process may inherit an open terminal. Where TIOCSTI is available, it can inject characters into that terminal's input queue. The following demonstration injects id followed by a newline:

c
#include <unistd.h>
#include <sys/ioctl.h>
#include <stdio.h>

int main()
{
    for (char *cmd = "id\n"; *cmd; cmd++) {
        if (ioctl(STDIN_FILENO, TIOCSTI, cmd)) {
            fprintf(stderr, "ioctl failed\n");
            return 1;
        }
    }
    return 0;
}

This call simulates typed input without an explicit user action. Its impact depends on the terminal, kernel settings, and process permissions. Containers do not always receive a new TTY: review whether -t is used, which process owns the terminal, and which file descriptors cross the boundary. The project recommends gosu chiefly for the root-to-user handoff at container startup; interactive privilege changes need separate TTY review.