From e799056e15a63c31bdbd2209bb39768933fadcd0 Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Wed, 21 Mar 2018 20:57:06 +0100
Subject: [PATCH] man: document that there's a second phase of shutdown in
 bootup(7)

---
 man/bootup.xml               | 15 +++++++++++++--
 man/systemd-halt.service.xml |  3 ++-
 2 files changed, 15 insertions(+), 3 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>
 
-- 
2.25.1