diff options
Diffstat (limited to 'man/systemd-soft-reboot.service.xml')
| -rw-r--r-- | man/systemd-soft-reboot.service.xml | 192 |
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> |