final v236 update (#7649)

[thirdparty/systemd.git] / man / systemd.offline-updates.xml

diff --git a/man/systemd.offline-updates.xml b/man/systemd.offline-updates.xml
index f404c8d72fab2b5729f20a3a95b074a7cd4d040e..01dd6c55e47d127a66284599b09cc62755661032 100644 (file)
--- a/man/systemd.offline-updates.xml
+++ b/man/systemd.offline-updates.xml
@@ -3,6 +3,8 @@
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
 <!--
+  SPDX-License-Identifier: LGPL-2.1+
+
   This file is part of systemd.
 
   Copyright 2013 Lennart Poettering
@@ -86,34 +88,44 @@
       </listitem>
 
       <listitem>
-        <para>The system now continues to boot into <filename>default.target</filename>, and thus
-        into <filename>system-update.target</filename>. This target pulls in the system update unit,
-        which starts the system update script after all file systems have been mounted.</para>
+        <para>The system now continues to boot into <filename>default.target</filename>, and
+        thus into <filename>system-update.target</filename>. This target pulls in all system
+        update units. Only one service should perform an update (see the next point), and all
+        the other ones should exit cleanly with a "success" return code and without doing
+        anything. Update services should be ordered after <filename>sysinit.target</filename>
+        so that the update starts after all file systems have been mounted.</para>
       </listitem>
 
       <listitem>
-        <para>As the first step, the update script should check if the
+        <para>As the first step, an update service should check if the
         <filename>/system-update</filename> symlink points to the location used by that update
-        script. In case it does not exists or points to a different location, the script must exit
+        service. In case it does not exist or points to a different location, the service must exit
         without error. It is possible for multiple update services to be installed, and for multiple
-        update scripts to be launched in parallel, and only the one that corresponds to the tool
+        update services to be launched in parallel, and only the one that corresponds to the tool
         that <emphasis>created</emphasis> the symlink before reboot should perform any actions. It
         is unsafe to run multiple updates in parallel.</para>
       </listitem>
 
       <listitem>
-        <para>The update script should now do its job. If applicable and possible, it should
-        create a file system snapshot, then install all packages.
-        After completion (regardless whether the update succeeded or failed) the machine
-        must be rebooted, for example by calling <command>systemctl reboot</command>.
-        In addition, on failure the script should revert to the old file system snapshot
-        (without the symlink).</para>
+        <para>The update service should now do its job. If applicable and possible, it should
+        create a file system snapshot, then install all packages.  After completion (regardless
+        whether the update succeeded or failed) the machine must be rebooted, for example by
+        calling <command>systemctl reboot</command>. In addition, on failure the script should
+        revert to the old file system snapshot (without the symlink).</para>
+      </listitem>
+
+      <listitem>
+        <para>The upgrade scripts should exit only after the update is finished. It is expected
+        that the service which performs the upgrade will cause the machine to reboot after it
+        is done. If the <filename>system-update.target</filename> is successfully reached, i.e.
+        all update services have run, and the <filename>/system-update</filename> symlink still
+        exists, it will be removed and the machine rebooted as a safety measure.</para>
       </listitem>
 
       <listitem>
-        <para>The system is rebooted. Since the <filename>/system-update</filename> symlink is gone,
-        the generator won't redirect <filename>default.target</filename> after reboot and the
-        system now boots into the default target again.</para>
+        <para>After a reboot, now that the <filename>/system-update</filename> symlink is gone,
+        the generator won't redirect <filename>default.target</filename> anymore and the system
+        now boots into the default target again.</para>
       </listitem>
     </orderedlist>
   </refsect1>
@@ -143,14 +155,15 @@
         <varname>FailureAction=</varname> makes sure that the specified unit is activated if your
         script exits uncleanly (by non-zero error code, or signal/coredump). If your script succeeds
         you should trigger the reboot in your own code, for example by invoking logind's
-        <command>Reboot()</command> call or calling <command>systemct reboot</command>. See
-        <ulink url="http://www.freedesktop.org/wiki/Software/systemd/logind">logind dbus API</ulink>
+        <command>Reboot()</command> call or calling <command>systemctl reboot</command>. See
+        <ulink url="https://www.freedesktop.org/wiki/Software/systemd/logind">logind dbus API</ulink>
         for details.</para>
       </listitem>
 
       <listitem>
         <para>The update service should declare <varname>DefaultDependencies=false</varname>,
-        and pull in any services it requires explicitly.</para>
+        <varname>Requires=sysinit.target</varname>, <varname>After=sysinit.target</varname>,
+        and explicitly pull in any other services it requires.</para>
       </listitem>
     </orderedlist>
   </refsect1>
@@ -159,7 +172,6 @@
     <title>See also</title>
 
     <para>
-      <ulink url="http://www.freedesktop.org/wiki/Software/systemd/SystemUpdates/">Implementing Offline System Updates</ulink>,
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,