|
HTML rendering created 2026-09-09 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | COMMAND | OPTIONS | EXIT STATUS | SEE ALSO | COLOPHON |
|
|
|
SYSTEMD-SYSUPDATE(8) systemd-sysupdate SYSTEMD-SYSUPDATE(8)
systemd-sysupdate, systemd-sysupdate-update.service, systemd-
sysupdate-update.timer, systemd-sysupdate-reboot.service, systemd-
sysupdate-reboot.timer, systemd-sysupdate-auto-enable.service,
systemd-sysupdate.service, systemd-sysupdate.timer - Automatically
Update OS or Other Resources
systemd-sysupdate [OPTIONS...]
systemd-sysupdate-update.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-update.service system service will
automatically update the host OS based on the installed transfer
files. It is triggered in regular intervals via
systemd-sysupdate-update.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.
The systemd-sysupdate-auto-enable.service system service
automatically enables all suggested components and all suggested
features of all components before each update. It is ordered
before and pulled in by systemd-sysupdate-update.service, and is
not enabled by default. Enable it if newly suggested components
and features shall be picked up automatically as they become
available, rather than requiring manual
enable-component/enable-feature invocations.
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.
enable-feature FEATURE..., disable-feature FEATURE...
Enables or disables the specified optional features. This
writes an Enabled= setting into a drop-in next to the feature
definition, see sysupdate.features(5) for details. The
features may be specified either as arguments or selected via
the --feature-all or --feature-suggested switches. Note that
this only changes the configuration: to actually download the
newly enabled transfers, or remove the disabled ones, invoke
update or vacuum afterwards.
Added in version 262.
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 [--offline] [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 --offline is specified, the update must already have been
acquired using acquire and, if so, this pre-acquired version
is the one which will be updated to.
Added in version 251.
acquire [VERSION]
Acquires (downloads) the specified version, ready to install
it. If no version is specified, the newest version available
is acquired. If the version is already installed or no newer
version is 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 260.
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.
enable-component COMPONENT..., disable-component COMPONENT...
Enables or disables the specified components. This writes an
Enabled= setting into a drop-in next to the component
definition. The components may be specified either as
arguments or selected via the --component=, --component-all or
--component-suggested switches.
Added in version 262.
cleanup
Removes orphaned files that were previously installed by a
transfer, but are no longer owned by any currently defined
transfer file. Whenever a resource is installed into the file
system, systemd-sysupdate records the target directory and the
matching pattern in an installation database below
/var/lib/systemd/sysupdate/. This command iterates through
these records, determines which files they match, and deletes
those that are no longer covered by any of the patterns of the
transfer files currently in place. This is useful to
garbage-collect files that used to be owned by a transfer file
that has since been modified, disabled or removed altogether
(for example because a component is no longer being updated).
By default only the selected component is processed (i.e. the
one selected via --component=, or the default one if none were
selected). Use --component-all to process all components known
to the installation database in a single invocation.
This operation only removes files that were installed into the
file system (i.e. resources of type "regular-file",
"directory" and "subvolume", see sysupdate.d(5)); it does not
touch partition-based resources.
Added in version 262.
-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=, nor with
the pending and reboot commands or the --reboot switch, which
only apply to the booted OS version.
Added in version 251.
--component-all, -A
Instead of operating on a single component, operate on all
known components (as well as the default, component-less
installation). This is supported for the update, acquire,
cleanup, enable-feature, disable-feature, enable-component and
disable-component commands; all other commands will fail if
this switch is used.
This option may not be combined with --component=.
Added in version 262.
--component-suggested, -S
Similar to --component-all, but operates only on the
components that are currently suggested for this system, as
determined by the Suggest= and SuggestOn...= settings in the
component definition files. This is supported for the
enable-component and disable-component commands. Both commands
operate on the same set of components, thus disable-component
undoes what enable-component did.
This option may not be combined with --component=.
In order to reconcile the system according to suggestions,
i.e., to also turn off the components that are not (or no
longer) suggested, first disable all components with
--component-all, then enable the suggested ones with this
switch. Note that this has wider consequences than the
equivalent reconciliation of optional features because
components are enabled by default, and a component counts as
not suggested unless Suggest= or one of the SuggestOn...=
settings says otherwise. Reconciling hence explicitly disables
every component that is not suggested, including components
that ship no *.component file at all. The default component is
not affected.
Added in version 262.
--feature-all, -a
Instead of operating on features specified on the command
line, operate on all optional features known to the selected
component(s). This is supported for the enable-feature and
disable-feature commands.
Added in version 262.
--feature-suggested, -s
Similar to --feature-all, but operates only on the optional
features that are currently suggested for this system, as
determined by the Suggest= and SuggestOn...= settings in the
feature definition files. This is supported for the
enable-feature and disable-feature commands. Both commands
operate on the same set of features, thus disable-feature
undoes what enable-feature did.
In order to reconcile the system according to suggestions,
i.e., to also turn off the features that are not (or no
longer) suggested, first disable all features with
--feature-all, then enable the suggested ones with this
switch.
Added in version 262.
--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 commands and a new
version is installed, automatically reboots the system
immediately afterwards. This switch may not be combined with
--component=, as it only applies to the booted OS version.
Added in version 251.
--cleanup=
Takes a boolean argument. When used in combination with the
update command, automatically performs the equivalent of the
cleanup command afterwards, removing any orphaned files that
are no longer covered by the patterns of the currently defined
transfer files. This is useful to garbage-collect files that
used to be owned by a transfer file that has since been
modified, disabled or removed. Defaults to off.
Added in version 262.
--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.
If used in combination with the update command, it allows
updates to be downloaded in advance (using acquire) and
installed later.
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), sysupdate.features(5),
sysupdate.components(5), systemd-sysupdated.service(8),
systemd-repart(8)
This page is part of the systemd (systemd system and service
manager) project. Information about the project can be found at
⟨http://www.freedesktop.org/wiki/Software/systemd⟩. If you have a
bug report for this manual page, see
⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩.
This page was obtained from the project's upstream Git repository
⟨https://github.com/systemd/systemd.git⟩ on 2026-08-04. (At that
time, the date of the most recent commit that was found in the
repository was 2026-08-03.) If you discover any rendering
problems in this HTML version of the page, or you believe there is
a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
man-pages@man7.org
systemd 262~devel SYSTEMD-SYSUPDATE(8)
Pages that refer to this page: bootctl(1), updatectl(1), org.freedesktop.sysupdate1(5), sysupdate.components(5), sysupdate.d(5), sysupdate.features(5), systemd.directives(7), systemd.index(7), systemd.v(7), systemd-sysupdated.service(8)
|
HTML rendering created 2026-09-09 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|