# systemd-sysupdate

## NAME



           systemd-sysupdate, systemd-sysupdate.service, systemd-
           sysupdate.timer, systemd-sysupdate-reboot.service, systemd-
           sysupdate-reboot.timer - Automatically Update OS or Other
           Resources
    


## SYNOPSIS



    
           **systemd-sysupdate**[OPTIONS...]
    
           systemd-sysupdate.service
    


## DESCRIPTION



           **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).
    


## COMMAND



           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.
    


## OPTIONS



           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).
    


## EXIT STATUS



           On success, 0 is returned, a non-zero failure code otherwise.
    


* * *