Merge pull request #8533 from poettering/bootup-shutdown-phase2

extend docs on second phase of shutdown and watchdog handling

3 files changed, 36 insertions, 28 deletions

diff --git a/man/bootup.xml b/man/bootup.xml
index 27619c29b8..565dda93cb 100644
--- a/man/bootup.xml
+++ b/man/bootup.xml
@@ -298,8 +298,18 @@ systemd-reboot.service   systemd-poweroff.service   systemd-halt.service   syste
            v                         v                        v                      v
     <emphasis>reboot.target</emphasis>             <emphasis>poweroff.target</emphasis>            <emphasis>halt.target</emphasis>           <emphasis>kexec.target</emphasis></programlisting>
 
-    <para>Commonly used system shutdown targets are
-    <emphasis>emphasized</emphasis>.</para>
+    <para>Commonly used system shutdown targets are <emphasis>emphasized</emphasis>.</para>
+
+    <para>Note that
+    <citerefentry>system<refentrytitle>systemd-halt.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+    <filename>systemd-reboot.service</filename>, <filename>systemd-poweroff.service</filename> and
+    <filename>systemd-kexec.service</filename> will transition the system and server manager (PID 1) into the second
+    phase of system shutdown (implemented in the <filename>systemd-shutdown</filename> binary), which will unmount any
+    remaining file systems, kill any remaining processes and release any other remaining resources, in a simple and
+    robust fashion, without taking any service or unit concept into account anymore. At that point, regular
+    applications and resources are generally terminated and released already, the second phase hence operates only as
+    safety net for everything that couldn't be stopped or released for some reason during the primary, unit-based
+    shutdown phase described above.</para>
   </refsect1>
 
   <refsect1>
@@ -309,6 +319,7 @@ systemd-reboot.service   systemd-poweroff.service   systemd-halt.service   syste
       <citerefentry project='man-pages'><refentrytitle>boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-halt.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry project='die-net'><refentrytitle>dracut</refentrytitle><manvolnum>8</manvolnum></citerefentry>
     </para>
   </refsect1>
diff --git a/man/systemd-halt.service.xml b/man/systemd-halt.service.xml
index b58279d828..a381b5c7d9 100644
--- a/man/systemd-halt.service.xml
+++ b/man/systemd-halt.service.xml
@@ -114,7 +114,8 @@
       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemd-suspend.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+      <citerefentry><refentrytitle>systemd-suspend.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>
     </para>
   </refsect1>
 
diff --git a/man/systemd-system.conf.xml b/man/systemd-system.conf.xml
index 5a308f275e..74dee3fd6f 100644
--- a/man/systemd-system.conf.xml
+++ b/man/systemd-system.conf.xml
@@ -157,31 +157,27 @@
         <term><varname>RuntimeWatchdogSec=</varname></term>
         <term><varname>ShutdownWatchdogSec=</varname></term>
 
-        <listitem><para>Configure the hardware watchdog at runtime and
-        at reboot. Takes a timeout value in seconds (or in other time
-        units if suffixed with <literal>ms</literal>,
-        <literal>min</literal>, <literal>h</literal>,
-        <literal>d</literal>, <literal>w</literal>). If
-        <varname>RuntimeWatchdogSec=</varname> is set to a non-zero
-        value, the watchdog hardware
-        (<filename>/dev/watchdog</filename> or the path specified with
-        <varname>WatchdogDevice=</varname> or the kernel option
-        <varname>systemd.watchdog-device=</varname>) will be programmed
-        to automatically reboot the system if it is not contacted within
-        the specified timeout interval. The system manager will ensure
-        to contact it at least once in half the specified timeout
-        interval. This feature requires a hardware watchdog device to
-        be present, as it is commonly the case in embedded and server
-        systems. Not all hardware watchdogs allow configuration of the
-        reboot timeout, in which case the closest available timeout is
-        picked. <varname>ShutdownWatchdogSec=</varname> may be used to
-        configure the hardware watchdog when the system is asked to
-        reboot. It works as a safety net to ensure that the reboot
-        takes place even if a clean reboot attempt times out. By
-        default <varname>RuntimeWatchdogSec=</varname> defaults to 0
-        (off), and <varname>ShutdownWatchdogSec=</varname> to 10min.
-        These settings have no effect if a hardware watchdog is not
-        available.</para></listitem>
+        <listitem><para>Configure the hardware watchdog at runtime and at reboot. Takes a timeout value in seconds (or
+        in other time units if suffixed with <literal>ms</literal>, <literal>min</literal>, <literal>h</literal>,
+        <literal>d</literal>, <literal>w</literal>). If <varname>RuntimeWatchdogSec=</varname> is set to a non-zero
+        value, the watchdog hardware (<filename>/dev/watchdog</filename> or the path specified with
+        <varname>WatchdogDevice=</varname> or the kernel option <varname>systemd.watchdog-device=</varname>) will be
+        programmed to automatically reboot the system if it is not contacted within the specified timeout interval. The
+        system manager will ensure to contact it at least once in half the specified timeout interval. This feature
+        requires a hardware watchdog device to be present, as it is commonly the case in embedded and server
+        systems. Not all hardware watchdogs allow configuration of all possible reboot timeout values, in which case
+        the closest available timeout is picked. <varname>ShutdownWatchdogSec=</varname> may be used to configure the
+        hardware watchdog when the system is asked to reboot. It works as a safety net to ensure that the reboot takes
+        place even if a clean reboot attempt times out. Note that the <varname>ShutdownWatchdogSec=</varname> timeout
+        applies only to the second phase of the reboot, i.e. after all regular services are already terminated, and
+        after the system and service manager process (PID 1) got replaced by the <filename>systemd-shutdown</filename>
+        binary, see system <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+        for details. During the first phase of the shutdown operation the system and service manager remains running
+        and hence <varname>RuntimeWatchdogSec=</varname> is still honoured. In order to define a timeout on this first
+        phase of system shutdown, configure <varname>JobTimeoutSec=</varname> and <varname>JobTimeoutAction=</varname>
+        in the <literal>[Unit]</literal> section of the <filename>shutdown.target</filename> unit. By default
+        <varname>RuntimeWatchdogSec=</varname> defaults to 0 (off), and <varname>ShutdownWatchdogSec=</varname> to
+        10min. These settings have no effect if a hardware watchdog is not available.</para></listitem>
       </varlistentry>
 
       <varlistentry>