]>
Commit | Line | Data |
---|---|---|
436aa3b1 LP |
1 | <?xml version='1.0'?> <!--*-nxml-*--> |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | |
eea10b26 | 3 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> |
436aa3b1 LP |
4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
5 | ||
6 | <refentry id="systemd-sysupdate" conditional='ENABLE_SYSUPDATE' | |
7 | xmlns:xi="http://www.w3.org/2001/XInclude"> | |
8 | ||
9 | <refentryinfo> | |
10 | <title>systemd-sysupdate</title> | |
11 | <productname>systemd</productname> | |
12 | </refentryinfo> | |
13 | ||
14 | <refmeta> | |
15 | <refentrytitle>systemd-sysupdate</refentrytitle> | |
16 | <manvolnum>8</manvolnum> | |
17 | </refmeta> | |
18 | ||
19 | <refnamediv> | |
20 | <refname>systemd-sysupdate</refname> | |
21 | <refname>systemd-sysupdate.service</refname> | |
22 | <refname>systemd-sysupdate.timer</refname> | |
23 | <refname>systemd-sysupdate-reboot.service</refname> | |
24 | <refname>systemd-sysupdate-reboot.timer</refname> | |
25 | <refpurpose>Automatically Update OS or Other Resources</refpurpose> | |
26 | </refnamediv> | |
27 | ||
28 | <refsynopsisdiv> | |
29 | <cmdsynopsis> | |
30 | <command>systemd-sysupdate</command> | |
31 | <arg choice="opt" rep="repeat">OPTIONS</arg> | |
32 | </cmdsynopsis> | |
33 | ||
34 | <para><filename>systemd-sysupdate.service</filename></para> | |
35 | </refsynopsisdiv> | |
36 | ||
37 | <refsect1> | |
38 | <title>Description</title> | |
39 | ||
40 | <para><command>systemd-sysupdate</command> atomically updates the host OS, container images, portable | |
41 | service images or other sources, based on the transfer configuration files described in | |
42 | <citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> | |
43 | ||
44 | <para>This tool implements file, directory, or partition based update schemes, supporting multiple | |
45 | parallel installed versions of specific resources in an A/B (or even: A/B/C, A/B/C/D/, …) style. A/B | |
46 | updating means that when one version of a resource is currently being used, the next version can be | |
a4cc838e | 47 | downloaded, unpacked, and prepared in an entirely separate location, independently of the first, and — once |
436aa3b1 | 48 | complete — be activated, swapping the roles so that it becomes the used one and the previously used one |
a4cc838e | 49 | becomes the one that is replaced by the next update, and so on. The resources to update are defined |
436aa3b1 LP |
50 | in transfer files, one for each resource to be updated. For example, resources that may be updated with |
51 | this tool could be: a root file system partition, a matching Verity partition plus one kernel image. The | |
52 | combination of the three would be considered a complete OS update.</para> | |
53 | ||
54 | <para>The tool updates partitions, files or directory trees always in whole, and operates with at least | |
55 | two versions of each of these resources: the <emphasis>current</emphasis> version, plus the | |
56 | <emphasis>next</emphasis> version: the one that is being updated to, and which is initially incomplete as | |
57 | the downloaded data is written to it; plus optionally more versions. Once the download of a newer version | |
58 | is complete it becomes the current version, releasing the version previously considered current for | |
59 | deletion/replacement/updating.</para> | |
60 | ||
61 | <para>When installing new versions the tool will directly download, decompress, unpack and write the new | |
62 | version into the destination. This is done in a robust fashion so that an incomplete download can be | |
63 | recognized on next invocation, and flushed out before a new attempt is initiated.</para> | |
64 | ||
65 | <para>Note that when writing updates to a partition, the partition has to exist already, as | |
66 | <command>systemd-sysupdate</command> will not automatically create new partitions. Use a tool such as | |
67 | <citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry> to | |
68 | automatically create additional partitions to be used with <command>systemd-sysupdate</command> on | |
69 | boot.</para> | |
70 | ||
71 | <para>The tool can both be used on the running OS, to update the OS in "online" state from within itself, | |
72 | and on "offline" disk images, to update them from the outside based on transfer files | |
73 | embedded in the disk images. For the latter, see <option>--image=</option> below. The latter is | |
74 | particularly interesting to update container images or portable service images.</para> | |
75 | ||
76 | <para>The <filename>systemd-sysupdate.service</filename> system service will automatically update the | |
77 | host OS based on the installed transfer files. It is triggered in regular intervals via | |
78 | <filename>systemd-sysupdate.timer</filename>. The <filename>systemd-sysupdate-reboot.service</filename> | |
79 | will automatically reboot the system after a new version is installed. It is triggered via | |
80 | <filename>systemd-sysupdate-reboot.timer</filename>. The two services are separate from each other as it | |
81 | is typically advisable to download updates regularly while the system is up, but delay reboots until the | |
82 | appropriate time (i.e. typically at night). The two sets of service/timer units may be enabled | |
83 | separately.</para> | |
84 | ||
85 | <para>For details about transfer files and examples see | |
86 | <citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> | |
87 | </refsect1> | |
88 | ||
89 | <refsect1> | |
90 | <title>Command</title> | |
91 | ||
92 | <para>The following commands are understood:</para> | |
93 | ||
94 | <variablelist> | |
95 | <varlistentry> | |
96 | <term><option>list</option> <optional><replaceable>VERSION</replaceable></optional></term> | |
97 | ||
98 | <listitem><para>If invoked without an argument, enumerates downloadable and installed versions, and | |
99 | shows a summarizing table with the discovered versions and their properties, including whether | |
100 | there's a newer candidate version to update to. If a version argument is specified, shows details | |
101 | about the specific version, including the individual files that need to be transferred to acquire the | |
102 | version.</para> | |
103 | ||
ec07c3c8 AK |
104 | <para>If no command is explicitly specified this command is implied.</para> |
105 | ||
106 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
107 | </varlistentry> |
108 | ||
109 | <varlistentry> | |
110 | <term><option>check-new</option></term> | |
111 | ||
112 | <listitem><para>Checks if there's a new version available. This internally enumerates downloadable and | |
113 | installed versions and returns exit status 0 if there's a new version to update to, non-zero | |
114 | otherwise. If there is a new version to update to, its version identifier is written to standard | |
ec07c3c8 AK |
115 | output.</para> |
116 | ||
117 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
118 | </varlistentry> |
119 | ||
120 | <varlistentry> | |
121 | <term><option>update</option> <optional><replaceable>VERSION</replaceable></optional></term> | |
122 | ||
123 | <listitem><para>Installs (updates to) the specified version, or if none is specified to the newest | |
124 | version available. If the version is already installed or no newer version available, no operation is | |
125 | executed.</para> | |
126 | ||
127 | <para>If a new version to install/update to is found, old installed versions are deleted until at | |
128 | least one new version can be installed, as configured via <varname>InstanceMax=</varname> in | |
129 | <citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, or | |
130 | via the available partition slots of the right type. This implicit operation can also be invoked | |
ec07c3c8 AK |
131 | explicitly via the <command>vacuum</command> command described below.</para> |
132 | ||
133 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
134 | </varlistentry> |
135 | ||
136 | <varlistentry> | |
137 | <term><option>vacuum</option></term> | |
138 | ||
139 | <listitem><para>Deletes old installed versions until the limits configured via | |
140 | <varname>InstanceMax=</varname> in | |
141 | <citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> are | |
142 | met again. Normally, it should not be necessary to invoke this command explicitly, since it is | |
ec07c3c8 AK |
143 | implicitly invoked whenever a new update is initiated.</para> |
144 | ||
145 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
146 | </varlistentry> |
147 | ||
148 | <varlistentry> | |
149 | <term><option>pending</option></term> | |
150 | ||
151 | <listitem><para>Checks whether a newer version of the OS is installed than the one currently | |
152 | running. Returns zero if so, non-zero otherwise. This compares the newest installed version's | |
153 | identifier with the OS image version as reported by the <varname>IMAGE_VERSION=</varname> field in | |
154 | <filename>/etc/os-release</filename>. If the former is newer than the latter, an update was | |
ec07c3c8 AK |
155 | apparently completed but not activated (i.e. rebooted into) yet.</para> |
156 | ||
157 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
158 | </varlistentry> |
159 | ||
160 | <varlistentry> | |
161 | <term><option>reboot</option></term> | |
162 | ||
163 | <listitem><para>Similar to the <option>pending</option> command but immediately reboots in case a | |
164 | newer version of the OS has been installed than the one currently running. This operation can be done | |
165 | implicitly together with the <command>update</command> command, after a completed update via the | |
166 | <option>--reboot</option> switch, see below. This command will execute no operation (and return | |
ec07c3c8 AK |
167 | success) if no update has been installed, and thus the system was not rebooted.</para> |
168 | ||
169 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
170 | </varlistentry> |
171 | ||
172 | <varlistentry> | |
173 | <term><option>components</option></term> | |
174 | ||
175 | <listitem><para>Lists components that can be updated. This enumerates the | |
176 | <filename>/etc/sysupdate.*.d/</filename>, <filename>/run/sysupdate.*.d/</filename> and | |
177 | <filename>/usr/lib/sysupdate.*.d/</filename> directories that contain transfer files. This command is | |
ec07c3c8 AK |
178 | useful to list possible parameters for <option>--component=</option> (see below).</para> |
179 | ||
180 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
181 | </varlistentry> |
182 | ||
183 | <xi:include href="standard-options.xml" xpointer="help" /> | |
184 | <xi:include href="standard-options.xml" xpointer="version" /> | |
185 | </variablelist> | |
186 | </refsect1> | |
187 | ||
188 | <refsect1> | |
189 | <title>Options</title> | |
190 | ||
191 | <para>The following options are understood:</para> | |
192 | ||
193 | <variablelist> | |
194 | ||
195 | <varlistentry> | |
196 | <term><option>--component=</option></term> | |
197 | <term><option>-C</option></term> | |
198 | ||
199 | <listitem><para>Selects the component to update. Takes a component name as argument. This has the | |
200 | effect of slightly altering the search logic for transfer files. If this switch is not used, the | |
201 | transfer files are loaded from <filename>/etc/sysupdate.d/*.conf</filename>, | |
202 | <filename>/run/sysupdate.d/*.conf</filename> and <filename>/usr/lib/sysupdate.d/*.conf</filename>. If | |
203 | this switch is used, the specified component name is used to alter the directories to look in to be | |
204 | <filename>/etc/sysupdate.<replaceable>component</replaceable>.d/*.conf</filename>, | |
205 | <filename>/run/sysupdate.<replaceable>component</replaceable>.d/*.conf</filename> and | |
206 | <filename>/usr/lib/sysupdate.<replaceable>component</replaceable>.d/*.conf</filename>, each time with | |
207 | the <filename><replaceable>component</replaceable></filename> string replaced with the specified | |
208 | component name.</para> | |
209 | ||
210 | <para>Use the <command>components</command> command to list available components to update. This enumerates | |
211 | the directories matching this naming rule.</para> | |
212 | ||
213 | <para>Components may be used to define a separate set of transfer files for different components of | |
214 | the OS that shall be updated separately. Do not use this concept for resources that shall always be | |
215 | updated together in a synchronous fashion. Simply define multiple transfer files within the same | |
216 | <filename>sysupdate.d/</filename> directory for these cases.</para> | |
217 | ||
ec07c3c8 AK |
218 | <para>This option may not be combined with <option>--definitions=</option>.</para> |
219 | ||
220 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
221 | </varlistentry> |
222 | ||
223 | <varlistentry> | |
224 | <term><option>--definitions=</option></term> | |
225 | ||
226 | <listitem><para>A path to a directory. If specified, the transfer <filename>*.conf</filename> files | |
227 | are read from this directory instead of <filename>/usr/lib/sysupdate.d/*.conf</filename>, | |
228 | <filename>/etc/sysupdate.d/*.conf</filename>, and <filename>/run/sysupdate.d/*.conf</filename>.</para> | |
229 | ||
ec07c3c8 AK |
230 | <para>This option may not be combined with <option>--component=</option>.</para> |
231 | ||
232 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
233 | </varlistentry> |
234 | ||
235 | <varlistentry> | |
236 | <term><option>--root=</option></term> | |
237 | ||
238 | <listitem><para>Takes a path to a directory to use as root file system when searching for | |
ec07c3c8 AK |
239 | <filename>sysupdate.d/*.conf</filename> files.</para> |
240 | ||
241 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
242 | </varlistentry> |
243 | ||
244 | <varlistentry> | |
245 | <term><option>--image=</option></term> | |
246 | ||
247 | <listitem><para>Takes a path to a disk image file or device to mount and use in a similar fashion to | |
248 | <option>--root=</option>, see above. If this is used and partition resources are updated this is done | |
ec07c3c8 AK |
249 | inside the specified disk image.</para> |
250 | ||
251 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
252 | </varlistentry> |
253 | ||
9ea81191 LP |
254 | <xi:include href="standard-options.xml" xpointer="image-policy-open" /> |
255 | ||
436aa3b1 LP |
256 | <varlistentry> |
257 | <term><option>--instances-max=</option></term> | |
258 | <term><option>-m</option></term> | |
259 | ||
260 | <listitem><para>Takes a decimal integer greater than or equal to 2. Controls how many versions to | |
261 | keep at any time. This option may also be configured inside the transfer files, via the | |
262 | <varname>InstancesMax=</varname> setting, see | |
263 | <citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> for | |
ec07c3c8 AK |
264 | details.</para> |
265 | ||
266 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
267 | </varlistentry> |
268 | ||
269 | <varlistentry> | |
270 | <term><option>--sync=</option></term> | |
271 | ||
272 | <listitem><para>Takes a boolean argument, defaults to yes. This may be used to specify whether the | |
273 | newly updated resource versions shall be synchronized to disk when appropriate (i.e. after the | |
274 | download is complete, before it is finalized, and again after finalization). This should not be | |
ec07c3c8 AK |
275 | turned off, except to improve runtime performance in testing environments.</para> |
276 | ||
277 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
278 | </varlistentry> |
279 | ||
280 | <varlistentry> | |
281 | <term><option>--verify=</option></term> | |
282 | ||
283 | <listitem><para>Takes a boolean argument, defaults to yes. Controls whether to cryptographically | |
ec07c3c8 AK |
284 | verify downloads. Do not turn this off, except in testing environments.</para> |
285 | ||
286 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
287 | </varlistentry> |
288 | ||
289 | <varlistentry> | |
290 | <term><option>--reboot</option></term> | |
291 | ||
292 | <listitem><para>When used in combination with the <command>update</command> command and a new version is | |
ec07c3c8 AK |
293 | installed, automatically reboots the system immediately afterwards.</para> |
294 | ||
295 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
436aa3b1 LP |
296 | </varlistentry> |
297 | ||
298 | <xi:include href="standard-options.xml" xpointer="no-pager" /> | |
299 | <xi:include href="standard-options.xml" xpointer="no-legend" /> | |
300 | <xi:include href="standard-options.xml" xpointer="json" /> | |
301 | </variablelist> | |
302 | </refsect1> | |
303 | ||
304 | <refsect1> | |
305 | <title>Exit status</title> | |
306 | ||
307 | <para>On success, 0 is returned, a non-zero failure code otherwise.</para> | |
308 | </refsect1> | |
309 | ||
310 | <refsect1> | |
311 | <title>See Also</title> | |
13a69c12 DT |
312 | <para><simplelist type="inline"> |
313 | <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
314 | <member><citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> | |
315 | <member><citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> | |
316 | </simplelist></para> | |
436aa3b1 LP |
317 | </refsect1> |
318 | ||
319 | </refentry> |