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.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       <xi:include href="standard-options.xml" xpointer="image-policy-open" />
 233
 234       <varlistentry>
 235         <term><option>--instances-max=</option></term>
 236         <term><option>-m</option></term>
 237
 238         <listitem><para>Takes a decimal integer greater than or equal to 2. Controls how many versions to
 239         keep at any time. This option may also be configured inside the transfer files, via the
 240         <varname>InstancesMax=</varname> setting, see
 241         <citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 242         details.</para></listitem>
 243       </varlistentry>
 244
 245       <varlistentry>
 246         <term><option>--sync=</option></term>
 247
 248         <listitem><para>Takes a boolean argument, defaults to yes. This may be used to specify whether the
 249         newly updated resource versions shall be synchronized to disk when appropriate (i.e. after the
 250         download is complete, before it is finalized, and again after finalization). This should not be
 251         turned off, except to improve runtime performance in testing environments.</para></listitem>
 252       </varlistentry>
 253
 254       <varlistentry>
 255         <term><option>--verify=</option></term>
 256
 257         <listitem><para>Takes a boolean argument, defaults to yes. Controls whether to cryptographically
 258         verify downloads. Do not turn this off, except in testing environments.</para></listitem>
 259       </varlistentry>
 260
 261       <varlistentry>
 262         <term><option>--reboot</option></term>
 263
 264         <listitem><para>When used in combination with the <command>update</command> command and a new version is
 265         installed, automatically reboots the system immediately afterwards.</para></listitem>
 266       </varlistentry>
 267
 268       <xi:include href="standard-options.xml" xpointer="no-pager" />
 269       <xi:include href="standard-options.xml" xpointer="no-legend" />
 270       <xi:include href="standard-options.xml" xpointer="json" />
 271     </variablelist>
 272   </refsect1>
 273
 274   <refsect1>
 275     <title>Exit status</title>
 276
 277     <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
 278   </refsect1>
 279
 280   <refsect1>
 281     <title>See Also</title>
 282     <para>
 283       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 284       <citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 285       <citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 286     </para>
 287   </refsect1>
 288
 289 </refentry>