From e002b8a28acc24e0a29cdc3f6cf759a197203f4a Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Thu, 20 Apr 2023 10:03:18 +0200
Subject: [PATCH] man: try to make clearer that /var/ is generally not
 available in /usr/lib/systemd/system-shutdown/ callouts

I made the mistake to look into what is installed into
/usr/lib/systemd/system-shutdown/ on Fedora. fwdupd among other things
assumes /var/ is available from these callouts, though it is not in the
general case.

Hence, let's emphasize this in the documentation a bit more.
---
 man/systemd-poweroff.service.xml | 57 ++++++++++++++------------------
 1 file changed, 25 insertions(+), 32 deletions(-)

diff --git a/man/systemd-poweroff.service.xml b/man/systemd-poweroff.service.xml
index 9adfcc5af0..98c20471da 100644
--- a/man/systemd-poweroff.service.xml
+++ b/man/systemd-poweroff.service.xml
@@ -36,41 +36,34 @@
   <refsect1>
     <title>Description</title>
 
-    <para><filename>systemd-poweroff.service</filename> is a system
-    service that is pulled in by <filename>poweroff.target</filename> and
-    is responsible for the actual system power-off operation. Similarly,
-    <filename>systemd-halt.service</filename> is pulled in by
-    <filename>halt.target</filename>,
-    <filename>systemd-reboot.service</filename> by
-    <filename>reboot.target</filename> and
-    <filename>systemd-kexec.service</filename> by
-    <filename>kexec.target</filename> to execute the respective
-    actions.</para>
+    <para><filename>systemd-poweroff.service</filename> is a system service that is pulled in by
+    <filename>poweroff.target</filename> and is responsible for the actual system power-off
+    operation. Similarly, <filename>systemd-halt.service</filename> is pulled in by
+    <filename>halt.target</filename>, <filename>systemd-reboot.service</filename> by
+    <filename>reboot.target</filename> and <filename>systemd-kexec.service</filename> by
+    <filename>kexec.target</filename> to execute the respective actions.</para>
 
-    <para>When these services are run, they ensure that PID 1 is
-    replaced by the
-    <filename>/usr/lib/systemd/systemd-shutdown</filename> tool which
-    is then responsible for the actual shutdown. Before shutting down,
-    this binary will try to unmount all remaining file systems,
-    disable all remaining swap devices, detach all remaining storage
-    devices and kill all remaining processes.</para>
+    <para>When these services are run, they ensure that PID 1 is replaced by the
+    <filename>/usr/lib/systemd/systemd-shutdown</filename> tool which is then responsible for the actual
+    shutdown. Before shutting down, this binary will try to unmount all remaining file systems (or at least
+    remount them read-only), disable all remaining swap devices, detach all remaining storage devices and
+    kill all remaining processes.</para>
 
-    <para>It is necessary to have this code in a separate binary
-    because otherwise rebooting after an upgrade might be broken — the
-    running PID 1 could still depend on libraries which are not
-    available any more, thus keeping the file system busy, which then
-    cannot be re-mounted read-only.</para>
+    <para>It is necessary to have this code in a separate binary because otherwise rebooting after an upgrade
+    might be broken — the running PID 1 could still depend on libraries which are not available any more,
+    thus keeping the file system busy, which then cannot be re-mounted read-only.</para>
 
-    <para>Immediately before executing the actual system
-    power-off/halt/reboot/kexec <filename>systemd-shutdown</filename>
-    will run all executables in
-    <filename>/usr/lib/systemd/system-shutdown/</filename> and pass
-    one arguments to them: either <literal>poweroff</literal>,
-    <literal>halt</literal>, <literal>reboot</literal>, or
-    <literal>kexec</literal>, depending on the chosen action. All
-    executables in this directory are executed in parallel, and
-    execution of the action is not continued before all executables
-    finished.</para>
+    <para>Shortly before executing the actual system power-off/halt/reboot/kexec
+    <filename>systemd-shutdown</filename> will run all executables in
+    <filename>/usr/lib/systemd/system-shutdown/</filename> and pass one arguments to them: either
+    <literal>poweroff</literal>, <literal>halt</literal>, <literal>reboot</literal>, or
+    <literal>kexec</literal>, depending on the chosen action. All executables in this directory are executed
+    in parallel, and execution of the action is not continued before all executables finished. Note that
+    these executables are run <emphasis>after</emphasis> all services have been shut down, and after most
+    mounts have been detached (the root file system as well as <filename>/run/</filename> and various API
+    file systems are still around though). This means any programs dropped into this directory must be
+    prepared to run in such a limited execution environment and not rely on external services or hierarchies
+    such as <filename>/var/</filename> to be around (or writable).</para>
 
     <para>Note that <filename>systemd-poweroff.service</filename> (and the related units) should never be
     executed directly. Instead, trigger system shutdown with a command such as <literal>systemctl
-- 
2.25.1