Merge pull request #34534 from keszybz/man-exitrd

Formally document exitrds

TODO

@@ -1374,12 +1374,6 @@ Features:
   CapabilityQuintet we already have. (This likely allows us to drop libcap
   dep in the base OS image)
 
-* add concept for "exitrd" as inverse of "initrd", that we can transition to at
-  shutdown, and has similar security semantics. This should then take the place
-  of dracut's shutdown logic. Should probably support sysexts too. Care needs
-  to be taken that the resulting logic ends up in RAM, i.e. is copied out of
-  on-disk storage.
-
 * userdbd: implement an additional varlink service socket that provides the
   host user db in restricted form, then allow this to be bind mounted into
   sandboxed environments that want the host database in minimal form. All

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
+    the storage technologies backing them), and then (optionally) jumps into the exitrd. The exitrd is backed
-    tmpfs, and unmounts/detaches the remaining file systems, including the real root. As a last step,
+    by tmpfs and unmounts/detaches the remaining file systems, including the real root. As a last step, the
-    the system is powered down.</para>
+    system is powered down.</para>
 
     <para>Additional information about the system boot process may be
     found in
@@ -343,6 +343,17 @@ systemd-reboot.service     |               |               |               |
     shutdown phase described above.</para>
   </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">

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.
+    <filename>/usr/lib/os-release</filename> if that is missing.
-    Applications should not read data from both files at the same
+    Applications should not combine the data from both files.
-    time. <filename>/usr/lib/os-release</filename> is the recommended
+    <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
+      <para>In the <ulink url="https://docs.kernel.org/admin-guide/initrd.html">initrd</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
+          the system extension is applicable to: i.e. to regular systems, to initrds and exitrds, or to
-          images. If unspecified, <literal>SYSEXT_SCOPE=system portable</literal> is implied, i.e. any system
+          portable service images. If not specified, <literal>SYSEXT_SCOPE=system portable</literal> is
-          extension without this field is applicable to regular systems and to portable service environments,
+          implied, i.e. any system extension without this field is applicable to regular systems and to
-          but not to initrd environments.</para>
+          portable service environments, but not to initrd/exitrd environments.</para>
 
           <xi:include href="version-info.xml" xpointer="v250"/></listitem>
         </varlistentry>