Signals & the PID 1 Problem

## The shape of container shutdown A container is not a virtual machine you power off — it is a process tree, and stopping it means asking the process at the root of that tree to end. Docker models that as a two-phase handshake: a polite request first, a fatal one after a deadline. ## Phase 1 — the stop signal When you run `docker stop <container>`, the Docker daemon (through containerd and the OCI runtime) sends a signal to **PID 1 in the container's PID namespace** — the single process Docker started from your `ENTRYPOINT`/`CMD`. It does not fan the signal out to child processes; anything else running in the container is that process's responsibility. The signal sent is, in priority order: whatever `docker stop --signal` names on this invocation, otherwise the image's Dockerfile `STOPSIGNAL` instruction, otherwise SIGTERM. SIGTERM (signal 15) is the conventional "please terminate" request: a process can install a handler for it and use the moment to stop accepting new work, finish or abandon in-flight work, flush buffers, close database connections and then exit. ## Phase 2 — the grace period and SIGKILL After sending the stop signal the daemon waits. The default wait is **10 seconds**. You change it per invocation with `docker stop -t 30 <container>`, and you can change the daemon-wide default with `--shutdown-timeout` (which also governs how long containers get when the daemon itself shuts down). Two outcomes: - **PID 1 exits inside the window.** The container transitions to `exited` and records PID 1's own exit code — 0 for a clean exit, or whatever code the app chose. - **PID 1 is still alive when the window closes.** The daemon sends **SIGKILL** (signal 9). SIGKILL cannot be caught, blocked or ignored; the kernel destroys the process. The container is recorded as exiting with **137**, which is the shell convention 128 + signal number (128 + 9). A SIGTERM-killed process would similarly show 143. When PID 1 dies, the kernel tears down the PID namespace and kills every remaining process in it, so orphaned children do not survive the container. ## Why the difference matters in production SIGKILL gives the process zero opportunity to clean up. Anything buffered in userspace is lost — an unflushed log batch, a partially written file, an HTTP response half-sent. A database engine killed with 9 typically has to run crash recovery on next start. A queue consumer killed with 9 leaves messages in-flight until the broker's visibility timeout expires and redelivers them. That is exactly why the graceful phase exists, and why an app that ignores SIGTERM is a real defect: it converts every deploy and every restart into a crash. ## docker kill `docker kill <container>` sends SIGKILL immediately with no grace period. It also doubles as a general signal-sending tool: `docker kill -s HUP nginx` sends SIGHUP to PID 1, which many servers use for config reload. Note the asymmetry — `docker kill` defaults to SIGKILL and ignores `STOPSIGNAL`, while `docker stop` honors it. `docker restart` is `stop` followed by `start` and takes the same `-t` flag, so it inherits the same grace semantics. `docker rm -f` on a running container also goes through a kill path rather than a graceful stop. ## Common traps 1. **The signal only reaches PID 1.** If your entrypoint is a shell script that launches the real server as a child, SIGTERM hits the shell, not the server. Use `exec` in the script, or the exec form of `ENTRYPOINT`, so the real process *becomes* PID 1. 2. **PID 1 has no default SIGTERM behavior.** The Linux kernel does not apply the usual default action to signals for PID 1, so a program with no explicit SIGTERM handler simply ignores it and always eats the full 10 seconds before SIGKILL. 3. **Ten seconds is a policy, not a law.** A service that legitimately needs to drain 30-second requests must be given a longer timeout everywhere it is stopped, and its shutdown code must be bounded so it actually finishes inside that window. 4. **A slow `docker stop` is a symptom.** If stopping consistently takes exactly the timeout, the container is being SIGKILLed every time; treat that as a bug to fix, not background noise. ## Verifying behavior Stop a container and time it: `time docker stop app`. Sub-second means the app handled the signal. Bang on 10 seconds means it did not. Then confirm with `docker inspect -f '{{.State.ExitCode}}' app` — 137 confirms SIGKILL.