org.freedesktop.sysupdate1 - Man Page

ListTargets() returns a list all known update targets​. It returns an array of structures which consist of a string indicating the target's class (see Target's Class property below for an explanation of the possible values), a string with the name of the target, and the target object path​.

ListJobs() 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's Type property below for an explanation of the possible values), the job's progress, and the job's object path​.

ListAppStream() returns an array of all the appstream catalog URLs that this service knows about​. See Target's GetAppStream() method below for more details​.

The JobRemoved() 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 succeeded​. 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")​.

List() returns a list of versions available for this target​. Additional options may be passed through the flags argument​. Valid flags are defined as follows:

#define SD_SYSUPDATE_OFFLINE    (UINT64_C(1) << 0)

When SD_SYSUPDATE_OFFLINE 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 Describe() to query more information about each version returned by this method​.

Describe() returns all known information about a given version as a JSON object​. The version argument is used to pass the version to be described​. Additional options may be passed through the flags argument​. This method supports the same flags as List()​. The returned JSON object contains several known keys​. More keys may be added in the future​. The currently known keys are as follows:

"version"

A string containing the version number​.

"newest"

A boolean indicating whether this version is the latest available for the target​.

"available"

A boolean indicating whether this version is available for download​.

"installed"

A boolean indicating whether this version is installed locally​.

"obsolete"

A boolean indicating whether this version is considered obsolete by the service, and is therefore disallowed from being installed​.

"protected"

A boolean indicating whether this version is exempt from deletion by a Vacuum() operation​.

"incomplete"

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 Acquire() and Install() on that version​.

"changelogUrls"

A list of strings that contain user-presentable URLs to change logs associated with this version​.

CheckNew() 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 Describe() to query more information about the version returned by this method​.

Acquire() downloads an update for this target, if one is available​. If a new_version is specified, that is the version that gets downloaded​. Otherwise, the latest version is downloaded​. Call Install() to install the acquired update​. The flags argument is added for future extensibility​. No flags are currently defined, and the argument is required to be set to "0"​. This method pulls both metadata and payload data from the network​.

Install() installs an already-acquired update for this target​. If a new_version is specified, that is the version that gets installed, assuming it has already been acquired​. Otherwise, the latest acquired version is installed​. The flags 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, Acquire() and Install() do not wait for their jobs to complete​. Instead, they return the job's 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's JobRemoved() signal to detect when the job is complete​.

Vacuum() deletes old installed versions of this target to free up space​. It returns the number of instances that have been deleted​.

GetAppStream() returns a list of HTTP/HTTPS URLs to this target's appstream catalog​^[1] 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 special metadata​^[2] to allow the software center to correctly associate the catalogs with this target​.

GetVersion() 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 IMAGE_VERSION in /etc/os-release​. If the target has no current version, the function will return an empty string​.

ListFeatures() returns a list of this target's optional features, by ID​. The flags 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​.

DescribeFeature() returns all known information about a given optional feature​. The feature argument is used to pass the ID of the feature to be described​. The flags 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:

"id"

A string containing the feature's ID​.

"description"

An optional string that contains a user-presentable description that identifies this feature

"enabled"

A boolean indicating whether this feature is enabled​.

"suggested"

An optional boolean indicating whether this feature is suggested for enablement​. If omitted, it could not be determined whether the feature is suggested​.

"documentation"

An optional array of strings containing user-presentable HTTP/HTTPS URLs to documentation about this feature​.

"appStream"

An optional string that contains an HTTP/HTTPS URL to an appstream catalog​^[1] XML file containing metadata about this feature​.

"transfers"

An optional array of strings that list which transfer definitions belong to this feature​.

SetFeatureEnabled() writes an appropriate drop-in file to enable or disable the specified optional feature​. If enable 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's default​. The flags 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 Acquire() and Install()​. 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 GetVersion())​. For now, this method only works with the "host" target​.

The Class property exposes the class of this target, which describes where it was enumerated​. Possible values include: "machine" for containers and virtual machines managed by systemd-machined.service(8), "portable" for portable services​^[3], "sysext" for system extensions managed by systemd-sysext(8), "confext" for configuration extensions managed by systemd-confext(8), "component" for components accepted by the --component= option of systemd-sysupdate(8), and "host" for the host system itself​. At most one target will have a class of "host"​.

The Path 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 sysupdate.d(5) directory​.

The Name 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"​.

Method calls on this service are authenticated via polkit​^[4]​.

List(), Describe(), and CheckNew() use the polkit action org​.freedesktop​.sysupdate1​.check​. By default, this action is permitted without administrator authentication​. Cancellation of these methods uses the polkit action org​.freedesktop​.sysupdate1​.cancel-check​. By default, this cancellation action is permitted without administrator authentication​.

Acquire() and Install() use 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​. Cancellation of these methods uses the polkit actions org​.freedesktop​.sysupdate1​.cancel-update and org​.freedesktop​.sysupdate1​.cancel-update-to-version​. By default, these cancellation actions are permitted without administrator authentication​.

Vacuum() uses the polkit action org​.freedesktop​.sysupdate1​.vacuum​. By default, this action requires administrator authentication​. Cancellation of this method uses the polkit action org​.freedesktop​.sysupdate1​.cancel-vacuum​. By default, this cancellation action is permitted without administrator authentication​.

SetFeatureEnabled() uses the polkit action org​.freedesktop​.sysupdate1​.manage-features​. By default, this action requires administrator authentication​. Cancellation is not supported for this method​.

GetAppStream(), GetVersion(), ListFeatures(), and DescribeFeature() are unauthenticated and may be called by anybody​. Cancellation is not supported for these methods, or is always allowed without administrator authentication​.

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:

• SD_SYSUPDATE_OFFLINE → "update"

The Cancel() method may be used to cancel the job​. It takes no parameters​.

The Id property exposes the numeric job ID of the job object​.

The Type property exposes the type of operation (one of: "list", "describe", "check-new", "acquire", "install", "vacuum", or "describe-feature")​.

The Offline property exposes whether the job is permitted to access the network or not​.

The Progress property exposes the current progress of the job as a value between 0 and 100​. It is only available for "acquire" and "install" jobs; for all other jobs it is always 0​.

Cancel() 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​.

ListTargets(), ListJobs(), ListAppStream(), and JobRemoved() were added in version 257​.

List(), Describe(), CheckNew(), Acquire(), Install(), Vacuum(), GetAppStream(), GetVersion(), ListFeatures(), DescribeFeature(), SetFeatureEnabled(), Class, Name, and Path were added in version 257​.

Cancel(), Id, Type, Offline, and Progress were added in version 257​.