systemd-sysupdate, systemd-sysupdate.service,
systemd-sysupdate.timer, systemd-sysupdate-reboot.service,
systemd-sysupdate-reboot.timer - Automatically Update OS or Other
Resources
systemd-sysupdate [OPTIONS...]
systemd-sysupdate.service
systemd-sysupdate atomically updates the host OS, container
images, portable service images or other sources, based on the transfer
configuration files described in sysupdate.d(5).
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 downloaded, unpacked, and prepared in an entirely separate
location, independently of the first, and — once complete — be
activated, swapping the roles so that it becomes the used one and the
previously used one becomes the one that is replaced by the next update, and
so on. The resources to update are defined 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.
The tool updates partitions, files or directory trees always in
whole, and operates with at least two versions of each of these resources:
the current version, plus the next 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.
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.
Note that when writing updates to a partition, the partition has
to exist already, as systemd-sysupdate will not automatically create
new partitions. Use a tool such as systemd-repart(8) to automatically
create additional partitions to be used with systemd-sysupdate on
boot.
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 --image= below. The latter is
particularly interesting to update container images or portable service
images.
The systemd-sysupdate.service system service will automatically
update the host OS based on the installed transfer files. It is triggered in
regular intervals via systemd-sysupdate.timer. The
systemd-sysupdate-reboot.service will automatically reboot the system after
a new version is installed. It is triggered via
systemd-sysupdate-reboot.timer. 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.
For details about transfer files and examples see
sysupdate.d(5).
The following commands are understood:
list [VERSION]
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.
If no command is explicitly specified this command is implied.
Added in version 251.
features [FEATURE]
If invoked without an argument, enumerates optional
features and shows a summarizing table, including which features are enabled
or disabled. If a feature argument is specified, shows details about the
specific feature, including the transfers that are controlled by the feature.
Added in version 257.
check-new
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
output.
Added in version 251.
update [VERSION]
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.
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 InstanceMax= in sysupdate.d(5), or via the
available partition slots of the right type. This implicit operation can
also be invoked explicitly via the vacuum command described
below.
Added in version 251.
vacuum
Deletes old installed versions until the limits
configured via
InstanceMax= in
sysupdate.d(5) are met again.
Normally, it should not be necessary to invoke this command explicitly, since
it is implicitly invoked whenever a new update is initiated.
Added in version 251.
pending
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
IMAGE_VERSION= field in /etc/os-release. If the
former is newer than the latter, an update was apparently completed but not
activated (i.e. rebooted into) yet.
Added in version 251.
reboot
Similar to the
pending 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
update command, after a completed update via the
--reboot
switch, see below. This command will execute no operation (and return success)
if no update has been installed, and thus the system was not rebooted.
Added in version 251.
components
Lists components that can be updated. This enumerates the
/etc/sysupdate.*.d/, /run/sysupdate.*.d/ and /usr/lib/sysupdate.*.d/
directories that contain transfer files. This command is useful to list
possible parameters for
--component= (see below).
Added in version 251.
-h, --help
Print a short help text and exit.
--version
Print a short version string and exit.
The following options are understood:
--component=, -C
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
/etc/sysupdate.d/*.conf, /run/sysupdate.d/*.conf and
/usr/lib/sysupdate.d/*.conf. If this switch is used, the specified component
name is used to alter the directories to look in to be
/etc/sysupdate.
component.d/*.conf,
/run/sysupdate.
component.d/*.conf and
/usr/lib/sysupdate.
component.d/*.conf, each time with the
component string replaced with the specified component name.
Use the components command to list available components to
update. This enumerates the directories matching this naming rule.
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
sysupdate.d/ directory for these cases.
This option may not be combined with --definitions=.
Added in version 251.
--definitions=
A path to a directory. If specified, the transfer *.conf
files are read from this directory instead of /usr/lib/sysupdate.d/*.conf,
/etc/sysupdate.d/*.conf, and /run/sysupdate.d/*.conf.
This option may not be combined with --component=.
Added in version 251.
--root=
Takes a path to a directory to use as root file system
when searching for sysupdate.d/*.conf files.
Added in version 251.
--image=
Takes a path to a disk image file or device to mount and
use in a similar fashion to
--root=, see above. If this is used and
partition resources are updated this is done inside the specified disk image.
Added in version 251.
--image-policy=policy
Takes an image policy string as argument, as per
systemd.image-policy(7). The policy is enforced when operating on the
disk image specified via --image=, see above. If not specified defaults
to the "*" policy, i.e. all recognized file systems in the image are
used.
--instances-max=, -m
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
InstancesMax= setting, see
sysupdate.d(5) for details.
Added in version 251.
--sync=
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
turned off, except to improve runtime performance in testing environments.
Added in version 251.
--verify=
Takes a boolean argument, defaults to yes. Controls
whether to cryptographically verify downloads. Do not turn this off, except in
testing environments.
Added in version 251.
--reboot
When used in combination with the
update command
and a new version is installed, automatically reboots the system immediately
afterwards.
Added in version 251.
--offline
Prevents fetching metadata from the network (i.e.
SHA256SUMS). This is most useful when used in combination with the
list
command, to query locally installed versions.
Added in version 257.
--transfer-source=
Takes a path as its argument. When specified, all
transfer sources configured with
PathRelativeTo=explicit will be
interpreted relative to the specified path.
Added in version 257.
--no-pager
Do not pipe output into a pager.
--no-legend
Do not print the legend, i.e. column headers and the
footer with hints.
--json=MODE
Shows output formatted as JSON. Expects one of
"short" (for the shortest possible output without any redundant
whitespace or line breaks), "pretty" (for a pretty version of the
same, with indentation and line breaks) or "off" (to turn off JSON
output, the default).
On success, 0 is returned, a non-zero failure code otherwise.
systemd(1), sysupdate.d(5),
systemd-sysupdated.service(8), systemd-repart(8)