Processes, signals, and PID 1 · Docker & Containers

Every container has a PID 1. It is the process that the OCI runtime invokes via execve(2). If that process does not handle signals correctly, the container cannot be stopped gracefully.

This is the root cause of “container takes 10 seconds to stop.” The default --stop-timeout is 10 seconds. If PID 1 ignores SIGTERM, docker stop waits the full timeout before sending SIGKILL.

The special semantics of PID 1

In Linux, when the kernel delivers a signal whose default action is to terminate the process, PID 1 is exempt. PID 1 only acts on signals that have an installed handler.

This is a feature for the system init process. The kernel assumes that PID 1 knows what it is doing and only acts when PID 1 chooses to. For container workloads, this feature becomes a footgun: most workloads do not know that they are PID 1 and do not install handlers.

sequenceDiagram
  participant D as docker stop
  participant K as Kernel
  participant PID1 as Container PID 1
  participant App as Application
  D->>K: send SIGTERM to PID 1
  alt PID 1 has a handler
    K->>PID1: deliver SIGTERM
    PID1->>App: forward or handle
    App-->>PID1: exit
    PID1-->>K: exit 0
  else PID 1 has no handler (e.g. shell)
    K->>PID1: ignore (default for PID 1)
    Note over K: wait --stop-timeout
    D->>K: timeout reached
    D->>K: send SIGKILL to PID 1
    K->>PID1: deliver SIGKILL
    PID1-->>K: killed (no cleanup)
  end

Why PID 1 is exempt from default-signal termination

The kernel’s signal handling has the rule: “if a signal has no handler installed, take the default action.” The default action for SIGTERM is to terminate the process.

The init process of a PID namespace is exempt from that rule. There is no magic no-op handler involved: the kernel’s delivery path checks, for every signal aimed at a namespace init, whether that process has installed a handler for it. If it has not, the signal is discarded before delivery. Nothing is queued, nothing is pending, and the sender gets a successful return from kill(2) — so from the outside the signal looks sent.

Two signals are carved out of the exemption: SIGKILL and SIGSTOP cannot be handled, blocked or ignored by anything, so they still work. That asymmetry is precisely why docker stop appears to do nothing for ten seconds and then works instantly.

The rule also depends on where the signal came from. A signal sent from inside the namespace to its own PID 1 is discarded if there is no handler. A signal sent from an ancestor namespace — which is what docker stop does, from the host — is treated the same way. Either path, no handler means no delivery.

This is why kill 1 (without -9) inside a container does nothing, and why a shell that does not trap SIGTERM silently drops the signal.

The single commonest cause: a shell-form `CMD`

Every stop takes exactly ten seconds, and it is not the application

Deploys are slow. Stopping the service takes ten seconds, every time, on every host. It is always ten seconds — never nine, never eleven. The application team is asked to speed up shutdown; they profile it and find their shutdown path runs in 40 ms. Nobody can reproduce it locally, because locally people press Ctrl-C, which sends SIGINT to the whole foreground process group rather than SIGTERM to PID 1.

The Dockerfile ends like this:

CMD python3 /app/server.py

That is the shell form. Docker wraps it, so the container’s PID 1 is not python3 — it is /bin/sh -c "python3 /app/server.py". The shell has no SIGTERM handler, it is PID 1, so the exemption above applies and the signal is discarded. The shell never forwards anything to python3, which never learns it is being shut down. Ten seconds later docker stop gives up and sends SIGKILL, which nothing can ignore, and both processes die where they stand.

Why the first diagnosis is wrong. “Ten seconds” is read as “the application is slow to shut down”, and every subsequent action — profiling the app, raising --stop-timeout to give it more room, adding a shutdown hook — is aimed at a process that is not receiving the signal in the first place. Raising --stop-timeout to 30 makes the deploy take thirty seconds.

What it costs. This is not only a slow deploy. SIGKILL means no connection draining, no flush of buffered writes, no clean database disconnect, and for anything with a write-ahead log or an in-memory buffer, it means the recovery path runs on the next start. A queue consumer loses its in-flight message. The tell is that the damage shows up as “occasional corruption after deploys” months before anyone connects it to the shutdown path.

The exact tell. .Path is /bin/sh and .Args starts with -c. That is the whole diagnosis, and it takes one command.

Read-only / Safeis PID 1 a shell?— Compare the two. A container whose Path is /bin/sh with a -c argument cannot receive SIGTERM, no matter what the application does.

CONTAINER=web
docker inspect --format 'Path:  {{.Path}}{{"\n"}}Args:  {{json .Args}}' "$CONTAINER"
PID=$(docker inspect --format '{{.State.Pid}}' "$CONTAINER")
tr '\0' ' ' < "/proc/$PID/cmdline"; echo

Path:  /bin/sh
Args:  ["-c","python3 /app/server.py"]
/bin/sh -c python3 /app/server.py

Illustrative output

A healthy container looks like this instead — .Path is the application itself, and /proc/<pid>/cmdline agrees:

Path:  python3
Args:  ["/app/server.py"]
python3 /app/server.py

Service impact possiblemeasure it, do not guess— Time the stop. A duration that lands within a few milliseconds of --stop-timeout means the timeout expired and SIGKILL did the work; a fast stop means PID 1 handled the signal.

