man/systemd-sysupdate.xml

   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 -->
   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>
 105
 106         <xi:include href="version-info.xml" xpointer="v251"/></listitem>
 107       </varlistentry>
 108
 109       <varlistentry>
 110         <term><option>check-new</option></term>
 111
 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
 115         output.</para>
 116
 117         <xi:include href="version-info.xml" xpointer="v251"/></listitem>
 118       </varlistentry>
 119
 120       <varlistentry>
 121         <term><option>update</option> <optional><replaceable>VERSION</replaceable></optional></term>
 122
 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
 125         executed.</para>
 126
 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>
 132
 133         <xi:include href="version-info.xml" xpointer="v251"/></listitem>
 134       </varlistentry>
 135
 136       <varlistentry>
 137         <term><option>vacuum</option></term>
 138
 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>
 144
 145         <xi:include href="version-info.xml" xpointer="v251"/></listitem>
 146       </varlistentry>
 147
 148       <varlistentry>
 149         <term><option>pending</option></term>
 150
 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>
 156
 157         <xi:include href="version-info.xml" xpointer="v251"/></listitem>
 158       </varlistentry>
 159
 160       <varlistentry>
 161         <term><option>reboot</option></term>
 162
 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>
 168
 169         <xi:include href="version-info.xml" xpointer="v251"/></listitem>
 170       </varlistentry>
 171
 172       <varlistentry>
 173         <term><option>components</option></term>
 174
 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>
 179
 180         <xi:include href="version-info.xml" xpointer="v251"/></listitem>
 181       </varlistentry>
 182
 183       <xi:include href="standard-options.xml" xpointer="help" />
 184       <xi:include href="standard-options.xml" xpointer="version" />
 185     </variablelist>
 186   </refsect1>
 187
 188   <refsect1>
 189     <title>Options</title>
 190
 191     <para>The following options are understood:</para>
 192
 193     <variablelist>
 194
 195       <varlistentry>
 196         <term><option>--component=</option></term>
 197         <term><option>-C</option></term>
 198
 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>
 209
 210         <para>Use the <command>components</command> command to list available components to update. This enumerates
 211         the directories matching this naming rule.</para>
 212
 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>
 217
 218         <para>This option may not be combined with <option>--definitions=</option>.</para>
 219
 220         <xi:include href="version-info.xml" xpointer="v251"/></listitem>
 221       </varlistentry>
 222
 223       <varlistentry>
 224         <term><option>--definitions=</option></term>
 225
 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>
 229
 230         <para>This option may not be combined with <option>--component=</option>.</para>
 231
 232         <xi:include href="version-info.xml" xpointer="v251"/></listitem>
 233       </varlistentry>
 234
 235       <varlistentry>
 236         <term><option>--root=</option></term>
 237
 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>
 240
 241         <xi:include href="version-info.xml" xpointer="v251"/></listitem>
 242       </varlistentry>
 243
 244       <varlistentry>
 245         <term><option>--image=</option></term>
 246
 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>
 250
 251         <xi:include href="version-info.xml" xpointer="v251"/></listitem>
 252       </varlistentry>
 253
 254       <xi:include href="standard-options.xml" xpointer="image-policy-open" />
 255
 256       <varlistentry>
 257         <term><option>--instances-max=</option></term>
 258         <term><option>-m</option></term>
 259
 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
 264         details.</para>
 265
 266         <xi:include href="version-info.xml" xpointer="v251"/></listitem>
 267       </varlistentry>
 268
 269       <varlistentry>
 270         <term><option>--sync=</option></term>
 271
 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>
 276
 277         <xi:include href="version-info.xml" xpointer="v251"/></listitem>
 278       </varlistentry>
 279
 280       <varlistentry>
 281         <term><option>--verify=</option></term>
 282
 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>
 285
 286         <xi:include href="version-info.xml" xpointer="v251"/></listitem>
 287       </varlistentry>
 288
 289       <varlistentry>
 290         <term><option>--reboot</option></term>
 291
 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>
 294
 295         <xi:include href="version-info.xml" xpointer="v251"/></listitem>
 296       </varlistentry>
 297
 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" />
 301     </variablelist>
 302   </refsect1>
 303
 304   <refsect1>
 305     <title>Exit status</title>
 306
 307     <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
 308   </refsect1>
 309
 310   <refsect1>
 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>
 316     </simplelist></para>
 317   </refsect1>
 318
 319 </refentry>