Debian Codegraph @

upstream/debian-unstable/man8/systemd-sysupdate.8

raw
1 '\" t
2 .TH "SYSTEMD\-SYSUPDATE" "8" "" "systemd 261~rc3" "systemd-sysupdate"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd-sysupdate, systemd-sysupdate.service, systemd-sysupdate.timer, systemd-sysupdate-reboot.service, systemd-sysupdate-reboot.timer \- Automatically Update OS or Other Resources
24 .SH "SYNOPSIS"
25 .HP \w'\fBsystemd\-sysupdate\fR\ 'u
26 \fBsystemd\-sysupdate\fR [OPTIONS...]
27 .PP
28 systemd\-sysupdate\&.service
29 .SH "DESCRIPTION"
30 .PP
31 \fBsystemd\-sysupdate\fR
32 atomically updates the host OS, container images, portable service images or other sources, based on the transfer configuration files described in
33 \fBsysupdate.d\fR(5)\&.
34 .PP
35 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 \(em once complete \(em 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\&.
36 .PP
37 The tool updates partitions, files or directory trees always in whole, and operates with at least two versions of each of these resources: the
38 \fIcurrent\fR
39 version, plus the
40 \fInext\fR
41 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\&.
42 .PP
43 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\&.
44 .PP
45 Note that when writing updates to a partition, the partition has to exist already, as
46 \fBsystemd\-sysupdate\fR
47 will not automatically create new partitions\&. Use a tool such as
48 \fBsystemd-repart\fR(8)
49 to automatically create additional partitions to be used with
50 \fBsystemd\-sysupdate\fR
51 on boot\&.
52 .PP
53 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
54 \fB\-\-image=\fR
55 below\&. The latter is particularly interesting to update container images or portable service images\&.
56 .PP
57 The
58 systemd\-sysupdate\&.service
59 system service will automatically update the host OS based on the installed transfer files\&. It is triggered in regular intervals via
60 systemd\-sysupdate\&.timer\&. The
61 systemd\-sysupdate\-reboot\&.service
62 will automatically reboot the system after a new version is installed\&. It is triggered via
63 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\&.
64 .PP
65 For details about transfer files and examples see
66 \fBsysupdate.d\fR(5)\&.
67 .SH "COMMAND"
68 .PP
69 The following commands are understood:
70 .PP
71 \fBlist\fR [\fIVERSION\fR]
72 .RS 4
73 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\*(Aqs 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\&.
74 .sp
75 If no command is explicitly specified this command is implied\&.
76 .sp
77 Added in version 251\&.
78 .RE
79 .PP
80 \fBfeatures\fR [\fIFEATURE\fR]
81 .RS 4
82 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\&.
83 .sp
84 Added in version 257\&.
85 .RE
86 .PP
87 \fBcheck\-new\fR
88 .RS 4
89 Checks if there\*(Aqs a new version available\&. This internally enumerates downloadable and installed versions and returns exit status 0 if there\*(Aqs 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\&.
90 .sp
91 Added in version 251\&.
92 .RE
93 .PP
94 \fBupdate\fR [\-\-offline] [\fIVERSION\fR]
95 .RS 4
96 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\&.
97 .sp
98 If
99 \fB\-\-offline\fR
100 is specified, the update must already have been acquired using
101 \fBacquire\fR
102 and, if so, this pre\-acquired version is the one which will be updated to\&.
103 .sp
104 Added in version 251\&.
105 .RE
106 .PP
107 \fBacquire\fR [\fIVERSION\fR]
108 .RS 4
109 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\&.
110 .sp
111 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
112 \fIInstanceMax=\fR
113 in
114 \fBsysupdate.d\fR(5), or via the available partition slots of the right type\&. This implicit operation can also be invoked explicitly via the
115 \fBvacuum\fR
116 command described below\&.
117 .sp
118 Added in version 260\&.
119 .RE
120 .PP
121 \fBvacuum\fR
122 .RS 4
123 Deletes old installed versions until the limits configured via
124 \fIInstanceMax=\fR
125 in
126 \fBsysupdate.d\fR(5)
127 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\&.
128 .sp
129 Added in version 251\&.
130 .RE
131 .PP
132 \fBpending\fR
133 .RS 4
134 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\*(Aqs identifier with the OS image version as reported by the
135 \fIIMAGE_VERSION=\fR
136 field in
137 /etc/os\-release\&. If the former is newer than the latter, an update was apparently completed but not activated (i\&.e\&. rebooted into) yet\&.
138 .sp
139 Added in version 251\&.
140 .RE
141 .PP
142 \fBreboot\fR
143 .RS 4
144 Similar to the
145 \fBpending\fR
146 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
147 \fBupdate\fR
148 command, after a completed update via the
149 \fB\-\-reboot\fR
150 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\&.
151 .sp
152 Added in version 251\&.
153 .RE
154 .PP
155 \fBcomponents\fR
156 .RS 4
157 Lists components that can be updated\&. This enumerates the
158 /etc/sysupdate\&.*\&.d/,
159 /run/sysupdate\&.*\&.d/
160 and
161 /usr/lib/sysupdate\&.*\&.d/
162 directories that contain transfer files\&. This command is useful to list possible parameters for
163 \fB\-\-component=\fR
164 (see below)\&.
165 .sp
166 Added in version 251\&.
167 .RE
168 .PP
169 \fB\-h\fR, \fB\-\-help\fR
170 .RS 4
171 Print a short help text and exit\&.
172 .RE
173 .PP
174 \fB\-\-version\fR
175 .RS 4
176 Print a short version string and exit\&.
177 .RE
178 .SH "OPTIONS"
179 .PP
180 The following options are understood:
181 .PP
182 \fB\-\-component=\fR, \fB\-C\fR
183 .RS 4
184 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
185 /etc/sysupdate\&.d/*\&.conf,
186 /run/sysupdate\&.d/*\&.conf
187 and
188 /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
189 /etc/sysupdate\&.\fIcomponent\fR\&.d/*\&.conf,
190 /run/sysupdate\&.\fIcomponent\fR\&.d/*\&.conf
191 and
192 /usr/lib/sysupdate\&.\fIcomponent\fR\&.d/*\&.conf, each time with the
193 \fIcomponent\fR
194 string replaced with the specified component name\&.
195 .sp
196 Use the
197 \fBcomponents\fR
198 command to list available components to update\&. This enumerates the directories matching this naming rule\&.
199 .sp
200 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
201 sysupdate\&.d/
202 directory for these cases\&.
203 .sp
204 This option may not be combined with
205 \fB\-\-definitions=\fR\&.
206 .sp
207 Added in version 251\&.
208 .RE
209 .PP
210 \fB\-\-definitions=\fR
211 .RS 4
212 A path to a directory\&. If specified, the transfer
213 *\&.conf
214 files are read from this directory instead of
215 /usr/lib/sysupdate\&.d/*\&.conf,
216 /etc/sysupdate\&.d/*\&.conf, and
217 /run/sysupdate\&.d/*\&.conf\&.
218 .sp
219 This option may not be combined with
220 \fB\-\-component=\fR\&.
221 .sp
222 Added in version 251\&.
223 .RE
224 .PP
225 \fB\-\-root=\fR
226 .RS 4
227 Takes a path to a directory to use as root file system when searching for
228 sysupdate\&.d/*\&.conf
229 files\&.
230 .sp
231 Added in version 251\&.
232 .RE
233 .PP
234 \fB\-\-image=\fR
235 .RS 4
236 Takes a path to a disk image file or device to mount and use in a similar fashion to
237 \fB\-\-root=\fR, see above\&. If this is used and partition resources are updated this is done inside the specified disk image\&.
238 .sp
239 Added in version 251\&.
240 .RE
241 .PP
242 \fB\-\-image\-policy=\fR\fB\fIpolicy\fR\fR
243 .RS 4
244 Takes an image policy string as argument, as per
245 \fBsystemd.image-policy\fR(7)\&. The policy is enforced when operating on the disk image specified via
246 \fB\-\-image=\fR, see above\&. If not specified, defaults to the
247 "*"
248 policy, i\&.e\&. all recognized file systems in the image are used\&.
249 .RE
250 .PP
251 \fB\-\-instances\-max=\fR, \fB\-m\fR
252 .RS 4
253 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
254 \fIInstancesMax=\fR
255 setting, see
256 \fBsysupdate.d\fR(5)
257 for details\&.
258 .sp
259 Added in version 251\&.
260 .RE
261 .PP
262 \fB\-\-sync=\fR
263 .RS 4
264 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\&.
265 .sp
266 Added in version 251\&.
267 .RE
268 .PP
269 \fB\-\-verify=\fR
270 .RS 4
271 Takes a boolean argument, defaults to yes\&. Controls whether to cryptographically verify downloads\&. Do not turn this off, except in testing environments\&.
272 .sp
273 Added in version 251\&.
274 .RE
275 .PP
276 \fB\-\-reboot\fR
277 .RS 4
278 When used in combination with the
279 \fBupdate\fR
280 commands and a new version is installed, automatically reboots the system immediately afterwards\&.
281 .sp
282 Added in version 251\&.
283 .RE
284 .PP
285 \fB\-\-offline\fR
286 .RS 4
287 Prevents fetching metadata from the network (i\&.e\&.
288 SHA256SUMS)\&. This is most useful when used in combination with the
289 \fBlist\fR
290 command, to query locally installed versions\&.
291 .sp
292 If used in combination with the
293 \fBupdate\fR
294 command, it allows updates to be downloaded in advance (using
295 \fBacquire\fR) and installed later\&.
296 .sp
297 Added in version 257\&.
298 .RE
299 .PP
300 \fB\-\-transfer\-source=\fR
301 .RS 4
302 Takes a path as its argument\&. When specified, all transfer sources configured with
303 \fIPathRelativeTo=explicit\fR
304 will be interpreted relative to the specified path\&.
305 .sp
306 Added in version 257\&.
307 .RE
308 .PP
309 \fB\-\-no\-pager\fR
310 .RS 4
311 Do not pipe output into a pager\&.
312 .RE
313 .PP
314 \fB\-\-no\-legend\fR
315 .RS 4
316 Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
317 .RE
318 .PP
319 \fB\-\-json=\fR\fB\fIMODE\fR\fR
320 .RS 4
321 Shows output formatted as JSON\&. Expects one of
322 "short"
323 (for the shortest possible output without any redundant whitespace or line breaks),
324 "pretty"
325 (for a pretty version of the same, with indentation and line breaks) or
326 "off"
327 (to turn off JSON output, the default)\&.
328 .RE
329 .SH "EXIT STATUS"
330 .PP
331 On success, 0 is returned, a non\-zero failure code otherwise\&.
332 .SH "SEE ALSO"
333 .PP
334 \fBsystemd\fR(1), \fBsysupdate.d\fR(5), \fBsystemd-sysupdated.service\fR(8), \fBsystemd-repart\fR(8)