Set timeouts and stop cleanly

When you stop a service, systemd sends a termination signal and waits before escalating. By default that is SIGTERM, a 90 second wait, then SIGKILL for anything still alive. Your application should use that window to stop accepting work, finish in-flight requests, and flush what it must.

SIGKILL cannot be caught. Anything the process had not written yet is lost. The goal of this lesson is to make sure your service never gets that far in normal operation.

Set bounds from measured behavior

[Service]
TimeoutStartSec=30
TimeoutStopSec=20

Use TimeoutStartSec= and TimeoutStopSec= from measured behavior, not guesses. If your application drains connections in five seconds, twenty is a comfortable stop bound. If startup ever legitimately takes a minute, a 30 second start timeout will kill healthy starts.

KillSignal= changes the initial signal, but the default SIGTERM is normally correct — it is the signal every runtime and framework documents for graceful shutdown. Change it only for software that documents something else.

Avoid KillMode=process. It signals only the main process and can leave children behind, still holding ports and files after systemd considers the service stopped. The default (control-group) signals the whole process tree, which is almost always what you mean.

Watch a stop happen

Follow the journal in one terminal while stopping the service in another:

journalctl -u demo-api.service -f

sudo systemctl stop demo-api.service

A clean stop logs the application’s own shutdown messages and then Deactivated successfully. A service that ignores SIGTERM looks like this instead:

Stopping demo-api.service - Demo API server...
demo-api.service: State 'stop-sigterm' timed out. Killing.
demo-api.service: Killing process 1423 (node) with signal SIGKILL.
demo-api.service: Main process exited, code=killed, status=9/KILL

If you see stop-sigterm timed out, the fix is in the application first: handle SIGTERM and exit. Raising TimeoutStopSec= only hides the missing handler.

Stop a test service while following its journal. Confirm which signal it receives, how long it needs, and whether every child process exits.