|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | INTRODUCTION | THE MANAGER OBJECT | THE TARGET OBJECT | THE JOB OBJECT | EXAMPLES | VERSIONING | HISTORY | SEE ALSO | NOTES | COLOPHON |
|
|
|
ORG.FREE...YSUPDATE1(5) org.freedesktop.sysupdate1ORG.FREE...YSUPDATE1(5)
org.freedesktop.sysupdate1 - The D-Bus interface of
systemd-sysupdated
systemd-sysupdated.service(8) is a system service that allows
unprivileged clients to update the system. This page describes the
D-Bus interface.
WARNING! This API is currently unstable and is thus subject to
breaking changes between versions of systemd.
The 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 { ... };
};
Methods
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.
Signals
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 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").
A target is a component of the system (i.e. the host itself, a
sysext, a confext, etc.) that can be updated by
systemd-sysupdate(8).
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 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 = '...';
@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 { ... };
};
Methods
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
Update() 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.
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[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:
"name"
A string containing the feature's name.
"description"
An optional string that contains a user-presentable
description that identifies this feature
"enabled"
A boolean indicating whether this feature is enabled.
"documentationUrl"
An optional string that contains a user-presentable HTTP/HTTPS
URL to documentation about this feature.
"appstreamUrl"
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 Update(). 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.
Properties
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".
Security
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.
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.
SetFeatureEnabled() uses the polkit action
org.freedesktop.sysupdate1.manage-features. By default, this
action requires administrator authentication.
GetAppStream(), GetVersion(), ListFeatures(), and
DescribeFeature() 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 → "update"
A 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 { ... };
};
Methods
The Cancel() method may be used to cancel the job. It takes no
parameters.
Properties
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", "update", "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 "update" jobs;
for all other jobs it is always 0.
Security
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.
Example 1. Introspect org.freedesktop.sysupdate1.Manager on the
bus
$ gdbus introspect --system \
--dest org.freedesktop.sysupdate1 \
--object-path /org/freedesktop/sysupdate1
Example 2. Introspect org.freedesktop.sysupdate1.Target on the bus
$ gdbus introspect --system \
--dest org.freedesktop.sysupdate1 \
--object-path /org/freedesktop/sysupdate1/target/host
Example 3. Introspect org.freedesktop.sysupdate1.Job on the bus
$ gdbus introspect --system \
--dest org.freedesktop.sysupdate1 \
--object-path /org/freedesktop/sysupdate1/job/_1
These D-Bus interfaces follow the usual interface versioning
guidelines[5].
The Manager Object
ListTargets(), ListJobs(), ListAppStream(), and JobRemoved() were
added in version 257.
The Target Object
List(), Describe(), CheckNew(), Update(), Vacuum(),
GetAppStream(), GetVersion(), ListFeatures(), DescribeFeature(),
SetFeatureEnabled(), Class, Name, and Path were added in version
257.
The Job Object
Cancel(), Id, Type, Offline, and Progress were added in version
257.
systemd(1), systemd-sysupdated.service(8), updatectl(1)
1. appstream catalog
https://wwww.freedesktop.org/software/appstream/docs/chap-CatalogData.html
2. special metadata
https://systemd.io/APPSTREAM_BUNDLE
3. portable services
https://systemd.io/PORTABLE_SERVICES
4. polkit
https://www.freedesktop.org/software/polkit/docs/latest/
5. the usual interface versioning guidelines
https://0pointer.de/blog/projects/versioning-dbus.html
This page is part of the systemd (systemd system and service
manager) project. Information about the project can be found at
⟨http://www.freedesktop.org/wiki/Software/systemd⟩. If you have a
bug report for this manual page, see
⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩.
This page was obtained from the project's upstream Git repository
⟨https://github.com/systemd/systemd.git⟩ on 2025-08-11. (At that
time, the date of the most recent commit that was found in the
repository was 2025-08-11.) If you discover any rendering
problems in this HTML version of the page, or you believe there is
a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
[email protected]
systemd 258~rc2 ORG.FREE...YSUPDATE1(5)
Pages that refer to this page: updatectl(1), systemd.directives(7), systemd.index(7), systemd-sysupdated.service(8)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|