summaryrefslogtreecommitdiffstats
path: root/man/systemd-soft-reboot.service.xml
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-10 20:49:52 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-10 20:49:52 +0000
commit55944e5e40b1be2afc4855d8d2baf4b73d1876b5 (patch)
tree33f869f55a1b149e9b7c2b7e201867ca5dd52992 /man/systemd-soft-reboot.service.xml
parentInitial commit. (diff)
downloadsystemd-55944e5e40b1be2afc4855d8d2baf4b73d1876b5.tar.xz
systemd-55944e5e40b1be2afc4855d8d2baf4b73d1876b5.zip
Adding upstream version 255.4.upstream/255.4
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'man/systemd-soft-reboot.service.xml')
-rw-r--r--man/systemd-soft-reboot.service.xml192
1 files changed, 192 insertions, 0 deletions
diff --git a/man/systemd-soft-reboot.service.xml b/man/systemd-soft-reboot.service.xml
new file mode 100644
index 0000000..e83e18f
--- /dev/null
+++ b/man/systemd-soft-reboot.service.xml
@@ -0,0 +1,192 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+
+<refentry id="systemd-soft-reboot.service"
+ xmlns:xi="http://www.w3.org/2001/XInclude">
+
+ <refentryinfo>
+ <title>systemd-soft-reboot.service</title>
+ <productname>systemd</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>systemd-soft-reboot.service</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>systemd-soft-reboot.service</refname>
+ <refpurpose>Userspace reboot operation</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <para><filename>systemd-soft-reboot.service</filename></para>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para><filename>systemd-soft-reboot.service</filename> is a system service that is pulled in by
+ <filename>soft-reboot.target</filename> and is responsible for performing a userspace-only reboot
+ operation. When invoked, it will send the <constant>SIGTERM</constant> signal to any processes left
+ running (but does not wait for the processes to exit), and follow up with <constant>SIGKILL</constant>.
+ If the <filename>/run/nextroot/</filename> directory exists (which may be a regular directory, a
+ directory mount point or a symlink to either) then it will switch the file system root to it. It then
+ reexecutes the service manager off the (possibly now new) root file system, which will enqueue a new boot
+ transaction as in a normal reboot.</para>
+
+ <para>Such a userspace-only reboot operation permits updating or resetting the entirety of userspace with
+ minimal downtime, as the reboot operation does <emphasis>not</emphasis> transition through:</para>
+
+ <itemizedlist>
+ <listitem><para>The second phase of regular shutdown, as implemented by
+ <citerefentry><refentrytitle>systemd-shutdown</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem>
+
+ <listitem><para>The third phase of regular shutdown, i.e. the return to the initrd context.
+ </para></listitem>
+
+ <listitem><para>The hardware reboot operation.</para></listitem>
+
+ <listitem><para>The firmware initialization.</para></listitem>
+
+ <listitem><para>The boot loader initialization.</para></listitem>
+
+ <listitem><para>The kernel initialization.</para></listitem>
+
+ <listitem><para>The initrd initialization.</para></listitem>
+ </itemizedlist>
+
+ <para>However this form of reboot comes with drawbacks as well:</para>
+
+ <itemizedlist>
+ <listitem><para>The OS update remains incomplete, as the kernel is not reset and continues
+ running.</para></listitem>
+
+ <listitem><para>Kernel settings (such as <filename>/proc/sys/</filename> settings, a.k.a. "sysctl", or
+ <filename>/sys/</filename> settings) are not reset.</para></listitem>
+ </itemizedlist>
+
+ <para>These limitations may be addressed by various means, which are outside of the scope of this
+ documentation, such as kernel live-patching and sufficiently comprehensive
+ <filename>/etc/sysctl.d/</filename> files.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Resource Pass-Through</title>
+
+ <para>Various runtime OS resources can passed from a system runtime to the next, through the userspace
+ reboot operation. Specifically:</para>
+
+ <itemizedlist>
+ <listitem><para>File descriptors placed in the file descriptor store of services that remain active
+ until the very end are passed to the next boot, where they are placed in the file descriptor store of
+ the same unit. For this to work, units must declare <varname>DefaultDependencies=no</varname> (and
+ avoid a manual <varname>Conflicts=shutdown.target</varname> or similar) to ensure they are not
+ terminated as usual during the system shutdown operation. Alternatively, use
+ <varname>FileDescriptorStorePreserve=</varname> to allow the file descriptor store to remain pinned
+ even when the unit is down. See
+ <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
+ details about the file descriptor store.</para></listitem>
+
+ <listitem><para>Similar to this, file descriptors associated with <filename>.socket</filename> units
+ remain open (and connectible) if the units are not stopped during the transition. (Achieved by
+ <varname>DefaultDependencies=no</varname>.)</para></listitem>
+
+ <listitem><para>The <filename>/run/</filename> file system remains mounted and populated and may be
+ used to pass state information between such userspace reboot cycles.</para></listitem>
+
+ <listitem><para>Service processes may continue to run over the transition, past soft-reboot and into
+ the next session, if they are placed in services that remain active until the very end of shutdown
+ (which again is achieved via <varname>DefaultDependencies=no</varname>). They must also be set up to
+ avoid being killed by the aforementioned <constant>SIGTERM</constant> and <constant>SIGKILL</constant>
+ via <varname>SurviveFinalKillSignal=yes</varname>, and also be configured to avoid being stopped on
+ isolate via <varname>IgnoreOnIsolate=yes</varname>. They also have to be configured to be stopped on
+ normal shutdown, reboot and maintenance mode. Finally, they have to be ordered after
+ <constant>basic.target</constant> to ensure correct ordeering on boot. Note that in case any new or
+ custom units are used to isolate to, or that implement an equivalent shutdown functionality, they will
+ also have to be configured manually for correct ordering and conflicting. For example:</para>
+
+ <programlisting>[Unit]
+Description=My surviving service
+SurviveFinalKillSignal=yes
+IgnoreOnIsolate=yes
+DefaultDependencies=no
+After=basic.target
+Conflicts=reboot.target
+Before=reboot.target
+Conflicts=kexec.target
+Before=kexec.target
+Conflicts=poweroff.target
+Before=poweroff.target
+Conflicts=halt.target
+Before=halt.target
+Conflicts=rescue.target
+Before=rescue.target
+Conflicts=emergency.target
+Before=emergency.target
+
+[Service]
+Type=oneshot
+ExecStart=sleep infinity
+ </programlisting>
+ </listitem>
+
+ <listitem><para>File system mounts may remain mounted during the transition, and complex storage
+ attached, if configured to remain until the very end of the shutdown process. (Also achieved via
+ <varname>DefaultDependencies=no</varname>, and by avoiding
+ <varname>Conflicts=umount.target</varname>)</para></listitem>
+
+ <listitem><para>If the unit publishes a service over D-Bus, the connection needs to be re-established
+ after soft-reboot as the D-Bus broker will be stopped and then started again. When using the sd-bus
+ library this can be achieved by adapting the following example.
+ <programlisting><xi:include href="sd_bus_service_reconnect.c" parse="text"/></programlisting>
+ </para></listitem>
+ </itemizedlist>
+
+ <para>Even though passing resources from one soft reboot cycle to the next is possible this way, we
+ strongly suggest to use this functionality sparingly only, as it creates a more fragile system as
+ resources from different versions of the OS and applications might be mixed with unforeseen
+ consequences. In particular it's recommended to <emphasis>avoid</emphasis> allowing processes to survive
+ the soft reboot operation, as this means code updates will necessarily be incomplete, and processes
+ typically pin various other resources (such as the file system they are backed by), thus increasing
+ memory usage (as two versions of the OS/application/file system might be kept in memory). Leaving
+ processes running during a soft-reboot operation requires disconnecting the service comprehensively from
+ the rest of the OS, i.e. minimizing IPC and reducing sharing of resources with the rest of the OS. A
+ possible mechanism to achieve this is the concept of <ulink
+ url="https://systemd.io/PORTABLE_SERVICES">Portable Services</ulink>, but make sure no resource from the
+ host's OS filesystems is pinned via <varname>BindPaths=</varname> or similar unit settings, otherwise the
+ old, originating filesystem will remain mounted as long as the unit is running.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Notes</title>
+
+ <para>Note that because
+ <citerefentry><refentrytitle>systemd-shutdown</refentrytitle><manvolnum>8</manvolnum></citerefentry> is
+ not executed, the executables in <filename>/usr/lib/systemd/system-shutdown/</filename> are not executed
+ either.</para>
+
+ <para>Note that <filename>systemd-soft-reboot.service</filename> (and related units) should never be
+ executed directly. Instead, trigger system shutdown with a command such as <literal>systemctl
+ soft-reboot</literal>.</para>
+
+ <para>Note that if a new root file system has been set up on <literal>/run/nextroot/</literal>, a
+ <command>soft-reboot</command> will be performed when the <command>reboot</command> command is
+ invoked.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd-poweroff.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>
+
+</refentry>