mirrors/systemd
0
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-11-27 04:03:36 +08:00
Code Issues Packages Projects Releases Wiki Activity
2ffc8b23f0
systemd/man/systemd-sysupdate.xml

340 lines
17 KiB
XML
Raw Normal View History

man: add sysupdate documentation
2021-07-05 23:55:58 +08:00
<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
man: use same version in public and system ident.
2023-12-25 22:48:33 +08:00
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
man: add sysupdate documentation
2021-07-05 23:55:58 +08:00
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
<refentry id="systemd-sysupdate" conditional='ENABLE_SYSUPDATE'
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>systemd-sysupdate</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>systemd-sysupdate</refentrytitle>
<manvolnum>8</manvolnum>
</refmeta>
<refnamediv>
<refname>systemd-sysupdate</refname>
<refname>systemd-sysupdate.service</refname>
<refname>systemd-sysupdate.timer</refname>
<refname>systemd-sysupdate-reboot.service</refname>
<refname>systemd-sysupdate-reboot.timer</refname>
<refpurpose>Automatically Update OS or Other Resources</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>systemd-sysupdate</command>
<arg choice="opt" rep="repeat">OPTIONS</arg>
</cmdsynopsis>
<para><filename>systemd-sysupdate.service</filename></para>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><command>systemd-sysupdate</command> atomically updates the host OS, container images, portable
service images or other sources, based on the transfer configuration files described in
<citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
<para>This tool implements file, directory, or partition based update schemes, supporting multiple
parallel installed versions of specific resources in an A/B (or even: A/B/C, A/B/C/D/, …) style. A/B
updating means that when one version of a resource is currently being used, the next version can be
man: fix sysupdate typos
2022-03-21 23:53:35 +08:00
downloaded, unpacked, and prepared in an entirely separate location, independently of the first, and — once
man: add sysupdate documentation
2021-07-05 23:55:58 +08:00
complete — be activated, swapping the roles so that it becomes the used one and the previously used one
man: fix sysupdate typos
2022-03-21 23:53:35 +08:00
becomes the one that is replaced by the next update, and so on. The resources to update are defined
man: add sysupdate documentation
2021-07-05 23:55:58 +08:00
in transfer files, one for each resource to be updated. For example, resources that may be updated with
this tool could be: a root file system partition, a matching Verity partition plus one kernel image. The
combination of the three would be considered a complete OS update.</para>
<para>The tool updates partitions, files or directory trees always in whole, and operates with at least
two versions of each of these resources: the <emphasis>current</emphasis> version, plus the
<emphasis>next</emphasis> version: the one that is being updated to, and which is initially incomplete as
the downloaded data is written to it; plus optionally more versions. Once the download of a newer version
is complete it becomes the current version, releasing the version previously considered current for
deletion/replacement/updating.</para>
<para>When installing new versions the tool will directly download, decompress, unpack and write the new
version into the destination. This is done in a robust fashion so that an incomplete download can be
recognized on next invocation, and flushed out before a new attempt is initiated.</para>
<para>Note that when writing updates to a partition, the partition has to exist already, as
<command>systemd-sysupdate</command> will not automatically create new partitions. Use a tool such as
<citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry> to
automatically create additional partitions to be used with <command>systemd-sysupdate</command> on
boot.</para>
<para>The tool can both be used on the running OS, to update the OS in "online" state from within itself,
and on "offline" disk images, to update them from the outside based on transfer files
embedded in the disk images. For the latter, see <option>--image=</option> below. The latter is
particularly interesting to update container images or portable service images.</para>
<para>The <filename>systemd-sysupdate.service</filename> system service will automatically update the
host OS based on the installed transfer files. It is triggered in regular intervals via
<filename>systemd-sysupdate.timer</filename>. The <filename>systemd-sysupdate-reboot.service</filename>
will automatically reboot the system after a new version is installed. It is triggered via
<filename>systemd-sysupdate-reboot.timer</filename>. The two services are separate from each other as it
is typically advisable to download updates regularly while the system is up, but delay reboots until the
appropriate time (i.e. typically at night). The two sets of service/timer units may be enabled
separately.</para>
<para>For details about transfer files and examples see
<citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
</refsect1>
<refsect1>
<title>Command</title>
<para>The following commands are understood:</para>
<variablelist>
<varlistentry>
<term><option>list</option> <optional><replaceable>VERSION</replaceable></optional></term>
<listitem><para>If invoked without an argument, enumerates downloadable and installed versions, and
shows a summarizing table with the discovered versions and their properties, including whether
there's a newer candidate version to update to. If a version argument is specified, shows details
about the specific version, including the individual files that need to be transferred to acquire the
version.</para>
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-23 00:52:36 +08:00
<para>If no command is explicitly specified this command is implied.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 23:55:58 +08:00
</varlistentry>
<varlistentry>
<term><option>check-new</option></term>
<listitem><para>Checks if there's a new version available. This internally enumerates downloadable and
installed versions and returns exit status 0 if there's a new version to update to, non-zero
otherwise. If there is a new version to update to, its version identifier is written to standard
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-23 00:52:36 +08:00
output.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 23:55:58 +08:00
</varlistentry>
<varlistentry>
<term><option>update</option> <optional><replaceable>VERSION</replaceable></optional></term>
<listitem><para>Installs (updates to) the specified version, or if none is specified to the newest
version available. If the version is already installed or no newer version available, no operation is
executed.</para>
<para>If a new version to install/update to is found, old installed versions are deleted until at
least one new version can be installed, as configured via <varname>InstanceMax=</varname> in
<citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, or
via the available partition slots of the right type. This implicit operation can also be invoked
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-23 00:52:36 +08:00
explicitly via the <command>vacuum</command> command described below.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 23:55:58 +08:00
</varlistentry>
<varlistentry>
<term><option>vacuum</option></term>
<listitem><para>Deletes old installed versions until the limits configured via
<varname>InstanceMax=</varname> in
<citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> are
met again. Normally, it should not be necessary to invoke this command explicitly, since it is
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-23 00:52:36 +08:00
implicitly invoked whenever a new update is initiated.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 23:55:58 +08:00
</varlistentry>
<varlistentry>
<term><option>pending</option></term>
<listitem><para>Checks whether a newer version of the OS is installed than the one currently
running. Returns zero if so, non-zero otherwise. This compares the newest installed version's
identifier with the OS image version as reported by the <varname>IMAGE_VERSION=</varname> field in
<filename>/etc/os-release</filename>. If the former is newer than the latter, an update was
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-23 00:52:36 +08:00
apparently completed but not activated (i.e. rebooted into) yet.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 23:55:58 +08:00
</varlistentry>
<varlistentry>
<term><option>reboot</option></term>
<listitem><para>Similar to the <option>pending</option> command but immediately reboots in case a
newer version of the OS has been installed than the one currently running. This operation can be done
implicitly together with the <command>update</command> command, after a completed update via the
<option>--reboot</option> switch, see below. This command will execute no operation (and return
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-23 00:52:36 +08:00
success) if no update has been installed, and thus the system was not rebooted.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 23:55:58 +08:00
</varlistentry>
<varlistentry>
<term><option>components</option></term>
<listitem><para>Lists components that can be updated. This enumerates the
<filename>/etc/sysupdate.*.d/</filename>, <filename>/run/sysupdate.*.d/</filename> and
<filename>/usr/lib/sysupdate.*.d/</filename> directories that contain transfer files. This command is
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-23 00:52:36 +08:00
useful to list possible parameters for <option>--component=</option> (see below).</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 23:55:58 +08:00
</varlistentry>
<xi:include href="standard-options.xml" xpointer="help" />
<xi:include href="standard-options.xml" xpointer="version" />
</variablelist>
</refsect1>
<refsect1>
<title>Options</title>
<para>The following options are understood:</para>
<variablelist>
<varlistentry>
<term><option>--component=</option></term>
<term><option>-C</option></term>
<listitem><para>Selects the component to update. Takes a component name as argument. This has the
effect of slightly altering the search logic for transfer files. If this switch is not used, the
transfer files are loaded from <filename>/etc/sysupdate.d/*.conf</filename>,
<filename>/run/sysupdate.d/*.conf</filename> and <filename>/usr/lib/sysupdate.d/*.conf</filename>. If
this switch is used, the specified component name is used to alter the directories to look in to be
<filename>/etc/sysupdate.<replaceable>component</replaceable>.d/*.conf</filename>,
<filename>/run/sysupdate.<replaceable>component</replaceable>.d/*.conf</filename> and
<filename>/usr/lib/sysupdate.<replaceable>component</replaceable>.d/*.conf</filename>, each time with
the <filename><replaceable>component</replaceable></filename> string replaced with the specified
component name.</para>
<para>Use the <command>components</command> command to list available components to update. This enumerates
the directories matching this naming rule.</para>
<para>Components may be used to define a separate set of transfer files for different components of
the OS that shall be updated separately. Do not use this concept for resources that shall always be
updated together in a synchronous fashion. Simply define multiple transfer files within the same
<filename>sysupdate.d/</filename> directory for these cases.</para>
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-23 00:52:36 +08:00
<para>This option may not be combined with <option>--definitions=</option>.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 23:55:58 +08:00
</varlistentry>
<varlistentry>
<term><option>--definitions=</option></term>
<listitem><para>A path to a directory. If specified, the transfer <filename>*.conf</filename> files
are read from this directory instead of <filename>/usr/lib/sysupdate.d/*.conf</filename>,
<filename>/etc/sysupdate.d/*.conf</filename>, and <filename>/run/sysupdate.d/*.conf</filename>.</para>
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-23 00:52:36 +08:00
<para>This option may not be combined with <option>--component=</option>.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 23:55:58 +08:00
</varlistentry>
<varlistentry>
<term><option>--root=</option></term>
<listitem><para>Takes a path to a directory to use as root file system when searching for
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-23 00:52:36 +08:00
<filename>sysupdate.d/*.conf</filename> files.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 23:55:58 +08:00
</varlistentry>
<varlistentry>
<term><option>--image=</option></term>
<listitem><para>Takes a path to a disk image file or device to mount and use in a similar fashion to
<option>--root=</option>, see above. If this is used and partition resources are updated this is done
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-23 00:52:36 +08:00
inside the specified disk image.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 23:55:58 +08:00
</varlistentry>
man: document image policy syntax and semantics, and the hooks in the various components
2022-12-02 05:41:47 +08:00
<xi:include href="standard-options.xml" xpointer="image-policy-open" />
man: add sysupdate documentation
2021-07-05 23:55:58 +08:00
<varlistentry>
<term><option>--instances-max=</option></term>
<term><option>-m</option></term>
sysupdate: Check that --instances-max is in bounds Otherwise user can pass in --instances-max=0 and crash sysupdate with an assertion failure.
2024-06-22 08:49:48 +08:00
<listitem><para>Takes a decimal integer greater than or equal to 2 while updating or 1 while vacuuming.
Controls how many versions to keep at any time. This option may also be configured inside the transfer
files, via the <varname>InstancesMax=</varname> setting, see
man: add sysupdate documentation
2021-07-05 23:55:58 +08:00
<citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-23 00:52:36 +08:00
details.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 23:55:58 +08:00
</varlistentry>
<varlistentry>
<term><option>--sync=</option></term>
<listitem><para>Takes a boolean argument, defaults to yes. This may be used to specify whether the
newly updated resource versions shall be synchronized to disk when appropriate (i.e. after the
download is complete, before it is finalized, and again after finalization). This should not be
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-23 00:52:36 +08:00
turned off, except to improve runtime performance in testing environments.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 23:55:58 +08:00
</varlistentry>
<varlistentry>
<term><option>--verify=</option></term>
<listitem><para>Takes a boolean argument, defaults to yes. Controls whether to cryptographically
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-23 00:52:36 +08:00
verify downloads. Do not turn this off, except in testing environments.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 23:55:58 +08:00
</varlistentry>
<varlistentry>
<term><option>--reboot</option></term>
<listitem><para>When used in combination with the <command>update</command> command and a new version is
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-23 00:52:36 +08:00
installed, automatically reboots the system immediately afterwards.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: add sysupdate documentation
2021-07-05 23:55:58 +08:00
</varlistentry>
sysupdate: Add --offline mode This prevents sysupdate from going out to the network to enumerate available instances. When combined with the list command, this lets us query installed instances
2023-07-12 06:35:54 +08:00
<varlistentry>
<term><option>--offline</option></term>
<listitem><para>Prevents fetching metadata from the network (i.e. <filename>SHA256SUMS</filename>).
This is most useful when used in combination with the <command>list</command> command, to query
locally installed versions.</para>
sysupdate: Add --transfer-source= In mkosi, I want to add a sysupdate verb to wrap systemd-sysupdate. The definitions will be picked up from mkosi.sysupdate/ and passed to systemd-sysupdate. I want users to be able to write transfer definitions that are independent of the output directory used by mkosi. To make this possible, it should be possible to specify the directory that transfer sources should be looked up in on the sysupdate command line. Let's allow this via a new --transfer-source= option. Additionally, transfer sources that want to take advantage of this feature should specify PathRelativeTo=directory to indicate the configured Path= is interpreted relative to the tranfer source directory specified on the CLI. This allows for the following transfer definition to be put in mkosi.sysupdate: """ [Transfer] ProtectVersion=%A [Source] Type=regular-file Path=/ PathRelativeTo=directory MatchPattern=ParticleOS_@v.usr-%a.@u.raw [Target] Type=partition Path=auto MatchPattern=ParticleOS_@v MatchPartitionType=usr PartitionFlags=0 ReadOnly=1 """
2024-09-08 22:09:19 +08:00
<xi:include href="version-info.xml" xpointer="v257"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--transfer-source=</option></term>
<listitem><para>Takes a path as its argument. When specified, all transfer sources configured with
<varname>PathRelativeTo=explicit</varname> will be interpreted relative to the specified path.</para>
sysupdate: Add --offline mode This prevents sysupdate from going out to the network to enumerate available instances. When combined with the list command, this lets us query installed instances
2023-07-12 06:35:54 +08:00
<xi:include href="version-info.xml" xpointer="v257"/></listitem>
</varlistentry>
man: add sysupdate documentation
2021-07-05 23:55:58 +08:00
<xi:include href="standard-options.xml" xpointer="no-pager" />
<xi:include href="standard-options.xml" xpointer="no-legend" />
<xi:include href="standard-options.xml" xpointer="json" />
</variablelist>
</refsect1>
<refsect1>
<title>Exit status</title>
<para>On success, 0 is returned, a non-zero failure code otherwise.</para>
</refsect1>
<refsect1>
<title>See Also</title>
man: use <simplelist> for 'See also' sections This is just a slight markup improvement; there should be no difference in rendering.
2023-12-23 02:09:32 +08:00
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
sysupdate: Implement systemd-sysupdated dbus service Co-authored-by: Tom Coldrick <thomas.coldrick@codethink.co.uk> Co-authored-by: Abderrahim Kitouni <abderrahim.kitouni@codethink.co.uk>
2023-06-30 10:58:41 +08:00
<member><citerefentry><refentrytitle>systemd-sysupdated.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
man: use <simplelist> for 'See also' sections This is just a slight markup improvement; there should be no difference in rendering.
2023-12-23 02:09:32 +08:00
<member><citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
</simplelist></para>
man: add sysupdate documentation
2021-07-05 23:55:58 +08:00
</refsect1>
</refentry>
Reference in New Issue Copy Permalink