dumb-init

dumb-init is a simple process supervisor and init system designed to run as PID 1 inside minimal container environments (such as Docker). It is deployed as a small, statically-linked binary written in C.

Lightweight containers have popularized the idea of running a single process or service without normal init systems like systemd or sysvinit. However, omitting an init system often leads to incorrect handling of processes and signals, and can result in problems such as containers which can't be gracefully stopped, or leaking containers which should have been destroyed.

dumb-init

dumb-init

Why you need an init system

Normally, when you launch a Docker container, the process you're executing becomes PID 1, giving it the quirks and responsibilities that come with being the init system for the container.

There are two common issues this presents:

1. In most cases, signals won't be handled properly.

The Linux kernel applies special signal handling to processes which run as PID 1.

When processes are sent a signal on a normal Linux system, the kernel will first check for any custom handlers the process has registered for that signal, and otherwise fall back to default behavior (for example, killing the process on

SIGTERM

However, if the process receiving the signal is PID 1, it gets special treatment by the kernel; if it hasn't registered a handler for the signal, the kernel won't fall back to default behavior, and nothing happens. In other words, if your process doesn't explicitly handle these signals, sending it

SIGTERM

A common example is CI jobs that do

docker run my-container script

SIGTERM

docker run

docker run

1. Orphaned zombie processes aren't properly reaped.

A process becomes a zombie when it exits, and remains a zombie until its parent calls some variation of the

wait()

wait()

If a parent exits before its child, the child is "orphaned", and is re-parented under PID 1. The init system is thus responsible for

wait()

Of course, most processes won't

wait()

What

dumb-init

does

dumb-init

Since your actual process is no longer PID 1, when it receives signals from

dumb-init

dumb-init

Session behavior

In its default mode,

dumb-init

This can actually be useful outside of Docker containers in regular process supervisors like daemontools or supervisord for supervising shell scripts. Normally, a signal like

SIGTERM

#!/usr/bin/dumb-init /bin/sh
my-web-server &  # launch a process in the background
my-other-server  # launch another process in the foreground

Ordinarily, a

SIGTERM

If you'd like for signals to only be sent to the direct child, you can run with the

--single-child

DUMB_INIT_SETSID=0

dumb-init

dumb-init
dumb-init echo 'oh, hi'

Signal rewriting

dumb-init allows rewriting incoming signals before proxying them. This is useful in cases where you have a Docker supervisor (like Mesos or Kubernetes) which always sends a standard signal (e.g. SIGTERM). Some apps require a different stop signal in order to do graceful cleanup.

For example, to rewrite the signal SIGTERM (number 15) to SIGQUIT (number 3), just add

--rewrite 15:3

To drop a signal entirely, you can rewrite it to the special number

0

Signal rewriting special case

When running in setsid mode, it is not sufficient to forward

SIGTSTP

SIGTTIN

SIGTTOU

SIGSTOP

One caveat with this feature: for job control signals (

SIGTSTP

SIGTTIN

SIGTTOU

Installing inside Docker containers

You have a few options for using

dumb-init

Option 1: Installing from your distro's package repositories (Debian, Ubuntu, etc.)

Many popular Linux distributions (including Debian (since

stretch

bionic

On Debian-based distributions, you can run

apt install dumb-init

Note: Most distro-provided versions of dumb-init are not statically-linked, unlike the versions we provide (see the other options below). This is normally perfectly fine, but means that these versions of dumb-init generally won't work when copied to other Linux distros, unlike the statically-linked versions we provide.

Option 2: Installing via an internal apt server (Debian/Ubuntu)

If you have an internal apt server, uploading the

.deb

dumb-init

apt install dumb-init

Debian packages are available from the GitHub Releases tab, or you can run

make builddeb

Option 3: Installing the

.deb

package manually (Debian/Ubuntu)

If you don't have an internal apt server, you can use

dpkg -i

.deb

.deb

wget

One possibility is with the following commands in your Dockerfile:

RUN wget https://github.com/Yelp/dumb-init/releases/download/v1.2.5/dumb-init_1.2.5_amd64.deb
RUN dpkg -i dumb-init_*.deb

Option 4: Downloading the binary directly

Since dumb-init is released as a statically-linked binary, you can usually just plop it into your images. Here's an example of doing that in a Dockerfile:

RUN wget -O /usr/local/bin/dumb-init https://github.com/Yelp/dumb-init/releases/download/v1.2.5/dumb-init_1.2.5_x86_64
RUN chmod +x /usr/local/bin/dumb-init

Option 5: Installing from PyPI

Though

dumb-init

pip

apt-get install gcc

pip install dumb-init

As of 1.2.0, the package at PyPI is available as a pre-built wheel archive and does not need to be compiled on common Linux distributions.

Usage

Once installed inside your Docker container, simply prefix your commands with

dumb-init

Within a Dockerfile, it's a good practice to use dumb-init as your container's entrypoint. An "entrypoint" is a partial command that gets prepended to your

CMD

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

or if you use --rewrite or other cli flags
ENTRYPOINT ["dumb-init", "--rewrite", "2:3", "--"]
CMD ["/my/script", "--with", "--args"]

If you declare an entrypoint in a base image, any images that descend from it don't need to also declare dumb-init. They can just set a

CMD

For interactive one-off usage, you can just prepend it manually:

$ docker run my_container dumb-init python -c 'while True: pass'

Running this same command without

dumb-init

SIGKILL

dumb-init

SIGTERM

It's important that you use the JSON syntax for

CMD

ENTRYPOINT

Using a shell for pre-start hooks

Often containers want to do some pre-start work which can't be done during build time. For example, you might want to template out some config files based on environment variables.

The best way to integrate that with dumb-init is like this:

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

By still using dumb-init as the entrypoint, you always have a proper init system in place.

The

exec

Building dumb-init

Building the dumb-init binary requires a working compiler and libc headers and defaults to glibc.

$ make

Building with musl

Statically compiled dumb-init is over 700KB due to glibc, but musl is now an option. On Debian/Ubuntu

apt-get install musl-tools

$ CC=musl-gcc make

When statically compiled with musl the binary size is around 20KB.

Building the Debian package

We use the standard Debian conventions for specifying build dependencies (look in

debian/control

apt-get install
build-essential devscripts equivs

sudo mk-build-deps -i --remove

make builddeb

If you prefer an automated Debian package build using Docker, just run

make
builddeb-docker

See also

• Docker and the PID 1 zombie reaping problem (Phusion Blog)
• Trapping signals in Docker containers (@gchudnov)
• tini, an alternative to dumb-init
• pid1, an alternative to dumb-init, written in Haskell