<?xml version='1.0'?> <!--*-nxml-*-->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-
-<!--
- This file is part of systemd.
-
- Copyright 2013 Lennart Poettering
- Copyright 2016 Zbigniew Jędrzejewski-Szmek
-
- systemd is free software; you can redistribute it and/or modify it
- under the terms of the GNU Lesser General Public License as published by
- the Free Software Foundation; either version 2.1 of the License, or
- (at your option) any later version.
-
- systemd is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- Lesser General Public License for more details.
-
- You should have received a copy of the GNU Lesser General Public License
- along with systemd; If not, see <http://www.gnu.org/licenses/>.
--->
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="systemd.offline-updates">
<refentryinfo>
<title>systemd.offline-updates</title>
<productname>systemd</productname>
-
- <authorgroup>
- <author>
- <contrib>Developer</contrib>
- <firstname>Lennart</firstname>
- <surname>Poettering</surname>
- <email>lennart@poettering.net</email>
- </author>
- </authorgroup>
</refentryinfo>
<refmeta>
<listitem>
<para>Very early in the new boot
- <citerefentry><refentrytitle>systemd-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
checks whether <filename>/system-update</filename> exists. If so, it (temporarily and for
this boot only) redirects (i.e. symlinks) <filename>default.target</filename> to
- <filename>system-update.target</filename>, a special target that is pulls in the base system
+ <filename>system-update.target</filename>, a special target that pulls in the base system
(i.e. <filename>sysinit.target</filename>, so that all file systems are mounted but little
else) and the system update units.</para>
</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 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>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>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>
<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>
+ <para>The update service should declare <varname>DefaultDependencies=no</varname>,
+ <varname>Requires=sysinit.target</varname>, <varname>After=sysinit.target</varname>,
+ <varname>After=system-update-pre.target</varname>, <varname>Before=system-update.target</varname>
+ and explicitly pull in any other services it requires.</para>
+ </listitem>
+
+ <listitem>
+ <para>It may be desirable to always run an auxiliary unit when booting
+ into offline-updates mode, which itself does not install updates. To
+ do this create a .service file with
+ <varname>Wants=system-update-pre.target</varname> and
+ <varname>Before=system-update-pre.target</varname> and add a symlink
+ to that file under
+ <filename noindex='true'>/usr/lib/systemd/system-update.target.wants</filename>
+ .</para>
</listitem>
</orderedlist>
</refsect1>
<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-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>dnf.plugin.system-upgrade</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <citerefentry project='mankier'><refentrytitle>dnf.plugin.system-upgrade</refentrytitle><manvolnum>8</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>
projects / thirdparty / systemd.git / blobdiff