From b750101eb236130cf056c675997decbac904cc49 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 17:35:18 +0200 Subject: Adding upstream version 252.22. Signed-off-by: Daniel Baumann --- man/systemd-sysupdate.xml | 287 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 287 insertions(+) create mode 100644 man/systemd-sysupdate.xml (limited to 'man/systemd-sysupdate.xml') diff --git a/man/systemd-sysupdate.xml b/man/systemd-sysupdate.xml new file mode 100644 index 0000000..77c1635 --- /dev/null +++ b/man/systemd-sysupdate.xml @@ -0,0 +1,287 @@ + + + + + + + + systemd-sysupdate + systemd + + + + systemd-sysupdate + 8 + + + + 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 + + + + 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.d5. + + 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-repart8 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 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.d5. + + + + Command + + The following commands are understood: + + + + 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. + + + + + + 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. + + + + 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.d5, or + via the available partition slots of the right type. This implicit operation can also be invoked + explicitly via the vacuum command described below. + + + + + + Deletes old installed versions until the limits configured via + InstanceMax= in + sysupdate.d5 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. + + + + + + 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. + + + + + + Similar to the 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 + 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. + + + + + + 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 (see below). + + + + + + + + + Options + + The following options are understood: + + + + + + + + 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 . + + + + + + 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 . + + + + + + Takes a path to a directory to use as root file system when searching for + sysupdate.d/*.conf files. + + + + + + Takes a path to a disk image file or device to mount and use in a similar fashion to + , see above. If this is used and partition resources are updated this is done + inside the specified disk image. + + + + + + + Takes a decimal integer greater than or equal to 2. 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.d5 for + details. + + + + + + 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. + + + + + + Takes a boolean argument, defaults to yes. Controls whether to cryptographically + verify downloads. Do not turn this off, except in testing environments. + + + + + + When used in combination with the update command and a new version is + installed, automatically reboots the system immediately afterwards. + + + + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure code otherwise. + + + + See Also + + systemd1, + sysupdate.d5, + systemd-repart8 + + + + -- cgit v1.2.3