docs: document LUO support

diff --git a/docs/FILE_DESCRIPTOR_STORE.md b/docs/FILE_DESCRIPTOR_STORE.md
index 8fa2ae0127c9625d19282c8592ae497b1b003181..e6141a4e01b6e4e85774efa296990dfa99a19e99 100644 (file)
--- a/docs/FILE_DESCRIPTOR_STORE.md
+++ b/docs/FILE_DESCRIPTOR_STORE.md
@@ -181,6 +181,31 @@ continuously).
 For further details see [Resource
 Pass-Through](https://www.freedesktop.org/software/systemd/man/latest/systemd-soft-reboot.service.html#Resource%20Pass-Through).
 
+## Kernel Live Update (kexec)
+
+On kernels that support the [Live Update
+Orchestrator](https://docs.kernel.org/userspace-api/liveupdate.html)
+(LUO), the fdstore may also be preserved across a `kexec`-based reboot into a
+new kernel. This allows updating the kernel itself without losing pinned
+resources such as serialized service state, analogous to soft reboot, but for
+the kernel.
+
+Only file descriptors that reference LUO-compatible kernel objects can be
+preserved this way. Currently the kernel supports `memfd` only for LUO, but
+more types are being worked on. Other kinds of file descriptors (sockets,
+regular files, etc.) will be dropped from the store during the kexec transition.
+
+LUO preservation of the fdstore is triggered automatically whenever a
+kexec-based reboot is initiated on an LUO-capable kernel, and is gated by a
+similar rule as soft-reboot: the service must have
+`FileDescriptorStorePreserve=yes` set, so that its fdstore remains loaded. On
+the other side of the kexec, the system manager rebuilds the mapping of fds
+back to their original service units, so that when those services are
+re-activated the fds are passed to them using the normal fdstore protocol.
+Adding a `FDNAME=…` string identifying the fd is also highly recommended,
+otherwise in case multiple fds are stored, it will be impossible to
+distinguish them, as they will all carry the default name (`stored`).
+
 ## Initrd Transitions
 
 The fdstore may also be used to pass file descriptors for resources from the

diff --git a/man/sd_notify.xml b/man/sd_notify.xml
index f9bb56b2d4730eb8e72f4108a69df12e0a4be774..52685c404bb9b13459152e18a29ae75a4682e904 100644 (file)
--- a/man/sd_notify.xml
+++ b/man/sd_notify.xml
@@ -428,6 +428,17 @@
         <para>For further information on the file descriptor store see the <ulink
         url="https://systemd.io/FILE_DESCRIPTOR_STORE">File Descriptor Store</ulink> overview.</para>
 
+        <para>On kernels that support the <ulink
+        url="https://docs.kernel.org/userspace-api/liveupdate.html">Live Update Orchestrator</ulink>,
+        compatible file descriptors stored this way (such as <citerefentry
+        project='man-pages'><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>)
+        are additionally preserved across <literal>kexec</literal>-based reboots and handed back to the
+        service on the other side, provided <varname>FileDescriptorStorePreserve=yes</varname> is set on
+        the service (see
+        <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
+        See the <ulink url="https://systemd.io/FILE_DESCRIPTOR_STORE">File Descriptor Store</ulink>
+        overview for details.</para>
+
         <xi:include href="version-info.xml" xpointer="v219"/></listitem>
       </varlistentry>
 

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index b25f1a90aabe0ce903adafea2c3b5ab6d278e902..028c1144b08207066736f540b110fd906ff35a4d 100644 (file)
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -1266,6 +1266,15 @@ RestartMaxDelaySec=160s</programlisting>
         See the <ulink url="https://systemd.io/FILE_DESCRIPTOR_STORE">File Descriptor Store</ulink>
         overview for details.</para>
 
+        <para>Setting this to <constant>yes</constant> also ensures the file descriptor store is kept loaded
+        across a <literal>kexec</literal>-based reboot on kernels supporting the <ulink
+        url="https://docs.kernel.org/userspace-api/liveupdate.html">Live Update Orchestrator</ulink>,
+        so that compatible file descriptors (such as <citerefentry
+        project='man-pages'><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>)
+        are preserved and handed back to the service on the other side. See the <ulink
+        url="https://systemd.io/FILE_DESCRIPTOR_STORE">File Descriptor Store</ulink> overview for
+        details.</para>
+
         <para>Use <command>systemctl clean --what=fdstore …</command> to release the file descriptor store
         explicitly.</para>