mirror of
https://github.com/systemd/systemd.git
synced 2024-12-23 21:35:11 +03:00
488 lines
22 KiB
XML
488 lines
22 KiB
XML
<?xml version='1.0'?>
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" >
|
|
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
|
|
|
|
<refentry id="org.freedesktop.sysupdate1" conditional='ENABLE_SYSUPDATE'
|
|
xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<refentryinfo>
|
|
<title>org.freedesktop.sysupdate1</title>
|
|
<productname>systemd</productname>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>org.freedesktop.sysupdate1</refentrytitle>
|
|
<manvolnum>5</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>org.freedesktop.sysupdate1</refname>
|
|
<refpurpose>The D-Bus interface of systemd-sysupdated</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1>
|
|
<title>Introduction</title>
|
|
|
|
<para>
|
|
<citerefentry><refentrytitle>systemd-sysupdated.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
|
is a system service that allows unprivileged clients to update the system. This page describes the D-Bus
|
|
interface.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>The Manager Object</title>
|
|
|
|
<para>The service exposes the following interfaces on the Manager object on the bus:</para>
|
|
|
|
<programlisting executable="systemd-sysupdated" node="/org/freedesktop/sysupdate1" interface="org.freedesktop.sysupdate1.Manager">
|
|
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 { ... };
|
|
};
|
|
</programlisting>
|
|
|
|
<!--Autogenerated cross-references for systemd.directives, do not edit-->
|
|
|
|
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.sysupdate1.Manager"/>
|
|
|
|
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.sysupdate1.Manager"/>
|
|
|
|
<variablelist class="dbus-method" generated="True" extra-ref="ListTargets()"/>
|
|
|
|
<variablelist class="dbus-method" generated="True" extra-ref="ListJobs()"/>
|
|
|
|
<variablelist class="dbus-method" generated="True" extra-ref="ListAppStream()"/>
|
|
|
|
<variablelist class="dbus-signal" generated="True" extra-ref="JobRemoved()"/>
|
|
|
|
<!--End of Autogenerated section-->
|
|
|
|
<refsect2>
|
|
<title>Methods</title>
|
|
|
|
<para><function>ListTargets()</function> 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
|
|
<varname>Class</varname> property below for an explanation of the possible values), a string
|
|
with the name of the target, and the target object path.</para>
|
|
|
|
<para><function>ListJobs()</function> 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
|
|
<varname>Type</varname> property below for an explanation of the possible values), the job's progress,
|
|
and the job's object path.</para>
|
|
|
|
<para><function>ListAppStream()</function> returns an array of all the appstream catalog URLs that this
|
|
service knows about. See Target's <varname>GetAppStream()</varname> method below for more
|
|
details.</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Signals</title>
|
|
|
|
<para>The <function>JobRemoved()</function> 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. <literal>EXIT_FAILURE</literal>), and a negative status should be treated as a
|
|
negative errno-style error code (i.e. <literal>-EINVAL</literal>).</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>The Target Object</title>
|
|
|
|
<para>A target is a component of the system (i.e. the host itself, a sysext, a confext, etc.) that
|
|
can be updated by
|
|
<citerefentry><refentrytitle>systemd-sysupdate</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
|
|
</para>
|
|
|
|
<para>The service exposes the following interfaces on Target objects on the bus:</para>
|
|
|
|
<programlisting executable="systemd-sysupdated" node="/org/freedesktop/sysupdate1/target/host" interface="org.freedesktop.sysupdate1.Target">
|
|
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 { ... };
|
|
};
|
|
</programlisting>
|
|
|
|
<!--Autogenerated cross-references for systemd.directives, do not edit-->
|
|
|
|
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.sysupdate1.Target"/>
|
|
|
|
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.sysupdate1.Target"/>
|
|
|
|
<variablelist class="dbus-method" generated="True" extra-ref="List()"/>
|
|
|
|
<variablelist class="dbus-method" generated="True" extra-ref="Describe()"/>
|
|
|
|
<variablelist class="dbus-method" generated="True" extra-ref="CheckNew()"/>
|
|
|
|
<variablelist class="dbus-method" generated="True" extra-ref="Update()"/>
|
|
|
|
<variablelist class="dbus-method" generated="True" extra-ref="Vacuum()"/>
|
|
|
|
<variablelist class="dbus-method" generated="True" extra-ref="GetAppStream()"/>
|
|
|
|
<variablelist class="dbus-method" generated="True" extra-ref="GetVersion()"/>
|
|
|
|
<variablelist class="dbus-property" generated="True" extra-ref="Class"/>
|
|
|
|
<variablelist class="dbus-property" generated="True" extra-ref="Name"/>
|
|
|
|
<variablelist class="dbus-property" generated="True" extra-ref="Path"/>
|
|
|
|
<!--End of Autogenerated section-->
|
|
|
|
<refsect2>
|
|
<title>Methods</title>
|
|
|
|
<para><function>List()</function> returns a list of versions available for this target. The
|
|
<varname>flags</varname> argument can be used to pass additional options, with bit 0 mapping to
|
|
<option>offline</option>. When <option>offline</option> is true, 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 <function>Describe()</function> to query more information about each
|
|
version returned by this method.</para>
|
|
|
|
<para><function>Describe()</function> returns all known information about a given version as a JSON
|
|
object. The <varname>version</varname> argument is used to pass the version to be described. Additional
|
|
options may be passed through the <varname>flags</varname> argument. The only supported value currently
|
|
is <varname>SD_SYSUPDATE_OFFLINE</varname>, which prevents the call from accessing the network
|
|
and restricts results to locally installed versions. This flag is defined as follows:</para>
|
|
|
|
<programlisting>
|
|
#define SD_SYSUPDATE_OFFLINE (UINT64_C(1) << 0)
|
|
</programlisting>
|
|
|
|
<para>The returned JSON object contains several known keys. More keys may be added in the future. The
|
|
currently known keys are as follows:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>version</term>
|
|
<listitem><para>A string containing the version number.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>newest</term>
|
|
<listitem><para>A boolean indicating whether this version is the latest available for the target.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>available</term>
|
|
<listitem><para>A boolean indicating whether this version is available for download.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>installed</term>
|
|
<listitem><para>A boolean indicating whether this version is installed locally.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>obsolete</term>
|
|
<listitem><para>A boolean indicating whether this version is considered obsolete by the service,
|
|
and is therefore disallowed from being installed.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>protected</term>
|
|
<listitem><para>A boolean indicating whether this version is exempt from deletion by a
|
|
<function>Vacuum()</function> operation.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>changelog_urls</term>
|
|
<listitem><para>A list of strings that contain user-presentable URLs to ChangeLogs associated with
|
|
this version.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para><function>CheckNew()</function> 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
|
|
<function>Describe()</function> to query more information about the version returned by this method.
|
|
</para>
|
|
|
|
<para><function>Update()</function> installs an update for this target. If a
|
|
<varname>new_version</varname> is specified, that is the version that gets installed. Otherwise, the
|
|
latest version is installed. The <varname>flags</varname> argument is added for future
|
|
extensibility. No flags are currently defined, and the argument is required to be set to
|
|
<literal>0</literal>. Unlike all the other methods in this interface, <function>Update()</function>
|
|
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 <function>JobRemoved()</function> signal to detect when the job is complete.</para>
|
|
|
|
<para><function>Vacuum()</function> deletes old installed versions of this target to free up space.
|
|
It returns the number of instances that have been deleted.</para>
|
|
|
|
<para><function>GetAppStream()</function> returns a list of HTTP/HTTPS URLs to this target's
|
|
<ulink url="https://wwww.freedesktop.org/software/appstream/docs/chap-CatalogData.html">appstream catalog</ulink>
|
|
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 <ulink url="https://systemd.io/APPSTREAM_BUNDLE">special metadata</ulink> to allow the
|
|
software center to correctly associate the catalogs with this target.</para>
|
|
|
|
<para><function>GetVersion()</function> 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
|
|
<varname>IMAGE_VERSION</varname> in <filename>/etc/os-release</filename>. If the target has no current
|
|
version, the function will return an empty string.</para>
|
|
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Properties</title>
|
|
|
|
<para>The <varname>Class</varname> property exposes the class of this target, which describes
|
|
where it was enumerated. Possible values include: <literal>machine</literal> for containers and
|
|
virtual machines managed by
|
|
<citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
|
|
<literal>portable</literal> for <ulink url="https://systemd.io/PORTABLE_SERVICES">portable services</ulink>,
|
|
<literal>sysext</literal> for system extensions managed by
|
|
<citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
|
|
<literal>confext</literal> for configuration extensions managed by
|
|
<citerefentry><refentrytitle>systemd-confext</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
|
|
<literal>component</literal> for components accepted by the <option>--component=</option> option of
|
|
<citerefentry><refentrytitle>systemd-sysupdate</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
|
|
and <literal>host</literal> for the host system itself. At most one target will have a class of
|
|
<literal>host</literal>.</para>
|
|
|
|
<para>The <varname>Path</varname> property exposes more detail about where this target was found.
|
|
For <literal>machine</literal>, <literal>portable</literal>, <literal>extension</literal>, and
|
|
<literal>confext</literal> targets, this is the file path to the image. For <literal>component</literal>
|
|
and <literal>host</literal> targets, this is the name of a
|
|
<citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
|
directory.</para>
|
|
|
|
<para>The <varname>Name</varname> 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 <literal>portable</literal> target named <literal>foobar</literal> and an
|
|
<literal>extension</literal> target named <literal>foobar</literal>, but it is not possible to have
|
|
two <literal>portable</literal> targets named <literal>foobar</literal>.</para>
|
|
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Security</title>
|
|
|
|
<para>Method calls on this service are authenticated via
|
|
<ulink url="https://www.freedesktop.org/software/polkit/docs/latest/">polkit</ulink>.</para>
|
|
|
|
<para><function>List()</function>, <function>Describe()</function>, and <function>CheckNew()</function>
|
|
use the polkit action <interfacename>org.freedesktop.sysupdate1.check</interfacename>.
|
|
By default, this action is permitted without administrator authentication.</para>
|
|
|
|
<para><function>Update()</function> uses the polkit action
|
|
<interfacename>org.freedesktop.sysupdate1.update</interfacename> when no version is specified.
|
|
By default, this action is permitted without administrator authentication. When a version is
|
|
specified, <interfacename>org.freedesktop.sysupdate1.update-to-version</interfacename> is
|
|
used instead. By default, this alternate action requires administrator authentication.</para>
|
|
|
|
<para><function>Vacuum()</function> uses the polkit action
|
|
<interfacename>org.freedesktop.sysupdate1.vacuum</interfacename>. By default, this action requires
|
|
administrator authentication.</para>
|
|
|
|
<para><function>GetAppStream()</function> and <function>GetVersion()</function> are unauthenticated and
|
|
may be called by anybody.</para>
|
|
|
|
<para>All methods called on this interface expose additional variables to the polkit rules.
|
|
<literal>class</literal> contains the class of the Target being acted upon, and <literal>name</literal>
|
|
contains the name of the same Target. Additionally, each method exposes its arguments to the
|
|
rule. Arguments containing flags are unwrapped into a variable-per-flag; for example, the
|
|
<literal>SD_SYSUPDATE_OFFLINE</literal> flag is exposed as a variable named <literal>offline</literal>.
|
|
</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>The Job Object</title>
|
|
|
|
<para>A job is an ongoing operation, started by one of the methods on a Target object.</para>
|
|
|
|
<para>The service exposes the following interfaces on Job objects on the bus:</para>
|
|
|
|
<programlisting executable="systemd-sysupdated" node="/org/freedesktop/sysupdate1/job/_1" interface="org.freedesktop.sysupdate1.Job">
|
|
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 { ... };
|
|
};
|
|
</programlisting>
|
|
|
|
|
|
<!--Autogenerated cross-references for systemd.directives, do not edit-->
|
|
|
|
|
|
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.sysupdate1.Job"/>
|
|
|
|
|
|
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.sysupdate1.Job"/>
|
|
|
|
|
|
<variablelist class="dbus-method" generated="True" extra-ref="Cancel()"/>
|
|
|
|
|
|
<variablelist class="dbus-property" generated="True" extra-ref="Id"/>
|
|
|
|
|
|
<variablelist class="dbus-property" generated="True" extra-ref="Type"/>
|
|
|
|
|
|
<variablelist class="dbus-property" generated="True" extra-ref="Offline"/>
|
|
|
|
|
|
<variablelist class="dbus-property" generated="True" extra-ref="Progress"/>
|
|
|
|
|
|
<!--End of Autogenerated section-->
|
|
|
|
|
|
<refsect2>
|
|
<title>Methods</title>
|
|
|
|
<para>The <function>Cancel()</function> method may be used to cancel the job. It takes no
|
|
parameters.</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Properties</title>
|
|
|
|
<para>The <varname>Id</varname> property exposes the numeric job ID of the job object.</para>
|
|
|
|
<para>The <varname>Type</varname> property exposes the type of operation (one of: <literal>list</literal>,
|
|
<literal>describe</literal>, <literal>check-new</literal>, <literal>update</literal>, or <literal>vacuum</literal>).
|
|
</para>
|
|
|
|
<para>The <varname>Offline</varname> property exposes whether the job is permitted to access
|
|
the network or not.</para>
|
|
|
|
<para>The <varname>Progress</varname> property exposes the current progress of the job as a value
|
|
between 0 and 100. It is only available for <literal>update</literal> jobs; for all other jobs
|
|
it is always 0.</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Security</title>
|
|
|
|
<para><function>Cancel()</function> uses the polkit action that corresponds to the method
|
|
that started this job. For instance, trying to cancel a <literal>list</literal> job will
|
|
require polkit to permit the <interfacename>org.freedesktop.sysupdate1.check</interfacename>
|
|
action.</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
|
|
<example>
|
|
<title>Introspect <interfacename>org.freedesktop.sysupdate1.Manager</interfacename> on the bus</title>
|
|
|
|
<programlisting>$ gdbus introspect --system \
|
|
--dest org.freedesktop.sysupdate1 \
|
|
--object-path /org/freedesktop/sysupdate1
|
|
</programlisting>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Introspect <interfacename>org.freedesktop.sysupdate1.Target</interfacename> on the bus</title>
|
|
|
|
<programlisting>$ gdbus introspect --system \
|
|
--dest org.freedesktop.sysupdate1 \
|
|
--object-path /org/freedesktop/sysupdate1/target/host
|
|
</programlisting>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Introspect <interfacename>org.freedesktop.sysupdate1.Job</interfacename> on the bus</title>
|
|
|
|
<programlisting>$ gdbus introspect --system \
|
|
--dest org.freedesktop.sysupdate1 \
|
|
--object-path /org/freedesktop/sysupdate1/job/_1
|
|
</programlisting>
|
|
</example>
|
|
</refsect1>
|
|
|
|
<xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/>
|
|
<refsect1>
|
|
<title>History</title>
|
|
<refsect2>
|
|
<title>The Manager Object</title>
|
|
<para><function>ListTargets()</function>,
|
|
<function>ListJobs()</function>,
|
|
<function>ListAppStream()</function>, and
|
|
<function>JobRemoved()</function> were added in version 257.</para>
|
|
</refsect2>
|
|
<refsect2>
|
|
<title>The Target Object</title>
|
|
<para><function>List()</function>,
|
|
<function>Describe()</function>,
|
|
<function>CheckNew()</function>,
|
|
<function>Update()</function>,
|
|
<function>Vacuum()</function>,
|
|
<function>GetAppStream()</function>,
|
|
<function>GetVersion()</function>,
|
|
<varname>Class</varname>,
|
|
<varname>Name</varname>, and
|
|
<varname>Path</varname> were added in version 257.</para>
|
|
</refsect2>
|
|
<refsect2>
|
|
<title>The Job Object</title>
|
|
<para><function>Cancel()</function>,
|
|
<varname>Id</varname>,
|
|
<varname>Type</varname>,
|
|
<varname>Offline</varname>, and
|
|
<varname>Progress</varname> were added in version 257.</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
</refentry>
|