Debian Codegraph @

upstream/opensuse-tumbleweed/man5/org.freedesktop.sysupdate1.5

raw
1 '\" t
2 .TH "ORG\&.FREEDESKTOP\&.SYSUPDATE1" "5" "" "systemd 260.1" "org.freedesktop.sysupdate1"
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 org.freedesktop.sysupdate1 \- The D\-Bus interface of systemd\-sysupdated
24 .SH "INTRODUCTION"
25 .PP
26 \fBsystemd-sysupdated.service\fR(8)
27 is a system service that allows unprivileged clients to update the system\&. This page describes the D\-Bus interface\&.
28 .PP
29 \fIWARNING!\fR
30 This API is currently
31 \fIunstable\fR
32 and is thus subject to breaking changes between versions of systemd\&.
33 .SH "THE MANAGER OBJECT"
34 .PP
35 The service exposes the following interfaces on the Manager object on the bus:
36 .sp
37 .if n \{\
38 .RS 4
39 .\}
40 .nf
41 node /org/freedesktop/sysupdate1 {
42 interface org\&.freedesktop\&.sysupdate1\&.Manager {
43 methods:
44 ListTargets(out a(sso) targets);
45 ListJobs(out a(tsuo) jobs);
46 ListAppStream(out as urls);
47 signals:
48 JobRemoved(t id,
49 o path,
50 i status);
51 };
52 interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
53 interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
54 interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
55 };
56 .fi
57 .if n \{\
58 .RE
59 .\}
60
61
62
63
64
65 .SS "Methods"
66 .PP
67 \fBListTargets()\fR
68 returns a list all known update targets\&. It returns an array of structures which consist of a string indicating the target\*(Aqs class (see Target\*(Aqs
69 \fIClass\fR
70 property below for an explanation of the possible values), a string with the name of the target, and the target object path\&.
71 .PP
72 \fBListJobs()\fR
73 returns a list all ongoing jobs\&. It returns an array of structures which consist of a numeric job ID, a string indicating the job type (see Job\*(Aqs
74 \fIType\fR
75 property below for an explanation of the possible values), the job\*(Aqs progress, and the job\*(Aqs object path\&.
76 .PP
77 \fBListAppStream()\fR
78 returns an array of all the appstream catalog URLs that this service knows about\&. See Target\*(Aqs
79 \fIGetAppStream()\fR
80 method below for more details\&.
81 .SS "Signals"
82 .PP
83 The
84 \fBJobRemoved()\fR
85 signal is sent each time a job finishes, is canceled or fails\&. It also carries the job ID and object path, followed by a numeric status code\&. If the status is zero, the job has succeed\&. A positive status should be treated as an exit code (i\&.e\&.
86 "EXIT_FAILURE"), and a negative status should be treated as a negative errno\-style error code (i\&.e\&.
87 "\-EINVAL")\&.
88 .SH "THE TARGET OBJECT"
89 .PP
90 A target is a component of the system (i\&.e\&. the host itself, a sysext, a confext, etc\&.) that can be updated by
91 \fBsystemd-sysupdate\fR(8)\&.
92 .PP
93 The service exposes the following interfaces on Target objects on the bus:
94 .sp
95 .if n \{\
96 .RS 4
97 .\}
98 .nf
99 node /org/freedesktop/sysupdate1/target/host {
100 interface org\&.freedesktop\&.sysupdate1\&.Target {
101 methods:
102 List(in t flags,
103 out as versions);
104 Describe(in s version,
105 in t flags,
106 out s json);
107 CheckNew(out s new_version);
108 Acquire(in s new_version,
109 in t flags,
110 out s new_version,
111 out t job_id,
112 out o job_path);
113 Install(in s new_version,
114 in t flags,
115 out s new_version,
116 out t job_id,
117 out o job_path);
118 Vacuum(out u instances,
119 out u disabled_transfers);
120 GetAppStream(out as appstream);
121 GetVersion(out s version);
122 ListFeatures(in t flags,
123 out as features);
124 DescribeFeature(in s feature,
125 in t flags,
126 out s json);
127 SetFeatureEnabled(in s feature,
128 in i enabled,
129 in t flags);
130 properties:
131 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
132 readonly s Class = \*(Aq\&.\&.\&.\*(Aq;
133 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
134 readonly s Name = \*(Aq\&.\&.\&.\*(Aq;
135 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
136 readonly s Path = \*(Aq\&.\&.\&.\*(Aq;
137 };
138 interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
139 interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
140 interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
141 };
142 .fi
143 .if n \{\
144 .RE
145 .\}
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161 .SS "Methods"
162 .PP
163 \fBList()\fR
164 returns a list of versions available for this target\&. Additional options may be passed through the
165 \fIflags\fR
166 argument\&. Valid flags are defined as follows:
167 .sp
168 .if n \{\
169 .RS 4
170 .\}
171 .nf
172 #define SD_SYSUPDATE_OFFLINE (UINT64_C(1) << 0)
173 .fi
174 .if n \{\
175 .RE
176 .\}
177 .PP
178 When
179 \fBSD_SYSUPDATE_OFFLINE\fR
180 is set, this method returns only the versions installed locally\&. Otherwise, this method pulls metadata from the network and returns all versions available for this target\&. Use
181 \fBDescribe()\fR
182 to query more information about each version returned by this method\&.
183 .PP
184 \fBDescribe()\fR
185 returns all known information about a given version as a JSON object\&. The
186 \fIversion\fR
187 argument is used to pass the version to be described\&. Additional options may be passed through the
188 \fIflags\fR
189 argument\&. This method supports the same flags as
190 \fBList()\fR\&. The returned JSON object contains several known keys\&. More keys may be added in the future\&. The currently known keys are as follows:
191 .PP
192 "version"
193 .RS 4
194 A string containing the version number\&.
195 .RE
196 .PP
197 "newest"
198 .RS 4
199 A boolean indicating whether this version is the latest available for the target\&.
200 .RE
201 .PP
202 "available"
203 .RS 4
204 A boolean indicating whether this version is available for download\&.
205 .RE
206 .PP
207 "installed"
208 .RS 4
209 A boolean indicating whether this version is installed locally\&.
210 .RE
211 .PP
212 "obsolete"
213 .RS 4
214 A boolean indicating whether this version is considered obsolete by the service, and is therefore disallowed from being installed\&.
215 .RE
216 .PP
217 "protected"
218 .RS 4
219 A boolean indicating whether this version is exempt from deletion by a
220 \fBVacuum()\fR
221 operation\&.
222 .RE
223 .PP
224 "incomplete"
225 .RS 4
226 A boolean indicating whether this version is incomplete, which means that it is missing some file\&. Note that only installed incomplete versions will be offered by the service; versions that are incomplete on the server\-side are completely ignored\&. Incomplete versions can be repaired in\-place by calling
227 \fBAcquire()\fR
228 and
229 \fBInstall()\fR
230 on that version\&.
231 .RE
232 .PP
233 "changelogUrls"
234 .RS 4
235 A list of strings that contain user\-presentable URLs to change logs associated with this version\&.
236 .RE
237 .PP
238 \fBCheckNew()\fR
239 checks if a newer version is available for this target\&. This method pulls metadata from the network\&. If a newer version is found, this method returns the version number\&. If no newer version is found, this method returns an empty string\&. Use
240 \fBDescribe()\fR
241 to query more information about the version returned by this method\&.
242 .PP
243 \fBAcquire()\fR
244 downloads an update for this target, if one is available\&. If a
245 \fInew_version\fR
246 is specified, that is the version that gets downloaded\&. Otherwise, the latest version is downloaded\&. Call
247 \fBInstall()\fR
248 to install the acquired update\&. The
249 \fIflags\fR
250 argument is added for future extensibility\&. No flags are currently defined, and the argument is required to be set to
251 "0"\&. This method pulls both metadata and payload data from the network\&.
252 .PP
253 \fBInstall()\fR
254 installs an already\-acquired update for this target\&. If a
255 \fInew_version\fR
256 is specified, that is the version that gets installed, assuming it has already been acquired\&. Otherwise, the latest acquired version is installed\&. The
257 \fIflags\fR
258 argument is added for future extensibility\&. No flags are currently defined, and the argument is required to be set to
259 "0"\&.
260 .PP
261 Unlike all the other methods in this interface,
262 \fBAcquire()\fR
263 and
264 \fBInstall()\fR
265 do not wait for their jobs to complete\&. Instead, they return the job\*(Aqs numeric ID and object path as soon as the job begins, so that the caller can listen for progress updates or cancel the operation\&. These methods also return the version the target will be updated to, for cases where no version was specified by the caller\&. Listen for the Manager\*(Aqs
266 \fBJobRemoved()\fR
267 signal to detect when the job is complete\&.
268 .PP
269 \fBVacuum()\fR
270 deletes old installed versions of this target to free up space\&. It returns the number of instances that have been deleted\&.
271 .PP
272 \fBGetAppStream()\fR
273 returns a list of HTTP/HTTPS URLs to this target\*(Aqs
274 \m[blue]\fBappstream catalog\fR\m[]\&\s-2\u[1]\d\s+2
275 XML files\&. If this target has no appstream catalogs, the method will return an empty list\&. These catalog files can be used by software centers (such as GNOME Software or KDE Discover) to present rich metadata about the target, including a display name, changelog, icon, and more\&. The returned catalogs will include
276 \m[blue]\fBspecial metadata\fR\m[]\&\s-2\u[2]\d\s+2
277 to allow the software center to correctly associate the catalogs with this target\&.
278 .PP
279 \fBGetVersion()\fR
280 returns the current version of this target, if any\&. The current version is the newest version that is installed\&. Note that this is not necessarily the same thing as the booted or currently\-in\-use version of the target\&. For example, on the host system the booted version is the current version most of the time, but if an update is installed and pending a reboot it will become the current version instead\&. You can query the booted version of the host system via
281 \fIIMAGE_VERSION\fR
282 in
283 /etc/os\-release\&. If the target has no current version, the function will return an empty string\&.
284 .PP
285 \fBListFeatures()\fR
286 returns a list of this target\*(Aqs optional features, by ID\&. The
287 \fIflags\fR
288 argument is added for future extensibility, and must be set to 0\&. If the target has no optional features, the method returns an empty array\&.
289 .PP
290 \fBDescribeFeature()\fR
291 returns all known information about a given optional feature\&. The
292 \fIfeature\fR
293 argument is used to pass the ID of the feature to be described\&. The
294 \fIflags\fR
295 argument is added for future extensibility, and must be set to 0\&. The returned JSON object contains several known keys\&. More keys may be added in the future\&. The currently known keys are as follows:
296 .PP
297 "name"
298 .RS 4
299 A string containing the feature\*(Aqs name\&.
300 .RE
301 .PP
302 "description"
303 .RS 4
304 An optional string that contains a user\-presentable description that identifies this feature
305 .RE
306 .PP
307 "enabled"
308 .RS 4
309 A boolean indicating whether this feature is enabled\&.
310 .RE
311 .PP
312 "documentationUrl"
313 .RS 4
314 An optional string that contains a user\-presentable HTTP/HTTPS URL to documentation about this feature\&.
315 .RE
316 .PP
317 "appstreamUrl"
318 .RS 4
319 An optional string that contains an HTTP/HTTPS URL to an
320 \m[blue]\fBappstream catalog\fR\m[]\&\s-2\u[1]\d\s+2
321 XML file containing metadata about this feature\&.
322 .RE
323 .PP
324 "transfers"
325 .RS 4
326 An optional array of strings that list which transfer definitions belong to this feature\&.
327 .RE
328 .PP
329 \fBSetFeatureEnabled()\fR
330 writes an appropriate drop\-in file to enable or disable the specified optional feature\&. If
331 \fIenable\fR
332 is zero, the feature is disabled\&. When greater than zero, the feature is enabled\&. When less than zero, the feature is reset to the distribution\*(Aqs default\&. The
333 \fIflags\fR
334 argument is added for future extensibility, and must be set to 0\&. The feature does not have to exist; this allows for graceful handling of masked features, and for preemptive decisions to be made about features that are planned to appear in future releases of the OS\&. The drop\-in will have a filename of
335 "50\-systemd\-sysupdate\-enabled\&.conf"\&. This method only changes configuration files; to actually apply the changes, clients will need to call
336 \fBAcquire()\fR
337 and
338 \fBInstall()\fR\&. Depending on the exact needs of the client, it can choose to update the system to the latest available version, or it can extend the newest existing installation in\-place (by passing in the version returned by
339 \fIGetVersion()\fR)\&. For now, this method only works with the
340 "host"
341 target\&.
342 .SS "Properties"
343 .PP
344 The
345 \fIClass\fR
346 property exposes the class of this target, which describes where it was enumerated\&. Possible values include:
347 "machine"
348 for containers and virtual machines managed by
349 \fBsystemd-machined.service\fR(8),
350 "portable"
351 for
352 \m[blue]\fBportable services\fR\m[]\&\s-2\u[3]\d\s+2,
353 "sysext"
354 for system extensions managed by
355 \fBsystemd-sysext\fR(8),
356 "confext"
357 for configuration extensions managed by
358 \fBsystemd-confext\fR(8),
359 "component"
360 for components accepted by the
361 \fB\-\-component=\fR
362 option of
363 \fBsystemd-sysupdate\fR(8), and
364 "host"
365 for the host system itself\&. At most one target will have a class of
366 "host"\&.
367 .PP
368 The
369 \fIPath\fR
370 property exposes more detail about where this target was found\&. For
371 "machine",
372 "portable",
373 "extension", and
374 "confext"
375 targets, this is the file path to the image\&. For
376 "component"
377 and
378 "host"
379 targets, this is the name of a
380 \fBsysupdate.d\fR(5)
381 directory\&.
382 .PP
383 The
384 \fIName\fR
385 property exposes the name of this target\&. Note that the name is unique within a class but is not necessarily unique between classes\&. For instance, it is possible to have both a
386 "portable"
387 target named
388 "foobar"
389 and an
390 "extension"
391 target named
392 "foobar", but it is not possible to have two
393 "portable"
394 targets named
395 "foobar"\&.
396 .SS "Security"
397 .PP
398 Method calls on this service are authenticated via
399 \m[blue]\fBpolkit\fR\m[]\&\s-2\u[4]\d\s+2\&.
400 .PP
401 \fBList()\fR,
402 \fBDescribe()\fR, and
403 \fBCheckNew()\fR
404 use the polkit action
405 org\&.freedesktop\&.sysupdate1\&.check\&. By default, this action is permitted without administrator authentication\&.
406 .PP
407 \fBAcquire()\fR
408 and
409 \fBInstall()\fR
410 use the polkit action
411 org\&.freedesktop\&.sysupdate1\&.update
412 when no version is specified\&. By default, this action is permitted without administrator authentication\&. When a version is specified,
413 org\&.freedesktop\&.sysupdate1\&.update\-to\-version
414 is used instead\&. By default, this alternate action requires administrator authentication\&.
415 .PP
416 \fBVacuum()\fR
417 uses the polkit action
418 org\&.freedesktop\&.sysupdate1\&.vacuum\&. By default, this action requires administrator authentication\&.
419 .PP
420 \fBSetFeatureEnabled()\fR
421 uses the polkit action
422 org\&.freedesktop\&.sysupdate1\&.manage\-features\&. By default, this action requires administrator authentication\&.
423 .PP
424 \fBGetAppStream()\fR,
425 \fBGetVersion()\fR,
426 \fBListFeatures()\fR, and
427 \fBDescribeFeature()\fR
428 are unauthenticated and may be called by anybody\&.
429 .PP
430 All methods called on this interface expose additional variables to the polkit rules\&.
431 "class"
432 contains the class of the Target being acted upon, and
433 "name"
434 contains the name of the same Target\&. Additionally, each method exposes its arguments to the rule\&. Flags are mapped as follows:
435 .sp
436 .RS 4
437 .ie n \{\
438 \h'-04'\(bu\h'+03'\c
439 .\}
440 .el \{\
441 .sp -1
442 .IP \(bu 2.3
443 .\}
444 \fBSD_SYSUPDATE_OFFLINE\fR
445 →
446 "update"
447 .RE
448 .SH "THE JOB OBJECT"
449 .PP
450 A job is an ongoing operation, started by one of the methods on a Target object\&.
451 .PP
452 The service exposes the following interfaces on Job objects on the bus:
453 .sp
454 .if n \{\
455 .RS 4
456 .\}
457 .nf
458 node /org/freedesktop/sysupdate1/job/_1 {
459 interface org\&.freedesktop\&.sysupdate1\&.Job {
460 methods:
461 Cancel();
462 properties:
463 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
464 readonly t Id = \&.\&.\&.;
465 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
466 readonly s Type = \*(Aq\&.\&.\&.\*(Aq;
467 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
468 readonly b Offline = \&.\&.\&.;
469 readonly u Progress = \&.\&.\&.;
470 };
471 interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
472 interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
473 interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
474 };
475 .fi
476 .if n \{\
477 .RE
478 .\}
479
480
481
482
483
484
485 .SS "Methods"
486 .PP
487 The
488 \fBCancel()\fR
489 method may be used to cancel the job\&. It takes no parameters\&.
490 .SS "Properties"
491 .PP
492 The
493 \fIId\fR
494 property exposes the numeric job ID of the job object\&.
495 .PP
496 The
497 \fIType\fR
498 property exposes the type of operation (one of:
499 "list",
500 "describe",
501 "check\-new",
502 "acquire",
503 "install",
504 "vacuum", or
505 "describe\-feature")\&.
506 .PP
507 The
508 \fIOffline\fR
509 property exposes whether the job is permitted to access the network or not\&.
510 .PP
511 The
512 \fIProgress\fR
513 property exposes the current progress of the job as a value between 0 and 100\&. It is only available for
514 "acquire"
515 and
516 "install"
517 jobs; for all other jobs it is always 0\&.
518 .SS "Security"
519 .PP
520 \fBCancel()\fR
521 uses the polkit action that corresponds to the method that started this job\&. For instance, trying to cancel a
522 "list"
523 job will require polkit to permit the
524 org\&.freedesktop\&.sysupdate1\&.check
525 action\&.
526 .SH "EXAMPLES"
527 .PP
528 \fBExample\ \&1.\ \&Introspect org\&.freedesktop\&.sysupdate1\&.Manager on the bus\fR
529 .sp
530 .if n \{\
531 .RS 4
532 .\}
533 .nf
534 $ gdbus introspect \-\-system \e
535 \-\-dest org\&.freedesktop\&.sysupdate1 \e
536 \-\-object\-path /org/freedesktop/sysupdate1
537 .fi
538 .if n \{\
539 .RE
540 .\}
541 .PP
542 \fBExample\ \&2.\ \&Introspect org\&.freedesktop\&.sysupdate1\&.Target on the bus\fR
543 .sp
544 .if n \{\
545 .RS 4
546 .\}
547 .nf
548 $ gdbus introspect \-\-system \e
549 \-\-dest org\&.freedesktop\&.sysupdate1 \e
550 \-\-object\-path /org/freedesktop/sysupdate1/target/host
551 .fi
552 .if n \{\
553 .RE
554 .\}
555 .PP
556 \fBExample\ \&3.\ \&Introspect org\&.freedesktop\&.sysupdate1\&.Job on the bus\fR
557 .sp
558 .if n \{\
559 .RS 4
560 .\}
561 .nf
562 $ gdbus introspect \-\-system \e
563 \-\-dest org\&.freedesktop\&.sysupdate1 \e
564 \-\-object\-path /org/freedesktop/sysupdate1/job/_1
565 .fi
566 .if n \{\
567 .RE
568 .\}
569 .SH "VERSIONING"
570 .PP
571 These D\-Bus interfaces follow
572 \m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[5]\d\s+2\&.
573 .SH "HISTORY"
574 .SS "The Manager Object"
575 .PP
576 \fBListTargets()\fR,
577 \fBListJobs()\fR,
578 \fBListAppStream()\fR, and
579 \fBJobRemoved()\fR
580 were added in version 257\&.
581 .SS "The Target Object"
582 .PP
583 \fBList()\fR,
584 \fBDescribe()\fR,
585 \fBCheckNew()\fR,
586 \fBAcquire()\fR,
587 \fBInstall()\fR,
588 \fBVacuum()\fR,
589 \fBGetAppStream()\fR,
590 \fBGetVersion()\fR,
591 \fBListFeatures()\fR,
592 \fBDescribeFeature()\fR,
593 \fBSetFeatureEnabled()\fR,
594 \fIClass\fR,
595 \fIName\fR, and
596 \fIPath\fR
597 were added in version 257\&.
598 .SS "The Job Object"
599 .PP
600 \fBCancel()\fR,
601 \fIId\fR,
602 \fIType\fR,
603 \fIOffline\fR, and
604 \fIProgress\fR
605 were added in version 257\&.
606 .SH "SEE ALSO"
607 .PP
608 \fBsystemd\fR(1), \fBsystemd-sysupdated.service\fR(8), \fBupdatectl\fR(1)
609 .SH "NOTES"
610 .IP " 1." 4
611 appstream catalog
612 .RS 4
613 \%https://wwww.freedesktop.org/software/appstream/docs/chap-CatalogData.html
614 .RE
615 .IP " 2." 4
616 special metadata
617 .RS 4
618 \%https://systemd.io/APPSTREAM_BUNDLE
619 .RE
620 .IP " 3." 4
621 portable services
622 .RS 4
623 \%https://systemd.io/PORTABLE_SERVICES
624 .RE
625 .IP " 4." 4
626 polkit
627 .RS 4
628 \%https://www.freedesktop.org/software/polkit/docs/latest/
629 .RE
630 .IP " 5." 4
631 the usual interface versioning guidelines
632 .RS 4
633 \%https://0pointer.de/blog/projects/versioning-dbus.html
634 .RE