org.freedesktop.sysupdate1systemdorg.freedesktop.sysupdate15org.freedesktop.sysupdate1The D-Bus interface of systemd-sysupdatedIntroductionsystemd-sysupdated.service8
is a system service that allows unprivileged clients to update the system. This page describes the D-Bus
interface.The Manager ObjectThe service exposes the following interfaces on the Manager object on the bus:
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 { ... };
};
MethodsListTargets() 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.SignalsThe 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 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).The Target ObjectA target is a component of the system (i.e. the host itself, a sysext, a confext, etc.) that
can be updated by
systemd-sysupdate8.
The service exposes the following interfaces on Target objects on the bus:
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 count);
GetAppStream(out as appstream);
GetVersion(out s version);
properties:
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Class = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Name = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Path = '...';
};
interface org.freedesktop.DBus.Peer { ... };
interface org.freedesktop.DBus.Introspectable { ... };
interface org.freedesktop.DBus.Properties { ... };
};
MethodsList() 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:versionA string containing the version number.newestA boolean indicating whether this version is the latest available for the target.availableA boolean indicating whether this version is available for download.installedA boolean indicating whether this version is installed locally.obsoleteA boolean indicating whether this version is considered obsolete by the service,
and is therefore disallowed from being installed.protectedA boolean indicating whether this version is exempt from deletion by a
Vacuum() operation.incompleteA 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 Update() on that version.changelog_urlsA list of strings that contain user-presentable URLs to ChangeLogs 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.
Update() installs an update for this target. If a
new_version is specified, that is the version that gets installed. Otherwise, the
latest 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, Update()
does not wait for its job to complete. Instead, it returns 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. 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'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
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 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 isn't 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.PropertiesThe 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.service8,
portable for portable services,
sysext for system extensions managed by
systemd-sysext8,
confext for configuration extensions managed by
systemd-confext8,
component for components accepted by the option of
systemd-sysupdate8,
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.d5
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.SecurityMethod calls on this service are authenticated via
polkit.List(), Describe(), and CheckNew()
use the polkit action org.freedesktop.sysupdate1.check.
By default, this action is permitted without administrator authentication.Update() 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.Vacuum() uses the polkit action
org.freedesktop.sysupdate1.vacuum. By default, this action requires
administrator authentication.GetAppStream() and GetVersion() are unauthenticated and
may be called by anybody.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 → updateThe Job ObjectA job is an ongoing operation, started by one of the methods on a Target object.The service exposes the following interfaces on Job objects on the bus:
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 = '...';
@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 { ... };
};
MethodsThe Cancel() method may be used to cancel the job. It takes no
parameters.PropertiesThe 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, update, or vacuum).
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 update jobs; for all other jobs
it is always 0.SecurityCancel() 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.ExamplesIntrospect org.freedesktop.sysupdate1.Manager on the bus$ gdbus introspect --system \
--dest org.freedesktop.sysupdate1 \
--object-path /org/freedesktop/sysupdate1
Introspect org.freedesktop.sysupdate1.Target on the bus$ gdbus introspect --system \
--dest org.freedesktop.sysupdate1 \
--object-path /org/freedesktop/sysupdate1/target/host
Introspect org.freedesktop.sysupdate1.Job on the bus$ gdbus introspect --system \
--dest org.freedesktop.sysupdate1 \
--object-path /org/freedesktop/sysupdate1/job/_1
HistoryThe Manager ObjectListTargets(),
ListJobs(),
ListAppStream(), and
JobRemoved() were added in version 257.The Target ObjectList(),
Describe(),
CheckNew(),
Update(),
Vacuum(),
GetAppStream(),
GetVersion(),
Class,
Name, and
Path were added in version 257.The Job ObjectCancel(),
Id,
Type,
Offline, and
Progress were added in version 257.