Keep systemd service children inside the shutdown boundary

A stopped main process does not necessarily mean every process belonging to the service has exited.

Source facts

The Debian systemd.kill manual describes KillMode=control-group as terminating remaining processes in the unit’s control group on stop. The process mode targets only the main process, while none avoids manager-driven termination. The manual warns against process and none because surviving children can escape ordinary lifecycle and resource management while the service appears stopped.

Source: Debian systemd manual — systemd.kill(5) — systemd — Debian trixie — Debian Manpages.

Applicability

Review systemd unit process termination using the Debian trixie systemd.kill manual.

DSE recommendation

DSE recommends inventorying workers and subprocesses created by a service before changing KillMode. Define the graceful stop action and the bounded fallback when children do not exit. Avoid weakening the process boundary merely to preserve an unidentified helper. If a child must outlive the parent, give it an explicitly managed lifecycle rather than hiding it in a stopped unit. Keep restart behavior safe against duplicate workers, stale locks, or listeners left by a previous instance.

Verification

On a disposable service that creates a child process, compare the unit state with its remaining process set after stop. Verify the chosen mode and timeout terminate the intended workload without affecting unrelated units. Repeat startup afterward and confirm there is only one expected set of workers. Retain the main and child process identities with the unit’s effective stop configuration. Ask the service owner to approve the grace period and escalation result, and reconcile every surviving process before marking the stop exercise complete.

Official reference

Debian systemd manual — systemd.kill(5) — systemd — Debian trixie — Debian Manpages. Reviewed October 20, 2026.