1SYSTEMD-SYSUPDATE(8)           systemd-sysupdate          SYSTEMD-SYSUPDATE(8)
2
3
4

NAME

6       systemd-sysupdate, systemd-sysupdate.service, systemd-sysupdate.timer,
7       systemd-sysupdate-reboot.service, systemd-sysupdate-reboot.timer -
8       Automatically Update OS or Other Resources
9

SYNOPSIS

11       systemd-sysupdate [OPTIONS...]
12
13       systemd-sysupdate.service
14

DESCRIPTION

16       systemd-sysupdate atomically updates the host OS, container images,
17       portable service images or other sources, based on the transfer
18       configuration files described in sysupdate.d(5).
19
20       This tool implements file, directory, or partition based update
21       schemes, supporting multiple parallel installed versions of specific
22       resources in an A/B (or even: A/B/C, A/B/C/D/, ...) style. A/B updating
23       means that when one version of a resource is currently being used, the
24       next version can be downloaded, unpacked, and prepared in an entirely
25       separate location, independently of the first, and — once complete — be
26       activated, swapping the roles so that it becomes the used one and the
27       previously used one becomes the one that is replaced by the next
28       update, and so on. The resources to update are defined in transfer
29       files, one for each resource to be updated. For example, resources that
30       may be updated with this tool could be: a root file system partition, a
31       matching Verity partition plus one kernel image. The combination of the
32       three would be considered a complete OS update.
33
34       The tool updates partitions, files or directory trees always in whole,
35       and operates with at least two versions of each of these resources: the
36       current version, plus the next version: the one that is being updated
37       to, and which is initially incomplete as the downloaded data is written
38       to it; plus optionally more versions. Once the download of a newer
39       version is complete it becomes the current version, releasing the
40       version previously considered current for
41       deletion/replacement/updating.
42
43       When installing new versions the tool will directly download,
44       decompress, unpack and write the new version into the destination. This
45       is done in a robust fashion so that an incomplete download can be
46       recognized on next invocation, and flushed out before a new attempt is
47       initiated.
48
49       Note that when writing updates to a partition, the partition has to
50       exist already, as systemd-sysupdate will not automatically create new
51       partitions. Use a tool such as systemd-repart(8) to automatically
52       create additional partitions to be used with systemd-sysupdate on boot.
53
54       The tool can both be used on the running OS, to update the OS in
55       "online" state from within itself, and on "offline" disk images, to
56       update them from the outside based on transfer files embedded in the
57       disk images. For the latter, see --image= below. The latter is
58       particularly interesting to update container images or portable service
59       images.
60
61       The systemd-sysupdate.service system service will automatically update
62       the host OS based on the installed transfer files. It is triggered in
63       regular intervals via systemd-sysupdate.timer. The
64       systemd-sysupdate-reboot.service will automatically reboot the system
65       after a new version is installed. It is triggered via
66       systemd-sysupdate-reboot.timer. The two services are separate from each
67       other as it is typically advisable to download updates regularly while
68       the system is up, but delay reboots until the appropriate time (i.e.
69       typically at night). The two sets of service/timer units may be enabled
70       separately.
71
72       For details about transfer files and examples see sysupdate.d(5).
73

COMMAND

75       The following commands are understood:
76
77       list [VERSION]
78           If invoked without an argument, enumerates downloadable and
79           installed versions, and shows a summarizing table with the
80           discovered versions and their properties, including whether there's
81           a newer candidate version to update to. If a version argument is
82           specified, shows details about the specific version, including the
83           individual files that need to be transferred to acquire the
84           version.
85
86           If no command is explicitly specified this command is implied.
87
88       check-new
89           Checks if there's a new version available. This internally
90           enumerates downloadable and installed versions and returns exit
91           status 0 if there's a new version to update to, non-zero otherwise.
92           If there is a new version to update to, its version identifier is
93           written to standard output.
94
95       update [VERSION]
96           Installs (updates to) the specified version, or if none is
97           specified to the newest version available. If the version is
98           already installed or no newer version available, no operation is
99           executed.
100
101           If a new version to install/update to is found, old installed
102           versions are deleted until at least one new version can be
103           installed, as configured via InstanceMax= in sysupdate.d(5), or via
104           the available partition slots of the right type. This implicit
105           operation can also be invoked explicitly via the vacuum command
106           described below.
107
108       vacuum
109           Deletes old installed versions until the limits configured via
110           InstanceMax= in sysupdate.d(5) are met again. Normally, it should
111           not be necessary to invoke this command explicitly, since it is
112           implicitly invoked whenever a new update is initiated.
113
114       pending
115           Checks whether a newer version of the OS is installed than the one
116           currently running. Returns zero if so, non-zero otherwise. This
117           compares the newest installed version's identifier with the OS
118           image version as reported by the IMAGE_VERSION= field in
119           /etc/os-release. If the former is newer than the latter, an update
120           was apparently completed but not activated (i.e. rebooted into)
121           yet.
122
123       reboot
124           Similar to the pending command but immediately reboots in case a
125           newer version of the OS has been installed than the one currently
126           running. This operation can be done implicitly together with the
127           update command, after a completed update via the --reboot switch,
128           see below. This command will execute no operation (and return
129           success) if no update has been installed, and thus the system was
130           not rebooted.
131
132       components
133           Lists components that can be updated. This enumerates the
134           /etc/sysupdate.*.d/, /run/sysupdate.*.d/ and
135           /usr/lib/sysupdate.*.d/ directories that contain transfer files.
136           This command is useful to list possible parameters for --component=
137           (see below).
138
139       -h, --help
140           Print a short help text and exit.
141
142       --version
143           Print a short version string and exit.
144