CONTAINER=web
time docker stop "$CONTAINER"
docker inspect --format 'exit={{.State.ExitCode}} oom={{.State.OOMKilled}}' "$CONTAINER"

web

real	0m10.043s
user	0m0.019s
sys	0m0.011s
exit=137 oom=false

Illustrative output

The pair of numbers is the verification, and each one rules something out on its own:

Duration at the timeout, exit 137. 137 is 128 + 9: SIGKILL. With oom=false, nothing ran out of memory — the stop timeout expired. PID 1 ignored SIGTERM.
Fast stop, exit 143. 143 is 128 + 15: SIGTERM. The signal was delivered and acted on. This is the working case.
Fast stop, exit 0. PID 1 handled SIGTERM, ran its shutdown path, and exited deliberately. This is the best case.

What if the entrypoint has to be a shell script?

Plenty of images need a wrapper: render a config template, wait for a dependency, pick a runtime flag. The wrapper does not have to stay PID 1. End it with exec:

#!/bin/sh
set -e
envsubst < /etc/app/config.tmpl > /etc/app/config.yaml

# Without exec, this shell stays PID 1 and swallows SIGTERM.
# With exec, the shell is REPLACED by the application, which
# inherits PID 1 and receives signals directly.
exec python3 /app/server.py "$@"

exec replaces the shell’s process image rather than forking a child, so there is no shell left to forward anything. This is the fix, and it costs one word.

If the wrapper genuinely needs to keep running — because it supervises more than one process — then it needs trap for SIGTERM and it needs to reap children, at which point you want --init or a real supervisor rather than a hand-written one.

Which signal does your application actually want?

Not every workload shuts down on SIGTERM. nginx treats SIGTERM as a fast shutdown that drops in-flight connections and reserves SIGQUIT for the graceful one. An image can declare the right signal so operators do not have to remember:

STOPSIGNAL SIGQUIT

docker run --stop-signal=SIGQUIT does the same per container. Check what an image will actually be sent with docker image inspect --format '{{.Config.StopSignal}}' — an empty result means the default, SIGTERM.

Two official images that override it, and why:

Image	`StopSignal`	Reason
`nginx`	`SIGQUIT`	nginx reads SIGTERM as fast shutdown, which drops in-flight connections. SIGQUIT is its graceful one.
`postgres`	`SIGINT`	Postgres reads SIGTERM as smart shutdown, which waits for every client to disconnect on its own — so a `docker stop` would hang for the full timeout and then be SIGKILLed mid-checkpoint. SIGINT is fast shutdown: refuse new connections, roll back open transactions, exit cleanly.

Read that Postgres row twice. The default signal is not merely suboptimal there — it produces the worst outcome available, an unclean kill, and it does so on a database. This is why an image that reimplements an official entrypoint has to carry the STOPSIGNAL line across with it.

Diagnosing a container that takes 10 seconds to stop

Read-only / Safeinspect stop behavior— A container's PID 1 entrypoint determines whether SIGTERM is handled.

docker inspect CONTAINER --format '{{.Path}}'
echo '---'
docker inspect CONTAINER --format '{{json .Config.Cmd}}'

Read-only / SafePID 1 details— Look at the actual PID 1 in the container's PID namespace.

PID=$(docker inspect --format '{{.State.Pid}}' CONTAINER)
cat /proc/$PID/status | grep -E '^(Name|Pid|State|PPid)'

The fix is one of:

--init — Docker injects tini as PID 1. tini installs default signal handlers and reaps zombies.
tini in the image — bake tini into your image and use it as the entrypoint.
dumb-init — alternative to tini with similar behavior.
Process manager — s6-overlay, supervisord, or systemd (in a container — for system services).
Application handles signals directly — fine for compiled apps in Go, Rust, etc. that respect SIGTERM by default.

A container PID 1 that handles signals correctly

Configuration change--init— The minimum fix for a shell-based entrypoint. Docker injects tini as PID 1.

docker run --init --name web -d nginx:1.27

Configuration changetini via ENTRYPOINT— The image-level fix. Bake tini into your image's ENTRYPOINT so every container inherits it.

# Dockerfile
COPY --from=ghcr.io/krallin/tini:latest /usr/local/bin/tini /sbin/tini
ENTRYPOINT ["/sbin/tini", "--"]
CMD ["python3", "/app/server.py"]

What other signals matter

SIGINT (2) — interrupt, default action: terminate. Usually same handling as SIGTERM.
SIGQUIT (3) — quit, default action: core dump. Rarely handled.
SIGHUP (1) — hangup, default: terminate. Used by some apps to trigger config reload (nginx, sshd).
SIGUSR1 (10) / SIGUSR2 (12) — user-defined. Java apps often use SIGUSR1 for heap dump.
SIGCHLD (17) — child terminated. PID 1 needs to wait() on this to reap zombies.

Graceful shutdown in practice

A production container should:

Receive SIGTERM.
Stop accepting new connections (mark unhealthy on health check).
Drain in-flight requests (typical grace: 10–30 seconds).
Close database connections cleanly.
Flush logs / metrics.
Exit 0.

The container’s --stop-timeout should be at least as long as the application’s graceful shutdown timeout, plus a buffer. Anything shorter forces SIGKILL before the app has finished draining.