[systemd-devel] [PATCH] man: document kill behavior after the main process exits

[Daniel Drake]

While looking at the exact behavior of how systemd stops services,
I encountered some behavior that wasn't clear from reading the man
page.

Specifically, if the main process exits before its children, the child
processes will actually receive a second SIGTERM. If that doesn't
kill them, they will later receive a SIGKILL too, even if
SendSIGKILL=no. Add some notes about this.
---
 man/systemd.kill.xml | 30 ++++++++++++++++++++++++++++--
 1 file changed, 28 insertions(+), 2 deletions(-)

Thanks for helping me to get to the bottom of this in the thread:
  Zombie process still exists after stopping gdm.service

unit_kill_context() has a comment which is relevant here:

   /* FIXME: For now, we will not wait for the
    * cgroup members to die, simply because
    * cgroup notification is unreliable. It
    * doesn't work at all in containers, and
    * outside of containers it can be confused
    * easily by leaving directories in the
    * cgroup. */

   /* wait_for_exit = true; */

When this is fixed, assumed to happen soon, the precise behaviour seen
in the discussion will change slightly (in terms of timing).

So I have carefully written this documentation patch in a way that does
not go into the timing details. The text changed below should therefore
be true both before and after that FIXME is resolved.

diff --git a/man/systemd.kill.xml b/man/systemd.kill.xml
index e57f0e7..10232fb 100644
--- a/man/systemd.kill.xml
+++ b/man/systemd.kill.xml
@@ -154,8 +154,9 @@
         <term><varname>SendSIGKILL=</varname></term>
         <listitem><para>Specifies whether to send
         <constant>SIGKILL</constant> to remaining processes after a
-        timeout, if the normal shutdown procedure left processes of
-        the service around. Takes a boolean value. Defaults to "yes".
+        timeout, if the normal shutdown procedure didn't succeed in
+        shutting down the main process. Takes a boolean value.
+        Defaults to "yes".
         </para></listitem>
       </varlistentry>
 
@@ -163,6 +164,31 @@
   </refsect1>
 
   <refsect1>
+    <title>Beyond the main process</title>
+
+     <para>The <varname>KillMode=</varname> option primarily defines
+     behavior up until the point where the main process has gone away.
+     systemd expects that when killed with the signal specified by
+     <varname>KillSignal=</varname>, the main process will kill and
+     reap all the other processes in the control group before
+     exiting itself. If that doesn't happen, and the main process
+     exits with other processes still running in the control group,
+     systemd gets a bit more heavy-handed:</para>
+
+     <para>If <option>KillMode=control-group</option>, systemd will
+     then send a second <varname>KillSignal=</varname> signal to the
+     remaining processes, which will then be followed by a
+     <constant>SIGKILL</constant> if processes are still around, even
+     if <option>SendSIGKILL=no</option>.</para>
+
+     <para>Or, if <option>KillMode=mixed</option>, systemd will
+     directly send <constant>SIGKILL</constant> to all remaining members
+     of the control group, regardless of the
+     <varname>SendSIGKILL=</varname> preference.</para>
+
+  </refsect1>
+
+  <refsect1>
       <title>See Also</title>
       <para>
         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-- 
2.1.0