OPTIONS

146       The following options are understood:
147
148       --component=, -C
149           Selects the component to update. Takes a component name as
150           argument. This has the effect of slightly altering the search logic
151           for transfer files. If this switch is not used, the transfer files
152           are loaded from /etc/sysupdate.d/*.conf, /run/sysupdate.d/*.conf
153           and /usr/lib/sysupdate.d/*.conf. If this switch is used, the
154           specified component name is used to alter the directories to look
155           in to be /etc/sysupdate.component.d/*.conf,
156           /run/sysupdate.component.d/*.conf and
157           /usr/lib/sysupdate.component.d/*.conf, each time with the component
158           string replaced with the specified component name.
159
160           Use the components command to list available components to update.
161           This enumerates the directories matching this naming rule.
162
163           Components may be used to define a separate set of transfer files
164           for different components of the OS that shall be updated
165           separately. Do not use this concept for resources that shall always
166           be updated together in a synchronous fashion. Simply define
167           multiple transfer files within the same sysupdate.d/ directory for
168           these cases.
169
170           This option may not be combined with --definitions=.
171
172       --definitions=
173           A path to a directory. If specified, the transfer *.conf files are
174           read from this directory instead of /usr/lib/sysupdate.d/*.conf,
175           /etc/sysupdate.d/*.conf, and /run/sysupdate.d/*.conf.
176
177           This option may not be combined with --component=.
178
179       --root=
180           Takes a path to a directory to use as root file system when
181           searching for sysupdate.d/*.conf files.
182
183       --image=
184           Takes a path to a disk image file or device to mount and use in a
185           similar fashion to --root=, see above. If this is used and
186           partition resources are updated this is done inside the specified
187           disk image.
188
189       --instances-max=, -m
190           Takes a decimal integer greater than or equal to 2. Controls how
191           many versions to keep at any time. This option may also be
192           configured inside the transfer files, via the InstancesMax=
193           setting, see sysupdate.d(5) for details.
194
195       --sync=
196           Takes a boolean argument, defaults to yes. This may be used to
197           specify whether the newly updated resource versions shall be
198           synchronized to disk when appropriate (i.e. after the download is
199           complete, before it is finalized, and again after finalization).
200           This should not be turned off, except to improve runtime
201           performance in testing environments.
202
203       --verify=
204           Takes a boolean argument, defaults to yes. Controls whether to
205           cryptographically verify downloads. Do not turn this off, except in
206           testing environments.
207
208       --reboot
209           When used in combination with the update command and a new version
210           is installed, automatically reboots the system immediately
211           afterwards.
212
213       --no-pager
214           Do not pipe output into a pager.
215
216       --no-legend
217           Do not print the legend, i.e. column headers and the footer with
218           hints.
219
220       --json=MODE
221           Shows output formatted as JSON. Expects one of "short" (for the
222           shortest possible output without any redundant whitespace or line
223           breaks), "pretty" (for a pretty version of the same, with
224           indentation and line breaks) or "off" (to turn off JSON output, the
225           default).
226

EXIT STATUS

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

SEE ALSO

231       systemd(1), sysupdate.d(5), systemd-repart(8)
232
233
234
235systemd 253                                               SYSTEMD-SYSUPDATE(8)
Impressum