1SYSTEMD-SYSUPDATE(8) systemd-sysupdate SYSTEMD-SYSUPDATE(8)
2
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
11 systemd-sysupdate [OPTIONS...]
12 systemd-sysupdate.service
14
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 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 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 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 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 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 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 For details about transfer files and examples see sysupdate.d(5).
73
75 The following commands are understood:
76 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 If no command is explicitly specified this command is implied.
87 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 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 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 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 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 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 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 -h, --help
140 Print a short help text and exit.
141 --version
143 Print a short version string and exit.
144
146 The following options are understood:
147 --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 Use the components command to list available components to update.
161 This enumerates the directories matching this naming rule.
162 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 This option may not be combined with --definitions=.
171 --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 This option may not be combined with --component=.
178 --root=
180 Takes a path to a directory to use as root file system when
181 searching for sysupdate.d/*.conf files.
182 --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 --image-policy=policy
190 Takes an image policy string as argument, as per systemd.image-
191 policy(7). The policy is enforced when operating on the disk image
192 specified via --image=, see above. If not specified defaults to the
193 "*" policy, i.e. all recognized file systems in the image are used.
194 --instances-max=, -m
196 Takes a decimal integer greater than or equal to 2. Controls how
197 many versions to keep at any time. This option may also be
198 configured inside the transfer files, via the InstancesMax=
199 setting, see sysupdate.d(5) for details.
200 --sync=
202 Takes a boolean argument, defaults to yes. This may be used to
203 specify whether the newly updated resource versions shall be
204 synchronized to disk when appropriate (i.e. after the download is
205 complete, before it is finalized, and again after finalization).
206 This should not be turned off, except to improve runtime
207 performance in testing environments.
208 --verify=
210 Takes a boolean argument, defaults to yes. Controls whether to
211 cryptographically verify downloads. Do not turn this off, except in
212 testing environments.
213 --reboot
215 When used in combination with the update command and a new version
216 is installed, automatically reboots the system immediately
217 afterwards.
218 --no-pager
220 Do not pipe output into a pager.
221 --no-legend
223 Do not print the legend, i.e. column headers and the footer with
224 hints.
225 --json=MODE
227 Shows output formatted as JSON. Expects one of "short" (for the
228 shortest possible output without any redundant whitespace or line
229 breaks), "pretty" (for a pretty version of the same, with
230 indentation and line breaks) or "off" (to turn off JSON output, the
231 default).
232
234 On success, 0 is returned, a non-zero failure code otherwise.
235
237 systemd(1), sysupdate.d(5), systemd-repart(8)
238systemd 254 SYSTEMD-SYSUPDATE(8)