dumb-init

dumb-init is a lightweight, statically-linked process supervisor and init system written in C. It is designed to run as PID 1 inside minimal container environments (like Docker) to solve two primary issues:

1. Signal Handling: Prevents processes from ignoring signals (like SIGTERM) because they are running as PID 1, which requires explicit signal handlers to act on them.
2. Zombie Process Reaping: Ensures that orphaned processes are properly reaped by acting as a proper init system, preventing the accumulation of defunct/zombie processes in the process table.

Standard Build

Requires a working compiler and libc headers (defaults to glibc):

make

Build with musl (Smaller binary size)

To produce a much smaller binary (~20KB vs ~700KB), use musl-gcc:

CC=musl-gcc make

Build Debian packages

To build .deb packages, install dependencies via apt-get install build-essential devscripts equivs and then use:

sudo mk-build-deps -i --remove
make builddeb

Or use Docker for an automated build:

make builddeb-docker

The recommended way to use dumb-init is to set it as your container's ENTRYPOINT. This ensures it acts as PID 1 and manages your CMD.

CRITICAL: You must use the JSON syntax for ENTRYPOINT and CMD. If you use shell syntax, Docker will invoke a shell as PID 1 instead of dumb-init.

Standard Usage

ENTRYPOINT ["/usr/bin/dumb-init", "--"]
CMD ["/my/script", "--with", "--args"]

Using shell pre-start hooks

If you need to run setup logic (like templating configs) before starting your server, use exec within a bash -c command to ensure the shell is replaced by your application process:

ENTRYPOINT ["/usr/bin/dumb-init", "--"]
CMD ["bash", "-c", "do-some-pre-start-thing && exec my-server"]

# Recommended pattern
ENTRYPOINT ["/usr/bin/dumb-init", "--"]
CMD ["/my/script", "--with", "--args"]

By default, dumb-init establishes a session rooted at the child process and sends signals to the entire process group. This is useful for shell scripts that spawn background processes.

To change this behavior so that signals are only sent to the direct child process, use one of the following:

• Use the --single-child CLI argument.
• Set the environment variable DUMB_INIT_SETSID=0.

You can rewrite incoming signals before they are proxied to your application. This is useful if your application requires a specific signal (e.g., SIGQUIT) for graceful shutdowns, but your orchestrator (like Kubernetes) only sends SIGTERM.

• To rewrite a signal: Use the --rewrite <original>:<new> flag. For example, to rewrite SIGTERM (15) to SIGQUIT (3), use --rewrite 15:3.
• To drop a signal: Rewrite it to the special number 0.

Note on Job Control Signals: For SIGTSTP, SIGTTIN, and SIGTTOU, dumb-init sets default rewrites to SIGSTOP. Additionally, dumb-init will always suspend itself upon receiving these signals, even if you attempt to rewrite them.