'\" t .TH "ORG\&.FREEDESKTOP\&.SYSUPDATE1" "5" "" "systemd 259.1" "org.freedesktop.sysupdate1" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" org.freedesktop.sysupdate1 \- The D\-Bus interface of systemd\-sysupdated .SH "INTRODUCTION" .PP \fBsystemd-sysupdated.service\fR(8) is a system service that allows unprivileged clients to update the system\&. This page describes the D\-Bus interface\&. .PP \fIWARNING!\fR This API is currently \fIunstable\fR and is thus subject to breaking changes between versions of systemd\&. .SH "THE MANAGER OBJECT" .PP The service exposes the following interfaces on the Manager object on the bus: .sp .if n \{\ .RS 4 .\} .nf node /org/freedesktop/sysupdate1 { interface org\&.freedesktop\&.sysupdate1\&.Manager { methods: ListTargets(out a(sso) targets); ListJobs(out a(tsuo) jobs); ListAppStream(out as urls); signals: JobRemoved(t id, o path, i status); }; interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; }; .fi .if n \{\ .RE .\} .SS "Methods" .PP \fBListTargets()\fR 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 \fIClass\fR property below for an explanation of the possible values), a string with the name of the target, and the target object path\&. .PP \fBListJobs()\fR 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 \fIType\fR property below for an explanation of the possible values), the job\*(Aqs progress, and the job\*(Aqs object path\&. .PP \fBListAppStream()\fR returns an array of all the appstream catalog URLs that this service knows about\&. See Target\*(Aqs \fIGetAppStream()\fR method below for more details\&. .SS "Signals" .PP The \fBJobRemoved()\fR 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\&. "EXIT_FAILURE"), and a negative status should be treated as a negative errno\-style error code (i\&.e\&. "\-EINVAL")\&. .SH "THE TARGET OBJECT" .PP A target is a component of the system (i\&.e\&. the host itself, a sysext, a confext, etc\&.) that can be updated by \fBsystemd-sysupdate\fR(8)\&. .PP The service exposes the following interfaces on Target objects on the bus: .sp .if n \{\ .RS 4 .\} .nf node /org/freedesktop/sysupdate1/target/host { interface org\&.freedesktop\&.sysupdate1\&.Target { methods: List(in t flags, out as versions); Describe(in s version, in t flags, out s json); CheckNew(out s new_version); Update(in s new_version, in t flags, out s new_version, out t job_id, out o job_path); Vacuum(out u instances, out u disabled_transfers); GetAppStream(out as appstream); GetVersion(out s version); ListFeatures(in t flags, out as features); DescribeFeature(in s feature, in t flags, out s json); SetFeatureEnabled(in s feature, in i enabled, in t flags); properties: @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") readonly s Class = \*(Aq\&.\&.\&.\*(Aq; @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") readonly s Name = \*(Aq\&.\&.\&.\*(Aq; @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") readonly s Path = \*(Aq\&.\&.\&.\*(Aq; }; interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; }; .fi .if n \{\ .RE .\} .SS "Methods" .PP \fBList()\fR returns a list of versions available for this target\&. Additional options may be passed through the \fIflags\fR argument\&. Valid flags are defined as follows: .sp .if n \{\ .RS 4 .\} .nf #define SD_SYSUPDATE_OFFLINE (UINT64_C(1) << 0) .fi .if n \{\ .RE .\} .PP When \fBSD_SYSUPDATE_OFFLINE\fR 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 \fBDescribe()\fR to query more information about each version returned by this method\&. .PP \fBDescribe()\fR returns all known information about a given version as a JSON object\&. The \fIversion\fR argument is used to pass the version to be described\&. Additional options may be passed through the \fIflags\fR argument\&. This method supports the same flags as \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: .PP "version" .RS 4 A string containing the version number\&. .RE .PP "newest" .RS 4 A boolean indicating whether this version is the latest available for the target\&. .RE .PP "available" .RS 4 A boolean indicating whether this version is available for download\&. .RE .PP "installed" .RS 4 A boolean indicating whether this version is installed locally\&. .RE .PP "obsolete" .RS 4 A boolean indicating whether this version is considered obsolete by the service, and is therefore disallowed from being installed\&. .RE .PP "protected" .RS 4 A boolean indicating whether this version is exempt from deletion by a \fBVacuum()\fR operation\&. .RE .PP "incomplete" .RS 4 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 \fBUpdate()\fR on that version\&. .RE .PP "changelogUrls" .RS 4 A list of strings that contain user\-presentable URLs to change logs associated with this version\&. .RE .PP \fBCheckNew()\fR 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 \fBDescribe()\fR to query more information about the version returned by this method\&. .PP \fBUpdate()\fR installs an update for this target\&. If a \fInew_version\fR is specified, that is the version that gets installed\&. Otherwise, the latest version is installed\&. The \fIflags\fR argument is added for future extensibility\&. No flags are currently defined, and the argument is required to be set to "0"\&. Unlike all the other methods in this interface, \fBUpdate()\fR does not wait for its job to complete\&. Instead, it returns 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\&. This method also returns the version the target will be updated to, for cases where no version was specified by the caller\&. This method pulls both metadata and payload data from the network\&. Listen for the Manager\*(Aqs \fBJobRemoved()\fR signal to detect when the job is complete\&. .PP \fBVacuum()\fR deletes old installed versions of this target to free up space\&. It returns the number of instances that have been deleted\&. .PP \fBGetAppStream()\fR returns a list of HTTP/HTTPS URLs to this target\*(Aqs \m[blue]\fBappstream catalog\fR\m[]\&\s-2\u[1]\d\s+2 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 \m[blue]\fBspecial metadata\fR\m[]\&\s-2\u[2]\d\s+2 to allow the software center to correctly associate the catalogs with this target\&. .PP \fBGetVersion()\fR 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 \fIIMAGE_VERSION\fR in /etc/os\-release\&. If the target has no current version, the function will return an empty string\&. .PP \fBListFeatures()\fR returns a list of this target\*(Aqs optional features, by ID\&. The \fIflags\fR 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\&. .PP \fBDescribeFeature()\fR returns all known information about a given optional feature\&. The \fIfeature\fR argument is used to pass the ID of the feature to be described\&. The \fIflags\fR 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: .PP "name" .RS 4 A string containing the feature\*(Aqs name\&. .RE .PP "description" .RS 4 An optional string that contains a user\-presentable description that identifies this feature .RE .PP "enabled" .RS 4 A boolean indicating whether this feature is enabled\&. .RE .PP "documentationUrl" .RS 4 An optional string that contains a user\-presentable HTTP/HTTPS URL to documentation about this feature\&. .RE .PP "appstreamUrl" .RS 4 An optional string that contains an HTTP/HTTPS URL to an \m[blue]\fBappstream catalog\fR\m[]\&\s-2\u[1]\d\s+2 XML file containing metadata about this feature\&. .RE .PP "transfers" .RS 4 An optional array of strings that list which transfer definitions belong to this feature\&. .RE .PP \fBSetFeatureEnabled()\fR writes an appropriate drop\-in file to enable or disable the specified optional feature\&. If \fIenable\fR 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 \fIflags\fR 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 "50\-systemd\-sysupdate\-enabled\&.conf"\&. This method only changes configuration files; to actually apply the changes, clients will need to call \fBUpdate()\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 \fIGetVersion()\fR)\&. For now, this method only works with the "host" target\&. .SS "Properties" .PP The \fIClass\fR property exposes the class of this target, which describes where it was enumerated\&. Possible values include: "machine" for containers and virtual machines managed by \fBsystemd-machined.service\fR(8), "portable" for \m[blue]\fBportable services\fR\m[]\&\s-2\u[3]\d\s+2, "sysext" for system extensions managed by \fBsystemd-sysext\fR(8), "confext" for configuration extensions managed by \fBsystemd-confext\fR(8), "component" for components accepted by the \fB\-\-component=\fR option of \fBsystemd-sysupdate\fR(8), and "host" for the host system itself\&. At most one target will have a class of "host"\&. .PP The \fIPath\fR property exposes more detail about where this target was found\&. For "machine", "portable", "extension", and "confext" targets, this is the file path to the image\&. For "component" and "host" targets, this is the name of a \fBsysupdate.d\fR(5) directory\&. .PP The \fIName\fR 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 "portable" target named "foobar" and an "extension" target named "foobar", but it is not possible to have two "portable" targets named "foobar"\&. .SS "Security" .PP Method calls on this service are authenticated via \m[blue]\fBpolkit\fR\m[]\&\s-2\u[4]\d\s+2\&. .PP \fBList()\fR, \fBDescribe()\fR, and \fBCheckNew()\fR use the polkit action org\&.freedesktop\&.sysupdate1\&.check\&. By default, this action is permitted without administrator authentication\&. .PP \fBUpdate()\fR uses the polkit action org\&.freedesktop\&.sysupdate1\&.update when no version is specified\&. By default, this action is permitted without administrator authentication\&. When a version is specified, org\&.freedesktop\&.sysupdate1\&.update\-to\-version is used instead\&. By default, this alternate action requires administrator authentication\&. .PP \fBVacuum()\fR uses the polkit action org\&.freedesktop\&.sysupdate1\&.vacuum\&. By default, this action requires administrator authentication\&. .PP \fBSetFeatureEnabled()\fR uses the polkit action org\&.freedesktop\&.sysupdate1\&.manage\-features\&. By default, this action requires administrator authentication\&. .PP \fBGetAppStream()\fR, \fBGetVersion()\fR, \fBListFeatures()\fR, and \fBDescribeFeature()\fR are unauthenticated and may be called by anybody\&. .PP All methods called on this interface expose additional variables to the polkit rules\&. "class" contains the class of the Target being acted upon, and "name" contains the name of the same Target\&. Additionally, each method exposes its arguments to the rule\&. Flags are mapped as follows: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fBSD_SYSUPDATE_OFFLINE\fR → "update" .RE .SH "THE JOB OBJECT" .PP A job is an ongoing operation, started by one of the methods on a Target object\&. .PP The service exposes the following interfaces on Job objects on the bus: .sp .if n \{\ .RS 4 .\} .nf node /org/freedesktop/sysupdate1/job/_1 { interface org\&.freedesktop\&.sysupdate1\&.Job { methods: Cancel(); properties: @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") readonly t Id = \&.\&.\&.; @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") readonly s Type = \*(Aq\&.\&.\&.\*(Aq; @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") readonly b Offline = \&.\&.\&.; readonly u Progress = \&.\&.\&.; }; interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; }; .fi .if n \{\ .RE .\} .SS "Methods" .PP The \fBCancel()\fR method may be used to cancel the job\&. It takes no parameters\&. .SS "Properties" .PP The \fIId\fR property exposes the numeric job ID of the job object\&. .PP The \fIType\fR property exposes the type of operation (one of: "list", "describe", "check\-new", "update", "vacuum", or "describe\-feature")\&. .PP The \fIOffline\fR property exposes whether the job is permitted to access the network or not\&. .PP The \fIProgress\fR property exposes the current progress of the job as a value between 0 and 100\&. It is only available for "update" jobs; for all other jobs it is always 0\&. .SS "Security" .PP \fBCancel()\fR uses the polkit action that corresponds to the method that started this job\&. For instance, trying to cancel a "list" job will require polkit to permit the org\&.freedesktop\&.sysupdate1\&.check action\&. .SH "EXAMPLES" .PP \fBExample\ \&1.\ \&Introspect org\&.freedesktop\&.sysupdate1\&.Manager on the bus\fR .sp .if n \{\ .RS 4 .\} .nf $ gdbus introspect \-\-system \e \-\-dest org\&.freedesktop\&.sysupdate1 \e \-\-object\-path /org/freedesktop/sysupdate1 .fi .if n \{\ .RE .\} .PP \fBExample\ \&2.\ \&Introspect org\&.freedesktop\&.sysupdate1\&.Target on the bus\fR .sp .if n \{\ .RS 4 .\} .nf $ gdbus introspect \-\-system \e \-\-dest org\&.freedesktop\&.sysupdate1 \e \-\-object\-path /org/freedesktop/sysupdate1/target/host .fi .if n \{\ .RE .\} .PP \fBExample\ \&3.\ \&Introspect org\&.freedesktop\&.sysupdate1\&.Job on the bus\fR .sp .if n \{\ .RS 4 .\} .nf $ gdbus introspect \-\-system \e \-\-dest org\&.freedesktop\&.sysupdate1 \e \-\-object\-path /org/freedesktop/sysupdate1/job/_1 .fi .if n \{\ .RE .\} .SH "VERSIONING" .PP These D\-Bus interfaces follow \m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[5]\d\s+2\&. .SH "HISTORY" .SS "The Manager Object" .PP \fBListTargets()\fR, \fBListJobs()\fR, \fBListAppStream()\fR, and \fBJobRemoved()\fR were added in version 257\&. .SS "The Target Object" .PP \fBList()\fR, \fBDescribe()\fR, \fBCheckNew()\fR, \fBUpdate()\fR, \fBVacuum()\fR, \fBGetAppStream()\fR, \fBGetVersion()\fR, \fBListFeatures()\fR, \fBDescribeFeature()\fR, \fBSetFeatureEnabled()\fR, \fIClass\fR, \fIName\fR, and \fIPath\fR were added in version 257\&. .SS "The Job Object" .PP \fBCancel()\fR, \fIId\fR, \fIType\fR, \fIOffline\fR, and \fIProgress\fR were added in version 257\&. .SH "SEE ALSO" .PP \fBsystemd\fR(1), \fBsystemd-sysupdated.service\fR(8), \fBupdatectl\fR(1) .SH "NOTES" .IP " 1." 4 appstream catalog .RS 4 \%https://wwww.freedesktop.org/software/appstream/docs/chap-CatalogData.html .RE .IP " 2." 4 special metadata .RS 4 \%https://systemd.io/APPSTREAM_BUNDLE .RE .IP " 3." 4 portable services .RS 4 \%https://systemd.io/PORTABLE_SERVICES .RE .IP " 4." 4 polkit .RS 4 \%https://www.freedesktop.org/software/polkit/docs/latest/ .RE .IP " 5." 4 the usual interface versioning guidelines .RS 4 \%https://0pointer.de/blog/projects/versioning-dbus.html .RE