Control How systemd Stops a Service with KillMode and Signals

You will configure and verify the process-killing policy for one systemd service, using a drop-in rather than editing the vendor unit. The result will make the service's stop behaviour explicit while keeping the original unit available for recovery. Allow about fifteen minutes. You need a systemd host, an existing service name, and sudo access if the unit is system-wide.

1. Inspect the current unit before changing it

Choose a service that you understand. Do not test this first on a database, queue, or other service where an abrupt stop could lose work. Replace example.service with the real unit name in every command below.

$ systemctl status example.service --no-pager
$ systemctl cat example.service
$ systemctl show example.service -p FragmentPath -p DropInPaths -p KillMode -p KillSignal -p FinalKillSignal -p SendSIGKILL -p TimeoutStopUSec

These are read-only commands and normally need no elevation. The installed package on this machine is systemd 255.4-1ubuntu8.17; the local systemd.kill(5) page identifies the documented interface as systemd 255. The effective values shown by systemctl show matter more than a setting found in one file, because vendor units, administrator drop-ins and generated configuration can all contribute.

Checkpoint: record the current values before changing anything. In particular, check whether the service already has a drop-in and whether its stop timeout is long enough for the program to finish.

2. Choose the process boundary

For most services, leave KillMode=control-group. When systemd stops the unit, it first runs the configured stop command, then terminates remaining processes in the unit's control group. This is the default and keeps helper processes inside the service lifecycle.

KillMode=mixed sends the first termination signal to the main process, then sends the final signal to every remaining process in the control group. This can suit a service whose main process needs a graceful shutdown while worker processes must not survive it. KillMode=process targets only the main process, and KillMode=none leaves processes running. The manual explicitly discourages both because processes can escape systemd's lifecycle and resource accounting.

Do not use process or none to hide a badly behaved child process. Find out why the child remains alive instead. A service reported as stopped while its old workers continue running is a confusing and potentially unsafe operating state.

3. Create a small administrator drop-in

Use systemctl edit to create a drop-in for a system service. This command requires elevation and opens your configured editor:

$ sudo systemctl edit example.service

Enter one section and only the settings you intend to change. This example keeps all processes in the control group, uses the normal termination signal, and allows 30 seconds before the final signal:

[Service]
KillMode=control-group
KillSignal=SIGTERM
TimeoutStopSec=30s

The file is normally saved below /etc/systemd/system/example.service.d/. The section is [Service] for a service. The same kill options are shared by service, socket, mount, swap and scope units, but the relevant section changes to [Socket], [Mount] or [Swap] where appropriate.

Do not add FinalKillSignal=SIGTERM as a supposedly gentler fallback. The final signal should normally be a signal the program cannot catch, and the default is SIGKILL. If you disable that fallback with SendSIGKILL=no, a control-group or mixed service may fail to restart while old processes remain in its group.

4. Validate and reload the configuration

Ask systemd to parse the unit files before touching the running service:

$ sudo systemd-analyze verify example.service

No output and exit status zero is the usual successful result. Warnings or errors identify the file and line that need attention. Fix those before continuing.

Reload the manager configuration. This does not itself stop or restart the service:

$ sudo systemctl daemon-reload
$ systemctl show example.service -p KillMode -p KillSignal -p TimeoutStopUSec

Checkpoint: confirm that the reported values match the drop-in. If they do not, inspect systemctl cat example.service and systemctl show example.service -p DropInPaths; another drop-in or a misspelled unit name is a more likely explanation than a signal problem.

5. Test the stop path deliberately

Stopping or restarting a service is service-disrupting and requires elevation. Arrange a maintenance window, then choose either a stop or a restart. A restart is useful when the service must come back:

$ sudo systemctl restart example.service
$ systemctl is-active example.service
active

During a stop, systemd uses KillSignal= for the initial request, and sends SIGCONT immediately afterwards so a suspended task can still be terminated. If processes remain, the configured TimeoutStopSec= applies for the relevant kill modes. With SendSIGKILL=yes, systemd then sends FinalKillSignal=, which defaults to SIGKILL.

Inspect the journal after the test:

$ journalctl -u example.service --since "5 minutes ago" --no-pager
$ systemctl status example.service --no-pager

Do not treat a successful systemctl exit status as proof that every child finished cleanly. Check the service's own shutdown messages and, if it is stopped, look for unexpected processes using the service's normal diagnostic tools. A longer timeout may help a graceful shutdown, but it cannot repair a program that ignores its termination contract.

6. Keep restart-only behaviour separate

RestartKillSignal= changes the first signal used during a restart job. It was added in systemd 244 and is not set by default, so the value of KillSignal= is used unless you configure it. This is a narrow exception, not a replacement for understanding the ordinary stop path.

Use a restart-specific signal only when the program documents a real difference between stopping and reloading through a restart. Verify it with:

$ systemctl show example.service -p KillSignal -p RestartKillSignal

SendSIGHUP=yes is another targeted option. It sends SIGHUP to remaining processes immediately after the configured first signal and defaults to no. It can be useful for shell-like programs, but it is not a general substitute for a service's documented shutdown protocol.

7. Undo the drop-in if the test is wrong

To remove the administrator override, use the same editor and delete the settings, or remove the specific drop-in with an explicit path after checking it:

$ systemctl cat example.service
$ sudo rm /etc/systemd/system/example.service.d/override.conf
$ sudo systemctl daemon-reload

The rm command is irreversible, so check the path before running it and do not substitute a broad directory. If you used a different file name, remove that file instead. Restart the service only if you need the old process state to be recreated:

$ sudo systemctl restart example.service
$ systemctl show example.service -p KillMode -p KillSignal -p TimeoutStopUSec