1 <?xml version='
1.0'
?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
6 <refentry id=
"systemd-sysupdate" conditional='ENABLE_SYSUPDATE'
7 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
10 <title>systemd-sysupdate
</title>
11 <productname>systemd
</productname>
15 <refentrytitle>systemd-sysupdate
</refentrytitle>
16 <manvolnum>8</manvolnum>
20 <refname>systemd-sysupdate
</refname>
21 <refname>systemd-sysupdate.service
</refname>
22 <refname>systemd-sysupdate.timer
</refname>
23 <refname>systemd-sysupdate-reboot.service
</refname>
24 <refname>systemd-sysupdate-reboot.timer
</refname>
25 <refpurpose>Automatically Update OS or Other Resources
</refpurpose>
30 <command>systemd-sysupdate
</command>
31 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
34 <para><filename>systemd-sysupdate.service
</filename></para>
38 <title>Description
</title>
40 <para><command>systemd-sysupdate
</command> atomically updates the host OS, container images, portable
41 service images or other sources, based on the transfer configuration files described in
42 <citerefentry><refentrytitle>sysupdate.d
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
44 <para>This tool implements file, directory, or partition based update schemes, supporting multiple
45 parallel installed versions of specific resources in an A/B (or even: A/B/C, A/B/C/D/, …) style. A/B
46 updating means that when one version of a resource is currently being used, the next version can be
47 downloaded, unpacked, and prepared in an entirely separate location, independently of the first, and — once
48 complete — be activated, swapping the roles so that it becomes the used one and the previously used one
49 becomes the one that is replaced by the next update, and so on. The resources to update are defined
50 in transfer files, one for each resource to be updated. For example, resources that may be updated with
51 this tool could be: a root file system partition, a matching Verity partition plus one kernel image. The
52 combination of the three would be considered a complete OS update.
</para>
54 <para>The tool updates partitions, files or directory trees always in whole, and operates with at least
55 two versions of each of these resources: the
<emphasis>current
</emphasis> version, plus the
56 <emphasis>next
</emphasis> version: the one that is being updated to, and which is initially incomplete as
57 the downloaded data is written to it; plus optionally more versions. Once the download of a newer version
58 is complete it becomes the current version, releasing the version previously considered current for
59 deletion/replacement/updating.
</para>
61 <para>When installing new versions the tool will directly download, decompress, unpack and write the new
62 version into the destination. This is done in a robust fashion so that an incomplete download can be
63 recognized on next invocation, and flushed out before a new attempt is initiated.
</para>
65 <para>Note that when writing updates to a partition, the partition has to exist already, as
66 <command>systemd-sysupdate
</command> will not automatically create new partitions. Use a tool such as
67 <citerefentry><refentrytitle>systemd-repart
</refentrytitle><manvolnum>8</manvolnum></citerefentry> to
68 automatically create additional partitions to be used with
<command>systemd-sysupdate
</command> on
71 <para>The tool can both be used on the running OS, to update the OS in
"online" state from within itself,
72 and on
"offline" disk images, to update them from the outside based on transfer files
73 embedded in the disk images. For the latter, see
<option>--image=
</option> below. The latter is
74 particularly interesting to update container images or portable service images.
</para>
76 <para>The
<filename>systemd-sysupdate.service
</filename> system service will automatically update the
77 host OS based on the installed transfer files. It is triggered in regular intervals via
78 <filename>systemd-sysupdate.timer
</filename>. The
<filename>systemd-sysupdate-reboot.service
</filename>
79 will automatically reboot the system after a new version is installed. It is triggered via
80 <filename>systemd-sysupdate-reboot.timer
</filename>. The two services are separate from each other as it
81 is typically advisable to download updates regularly while the system is up, but delay reboots until the
82 appropriate time (i.e. typically at night). The two sets of service/timer units may be enabled
85 <para>For details about transfer files and examples see
86 <citerefentry><refentrytitle>sysupdate.d
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
90 <title>Command
</title>
92 <para>The following commands are understood:
</para>
96 <term><option>list
</option> <optional><replaceable>VERSION
</replaceable></optional></term>
98 <listitem><para>If invoked without an argument, enumerates downloadable and installed versions, and
99 shows a summarizing table with the discovered versions and their properties, including whether
100 there's a newer candidate version to update to. If a version argument is specified, shows details
101 about the specific version, including the individual files that need to be transferred to acquire the
104 <para>If no command is explicitly specified this command is implied.
</para>
106 <xi:include href=
"version-info.xml" xpointer=
"v251"/></listitem>
110 <term><option>check-new
</option></term>
112 <listitem><para>Checks if there's a new version available. This internally enumerates downloadable and
113 installed versions and returns exit status
0 if there's a new version to update to, non-zero
114 otherwise. If there is a new version to update to, its version identifier is written to standard
117 <xi:include href=
"version-info.xml" xpointer=
"v251"/></listitem>
121 <term><option>update
</option> <optional><replaceable>VERSION
</replaceable></optional></term>
123 <listitem><para>Installs (updates to) the specified version, or if none is specified to the newest
124 version available. If the version is already installed or no newer version available, no operation is
127 <para>If a new version to install/update to is found, old installed versions are deleted until at
128 least one new version can be installed, as configured via
<varname>InstanceMax=
</varname> in
129 <citerefentry><refentrytitle>sysupdate.d
</refentrytitle><manvolnum>5</manvolnum></citerefentry>, or
130 via the available partition slots of the right type. This implicit operation can also be invoked
131 explicitly via the
<command>vacuum
</command> command described below.
</para>
133 <xi:include href=
"version-info.xml" xpointer=
"v251"/></listitem>
137 <term><option>vacuum
</option></term>
139 <listitem><para>Deletes old installed versions until the limits configured via
140 <varname>InstanceMax=
</varname> in
141 <citerefentry><refentrytitle>sysupdate.d
</refentrytitle><manvolnum>5</manvolnum></citerefentry> are
142 met again. Normally, it should not be necessary to invoke this command explicitly, since it is
143 implicitly invoked whenever a new update is initiated.
</para>
145 <xi:include href=
"version-info.xml" xpointer=
"v251"/></listitem>
149 <term><option>pending
</option></term>
151 <listitem><para>Checks whether a newer version of the OS is installed than the one currently
152 running. Returns zero if so, non-zero otherwise. This compares the newest installed version's
153 identifier with the OS image version as reported by the
<varname>IMAGE_VERSION=
</varname> field in
154 <filename>/etc/os-release
</filename>. If the former is newer than the latter, an update was
155 apparently completed but not activated (i.e. rebooted into) yet.
</para>
157 <xi:include href=
"version-info.xml" xpointer=
"v251"/></listitem>
161 <term><option>reboot
</option></term>
163 <listitem><para>Similar to the
<option>pending
</option> command but immediately reboots in case a
164 newer version of the OS has been installed than the one currently running. This operation can be done
165 implicitly together with the
<command>update
</command> command, after a completed update via the
166 <option>--reboot
</option> switch, see below. This command will execute no operation (and return
167 success) if no update has been installed, and thus the system was not rebooted.
</para>
169 <xi:include href=
"version-info.xml" xpointer=
"v251"/></listitem>
173 <term><option>components
</option></term>
175 <listitem><para>Lists components that can be updated. This enumerates the
176 <filename>/etc/sysupdate.*.d/
</filename>,
<filename>/run/sysupdate.*.d/
</filename> and
177 <filename>/usr/lib/sysupdate.*.d/
</filename> directories that contain transfer files. This command is
178 useful to list possible parameters for
<option>--component=
</option> (see below).
</para>
180 <xi:include href=
"version-info.xml" xpointer=
"v251"/></listitem>
183 <xi:include href=
"standard-options.xml" xpointer=
"help" />
184 <xi:include href=
"standard-options.xml" xpointer=
"version" />
189 <title>Options
</title>
191 <para>The following options are understood:
</para>
196 <term><option>--component=
</option></term>
197 <term><option>-C
</option></term>
199 <listitem><para>Selects the component to update. Takes a component name as argument. This has the
200 effect of slightly altering the search logic for transfer files. If this switch is not used, the
201 transfer files are loaded from
<filename>/etc/sysupdate.d/*.conf
</filename>,
202 <filename>/run/sysupdate.d/*.conf
</filename> and
<filename>/usr/lib/sysupdate.d/*.conf
</filename>. If
203 this switch is used, the specified component name is used to alter the directories to look in to be
204 <filename>/etc/sysupdate.
<replaceable>component
</replaceable>.d/*.conf
</filename>,
205 <filename>/run/sysupdate.
<replaceable>component
</replaceable>.d/*.conf
</filename> and
206 <filename>/usr/lib/sysupdate.
<replaceable>component
</replaceable>.d/*.conf
</filename>, each time with
207 the
<filename><replaceable>component
</replaceable></filename> string replaced with the specified
208 component name.
</para>
210 <para>Use the
<command>components
</command> command to list available components to update. This enumerates
211 the directories matching this naming rule.
</para>
213 <para>Components may be used to define a separate set of transfer files for different components of
214 the OS that shall be updated separately. Do not use this concept for resources that shall always be
215 updated together in a synchronous fashion. Simply define multiple transfer files within the same
216 <filename>sysupdate.d/
</filename> directory for these cases.
</para>
218 <para>This option may not be combined with
<option>--definitions=
</option>.
</para>
220 <xi:include href=
"version-info.xml" xpointer=
"v251"/></listitem>
224 <term><option>--definitions=
</option></term>
226 <listitem><para>A path to a directory. If specified, the transfer
<filename>*.conf
</filename> files
227 are read from this directory instead of
<filename>/usr/lib/sysupdate.d/*.conf
</filename>,
228 <filename>/etc/sysupdate.d/*.conf
</filename>, and
<filename>/run/sysupdate.d/*.conf
</filename>.
</para>
230 <para>This option may not be combined with
<option>--component=
</option>.
</para>
232 <xi:include href=
"version-info.xml" xpointer=
"v251"/></listitem>
236 <term><option>--root=
</option></term>
238 <listitem><para>Takes a path to a directory to use as root file system when searching for
239 <filename>sysupdate.d/*.conf
</filename> files.
</para>
241 <xi:include href=
"version-info.xml" xpointer=
"v251"/></listitem>
245 <term><option>--image=
</option></term>
247 <listitem><para>Takes a path to a disk image file or device to mount and use in a similar fashion to
248 <option>--root=
</option>, see above. If this is used and partition resources are updated this is done
249 inside the specified disk image.
</para>
251 <xi:include href=
"version-info.xml" xpointer=
"v251"/></listitem>
254 <xi:include href=
"standard-options.xml" xpointer=
"image-policy-open" />
257 <term><option>--instances-max=
</option></term>
258 <term><option>-m
</option></term>
260 <listitem><para>Takes a decimal integer greater than or equal to
2. Controls how many versions to
261 keep at any time. This option may also be configured inside the transfer files, via the
262 <varname>InstancesMax=
</varname> setting, see
263 <citerefentry><refentrytitle>sysupdate.d
</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
266 <xi:include href=
"version-info.xml" xpointer=
"v251"/></listitem>
270 <term><option>--sync=
</option></term>
272 <listitem><para>Takes a boolean argument, defaults to yes. This may be used to specify whether the
273 newly updated resource versions shall be synchronized to disk when appropriate (i.e. after the
274 download is complete, before it is finalized, and again after finalization). This should not be
275 turned off, except to improve runtime performance in testing environments.
</para>
277 <xi:include href=
"version-info.xml" xpointer=
"v251"/></listitem>
281 <term><option>--verify=
</option></term>
283 <listitem><para>Takes a boolean argument, defaults to yes. Controls whether to cryptographically
284 verify downloads. Do not turn this off, except in testing environments.
</para>
286 <xi:include href=
"version-info.xml" xpointer=
"v251"/></listitem>
290 <term><option>--reboot
</option></term>
292 <listitem><para>When used in combination with the
<command>update
</command> command and a new version is
293 installed, automatically reboots the system immediately afterwards.
</para>
295 <xi:include href=
"version-info.xml" xpointer=
"v251"/></listitem>
298 <xi:include href=
"standard-options.xml" xpointer=
"no-pager" />
299 <xi:include href=
"standard-options.xml" xpointer=
"no-legend" />
300 <xi:include href=
"standard-options.xml" xpointer=
"json" />
305 <title>Exit status
</title>
307 <para>On success,
0 is returned, a non-zero failure code otherwise.
</para>
311 <title>See Also
</title>
312 <para><simplelist type=
"inline">
313 <member><citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
314 <member><citerefentry><refentrytitle>sysupdate.d
</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
315 <member><citerefentry><refentrytitle>systemd-repart
</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>