stop, kill, and pause — the three ways to interrupt a container

There are three commands that interrupt a running container and they are not interchangeable. docker stop asks. docker kill tells. docker pause freezes without asking or telling anybody, including the application.

Choosing the wrong one is how deploys drop in-flight requests, how database containers come back needing recovery, and how a “quick pause for a snapshot” turns into a client-visible hang.

The stop path, step by step

Step 3 is where most surprises live. The signal goes to PID 1 and nowhere else. If your entrypoint is a shell script that launched the real application in the background, the shell receives SIGTERM and the application does not. If PID 1 is a shell without a trap, the signal is discarded entirely, because Linux does not deliver an unhandled signal to PID 1 of a namespace.

Step 6 is where data is lost. SIGKILL cannot be caught, blocked, or ignored. Whatever the process was doing — a partially written file, an open transaction, an unflushed buffer — stops mid-instruction.

Which timeout wins

Three places can set a stop timeout, and they are consulted in this order:

There is no STOPTIMEOUT instruction in a Dockerfile — the image can set the stop signal but not the stop timeout. Compose has stop_grace_period, which sets the container’s stop timeout at creation.

$ docker inspect --format 'signal={{.Config.StopSignal}} timeout={{.Config.StopTimeout}}' web

signal= timeout=<nil>

Empty and <nil> mean “not configured, use the defaults”: SIGTERM and 10 seconds. This is the single most useful pre-deploy check on a stateful container, because the default 10 seconds is far too short for most databases and message brokers.

STOPSIGNAL and --stop-signal

Some applications shut down cleanly on something other than SIGTERM. nginx treats SIGQUIT as “graceful shutdown, finish current requests” and SIGTERM as “fast shutdown, drop them”. That distinction is exactly what you want control over during a deploy.

FROM nginx:1.27
STOPSIGNAL SIGQUIT

or, without changing the image:

docker run -d --name web --stop-signal SIGQUIT --stop-timeout 60 nginx:1.27

Recent Docker CLI versions also accept --signal on stop and restart, which overrides the configured stop signal for that one invocation:

docker stop --signal SIGQUIT --timeout 60 web

If your CLI does not have that flag, set --stop-signal at create time instead — the per-container setting has been there far longer.

kill is not “stop harder”

docker kill sends one signal, immediately, with no timer and no fallback. Its default is SIGKILL, which is why people think of it as the violent option, but -s makes it the general-purpose signalling tool:

docker kill --signal SIGHUP web

Common uses that have nothing to do with killing:

• SIGHUP — reload configuration, for daemons that implement it.
• SIGUSR1 — reopen log files (nginx), dump goroutine stacks (some Go services), toggle debug logging.
• SIGUSR2 — application-defined; often a live binary upgrade.

pause is a kernel freeze

docker pause does not signal anything. On cgroup v2 it writes 1 to the container’s cgroup.freeze file, and the kernel stops scheduling every task in that cgroup. On cgroup v1 it used the freezer controller for the same effect.

# cat /sys/fs/cgroup/system.slice/docker-25fb9c8b983b.scope/cgroup.freeze

0

What that means in practice:

• Memory is untouched. Every page the process had is still resident. A paused container frees no RAM.
• Sockets stay open. The listening socket is still bound, so the kernel keeps accepting connections into the backlog. Clients do not get “connection refused” — they connect successfully and then wait forever. This is worse than a stop for anything behind a load balancer, because the health of the TCP handshake is what most simple health checks measure.
• Timers do not fire. Application-level heartbeats, cluster keepalives, and lease renewals all stop. A paused node in a clustered application gets evicted from the cluster while looking perfectly healthy at the TCP layer.
• Nothing is flushed. The application has no idea it was paused, so it cannot checkpoint, flush a write-ahead log, or close a transaction.

A paused process cannot run a signal handler, because it is not being scheduled at all. So the graceful half of docker stop is meaningless while a container is paused: unpause it first, then stop it.

docker unpause web
docker stop --timeout 60 web

Choosing between them

Knowledge check