Merge pull request #34534 from keszybz/man-exitrd

Formally document exitrds

2 files changed, 24 insertions, 13 deletions

diff --git a/man/bootup.xml b/man/bootup.xml
index db98f4649a..a0aafe5e79 100644
--- a/man/bootup.xml
+++ b/man/bootup.xml
@@ -47,9 +47,9 @@
     necessary file systems and spawning all configured services.</para>
 
     <para>On shutdown, the system manager stops all services, unmounts all non-busy file systems (detaching
-    the storage technologies backing them), and then (optionally) jumps into the exitrd, which is backed by
-    tmpfs, and unmounts/detaches the remaining file systems, including the real root. As a last step,
-    the system is powered down.</para>
+    the storage technologies backing them), and then (optionally) jumps into the exitrd. The exitrd is backed
+    by tmpfs and unmounts/detaches the remaining file systems, including the real root. As a last step, the
+    system is powered down.</para>
 
     <para>Additional information about the system boot process may be
     found in
@@ -344,6 +344,17 @@ systemd-reboot.service     |               |               |               |
   </refsect1>
 
   <refsect1>
+    <title>The exitrd</title>
+
+    <para>The "exitrd" is a concept symmetrical to the initrd. When the system manager is shutting down and
+    <filename>/run/initramfs/shutdown</filename> exists, it will switch root to
+    <filename>/run/initramfs/</filename> and execute <filename>/shutdown</filename>. This program runs from
+    the tmpfs mounted on <filename>/run/</filename>, so it can unmount the old root file system and perform
+    additional steps, for example dismantle complex storage or perform additional logging about the shutdown.
+    </para>
+  </refsect1>
+
+  <refsect1>
     <title>See Also</title>
     <para><simplelist type="inline">
       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
diff --git a/man/os-release.xml b/man/os-release.xml
index 315ed8fcd6..99e31ba24e 100644
--- a/man/os-release.xml
+++ b/man/os-release.xml
@@ -53,9 +53,9 @@
     precedence over <filename>/usr/lib/os-release</filename>.
     Applications should check for the former, and exclusively use its
     data if it exists, and only fall back to
-    <filename>/usr/lib/os-release</filename> if it is missing.
-    Applications should not read data from both files at the same
-    time. <filename>/usr/lib/os-release</filename> is the recommended
+    <filename>/usr/lib/os-release</filename> if that is missing.
+    Applications should not combine the data from both files.
+    <filename>/usr/lib/os-release</filename> is the recommended
     place to store OS release information as part of vendor trees.
     <filename>/etc/os-release</filename> should be a relative symlink
     to <filename>/usr/lib/os-release</filename>, to provide
@@ -88,10 +88,10 @@
     <refsect2>
       <title><filename>/etc/initrd-release</filename></title>
 
-      <para>In the <ulink
-      url="https://docs.kernel.org/admin-guide/initrd.html">initrd</ulink>,
+      <para>In the <ulink url="https://docs.kernel.org/admin-guide/initrd.html">initrd</ulink>
+      and exitrd,
       <filename>/etc/initrd-release</filename> plays the same role as <filename>os-release</filename> in the
-      main system. Additionally, the presence of that file means that the system is in the initrd phase.
+      main system. Additionally, the presence of that file means that the system is in the initrd/exitrd phase.
       <filename>/etc/os-release</filename> should be symlinked to <filename>/etc/initrd-release</filename>
       (or vice versa), so programs that only look for <filename>/etc/os-release</filename> (as described
       above) work correctly.</para>
@@ -594,10 +594,10 @@
           <listitem><para>Takes a space-separated list of one or more of the strings
           <literal>system</literal>, <literal>initrd</literal> and <literal>portable</literal>. This field is
           only supported in <filename>extension-release.d/</filename> files and indicates what environments
-          the system extension is applicable to: i.e. to regular systems, to initrds, or to portable service
-          images. If unspecified, <literal>SYSEXT_SCOPE=system portable</literal> is implied, i.e. any system
-          extension without this field is applicable to regular systems and to portable service environments,
-          but not to initrd environments.</para>
+          the system extension is applicable to: i.e. to regular systems, to initrds and exitrds, or to
+          portable service images. If not specified, <literal>SYSEXT_SCOPE=system portable</literal> is
+          implied, i.e. any system extension without this field is applicable to regular systems and to
+          portable service environments, but not to initrd/exitrd environments.</para>
 
           <xi:include href="version-info.xml" xpointer="v250"/></listitem>
         </varlistentry>