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.2/docbookx.dtd"> 4<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> 5 6<refentry id="systemd-sysupdate" conditional='ENABLE_SYSUPDATE' 7 xmlns:xi="http://www.w3.org/2001/XInclude"> 8 9 <refentryinfo> 10 <title>systemd-sysupdate</title> 11 <productname>systemd</productname> 12 </refentryinfo> 13 14 <refmeta> 15 <refentrytitle>systemd-sysupdate</refentrytitle> 16 <manvolnum>8</manvolnum> 17 </refmeta> 18 19 <refnamediv> 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> 26 </refnamediv> 27 28 <refsynopsisdiv> 29 <cmdsynopsis> 30 <command>systemd-sysupdate</command> 31 <arg choice="opt" rep="repeat">OPTIONS</arg> 32 </cmdsynopsis> 33 34 <para><filename>systemd-sysupdate.service</filename></para> 35 </refsynopsisdiv> 36 37 <refsect1> 38 <title>Description</title> 39 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> 43 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> 53 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> 60 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> 64 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 69 boot.</para> 70 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> 75 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 83 separately.</para> 84 85 <para>For details about transfer files and examples see 86 <citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> 87 </refsect1> 88 89 <refsect1> 90 <title>Command</title> 91 92 <para>The following commands are understood:</para> 93 94 <variablelist> 95 <varlistentry> 96 <term><option>list</option> <optional><replaceable>VERSION</replaceable></optional></term> 97 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 102 version.</para> 103 104 <para>If no command is explicitly specified this command is implied.</para></listitem> 105 </varlistentry> 106 107 <varlistentry> 108 <term><option>check-new</option></term> 109 110 <listitem><para>Checks if there's a new version available. This internally enumerates downloadable and 111 installed versions and returns exit status 0 if there's a new version to update to, non-zero 112 otherwise. If there is a new version to update to, its version identifier is written to standard 113 output.</para></listitem> 114 </varlistentry> 115 116 <varlistentry> 117 <term><option>update</option> <optional><replaceable>VERSION</replaceable></optional></term> 118 119 <listitem><para>Installs (updates to) the specified version, or if none is specified to the newest 120 version available. If the version is already installed or no newer version available, no operation is 121 executed.</para> 122 123 <para>If a new version to install/update to is found, old installed versions are deleted until at 124 least one new version can be installed, as configured via <varname>InstanceMax=</varname> in 125 <citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, or 126 via the available partition slots of the right type. This implicit operation can also be invoked 127 explicitly via the <command>vacuum</command> command described below.</para></listitem> 128 </varlistentry> 129 130 <varlistentry> 131 <term><option>vacuum</option></term> 132 133 <listitem><para>Deletes old installed versions until the limits configured via 134 <varname>InstanceMax=</varname> in 135 <citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> are 136 met again. Normally, it should not be necessary to invoke this command explicitly, since it is 137 implicitly invoked whenever a new update is initiated.</para></listitem> 138 </varlistentry> 139 140 <varlistentry> 141 <term><option>pending</option></term> 142 143 <listitem><para>Checks whether a newer version of the OS is installed than the one currently 144 running. Returns zero if so, non-zero otherwise. This compares the newest installed version's 145 identifier with the OS image version as reported by the <varname>IMAGE_VERSION=</varname> field in 146 <filename>/etc/os-release</filename>. If the former is newer than the latter, an update was 147 apparently completed but not activated (i.e. rebooted into) yet.</para></listitem> 148 </varlistentry> 149 150 <varlistentry> 151 <term><option>reboot</option></term> 152 153 <listitem><para>Similar to the <option>pending</option> command but immediately reboots in case a 154 newer version of the OS has been installed than the one currently running. This operation can be done 155 implicitly together with the <command>update</command> command, after a completed update via the 156 <option>--reboot</option> switch, see below. This command will execute no operation (and return 157 success) if no update has been installed, and thus the system was not rebooted.</para></listitem> 158 </varlistentry> 159 160 <varlistentry> 161 <term><option>components</option></term> 162 163 <listitem><para>Lists components that can be updated. This enumerates the 164 <filename>/etc/sysupdate.*.d/</filename>, <filename>/run/sysupdate.*.d/</filename> and 165 <filename>/usr/lib/sysupdate.*.d/</filename> directories that contain transfer files. This command is 166 useful to list possible parameters for <option>--component=</option> (see below).</para></listitem> 167 </varlistentry> 168 169 <xi:include href="standard-options.xml" xpointer="help" /> 170 <xi:include href="standard-options.xml" xpointer="version" /> 171 </variablelist> 172 </refsect1> 173 174 <refsect1> 175 <title>Options</title> 176 177 <para>The following options are understood:</para> 178 179 <variablelist> 180 181 <varlistentry> 182 <term><option>--component=</option></term> 183 <term><option>-C</option></term> 184 185 <listitem><para>Selects the component to update. Takes a component name as argument. This has the 186 effect of slightly altering the search logic for transfer files. If this switch is not used, the 187 transfer files are loaded from <filename>/etc/sysupdate.d/*.conf</filename>, 188 <filename>/run/sysupdate.d/*.conf</filename> and <filename>/usr/lib/sysupdate.d/*.conf</filename>. If 189 this switch is used, the specified component name is used to alter the directories to look in to be 190 <filename>/etc/sysupdate.<replaceable>component</replaceable>.d/*.conf</filename>, 191 <filename>/run/sysupdate.<replaceable>component</replaceable>.d/*.conf</filename> and 192 <filename>/usr/lib/sysupdate.<replaceable>component</replaceable>.d/*.conf</filename>, each time with 193 the <filename><replaceable>component</replaceable></filename> string replaced with the specified 194 component name.</para> 195 196 <para>Use the <command>components</command> command to list available components to update. This enumerates 197 the directories matching this naming rule.</para> 198 199 <para>Components may be used to define a separate set of transfer files for different components of 200 the OS that shall be updated separately. Do not use this concept for resources that shall always be 201 updated together in a synchronous fashion. Simply define multiple transfer files within the same 202 <filename>sysupdate.d/</filename> directory for these cases.</para> 203 204 <para>This option may not be combined with <option>--definitions=</option>.</para></listitem> 205 </varlistentry> 206 207 <varlistentry> 208 <term><option>--definitions=</option></term> 209 210 <listitem><para>A path to a directory. If specified, the transfer <filename>*.conf</filename> files 211 are read from this directory instead of <filename>/usr/lib/sysupdate.d/*.conf</filename>, 212 <filename>/etc/sysupdate.d/*.conf</filename>, and <filename>/run/sysupdate.d/*.conf</filename>.</para> 213 214 <para>This option may not be combined with <option>--component=</option>.</para></listitem> 215 </varlistentry> 216 217 <varlistentry> 218 <term><option>--root=</option></term> 219 220 <listitem><para>Takes a path to a directory to use as root file system when searching for 221 <filename>sysupdate.d/*.conf</filename> files.</para></listitem> 222 </varlistentry> 223 224 <varlistentry> 225 <term><option>--image=</option></term> 226 227 <listitem><para>Takes a path to a disk image file or device to mount and use in a similar fashion to 228 <option>--root=</option>, see above. If this is used and partition resources are updated this is done 229 inside the specified disk image.</para></listitem> 230 </varlistentry> 231 232 <varlistentry> 233 <term><option>--instances-max=</option></term> 234 <term><option>-m</option></term> 235 236 <listitem><para>Takes a decimal integer greater than or equal to 2. Controls how many versions to 237 keep at any time. This option may also be configured inside the transfer files, via the 238 <varname>InstancesMax=</varname> setting, see 239 <citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> for 240 details.</para></listitem> 241 </varlistentry> 242 243 <varlistentry> 244 <term><option>--sync=</option></term> 245 246 <listitem><para>Takes a boolean argument, defaults to yes. This may be used to specify whether the 247 newly updated resource versions shall be synchronized to disk when appropriate (i.e. after the 248 download is complete, before it is finalized, and again after finalization). This should not be 249 turned off, except to improve runtime performance in testing environments.</para></listitem> 250 </varlistentry> 251 252 <varlistentry> 253 <term><option>--verify=</option></term> 254 255 <listitem><para>Takes a boolean argument, defaults to yes. Controls whether to cryptographically 256 verify downloads. Do not turn this off, except in testing environments.</para></listitem> 257 </varlistentry> 258 259 <varlistentry> 260 <term><option>--reboot</option></term> 261 262 <listitem><para>When used in combination with the <command>update</command> command and a new version is 263 installed, automatically reboots the system immediately afterwards.</para></listitem> 264 </varlistentry> 265 266 <xi:include href="standard-options.xml" xpointer="no-pager" /> 267 <xi:include href="standard-options.xml" xpointer="no-legend" /> 268 <xi:include href="standard-options.xml" xpointer="json" /> 269 </variablelist> 270 </refsect1> 271 272 <refsect1> 273 <title>Exit status</title> 274 275 <para>On success, 0 is returned, a non-zero failure code otherwise.</para> 276 </refsect1> 277 278 <refsect1> 279 <title>See Also</title> 280 <para> 281 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 282 <citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, 283 <citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry> 284 </para> 285 </refsect1> 286 287</refentry> 288