mirror of
https://github.com/systemd/systemd.git
synced 2024-12-23 21:35:11 +03:00
57ada07e7a
When enumerating what versions exist for a given target, sysupdate would completely throw out any version that's incomplete (where some of the transfers in the target have that version installed or available, and other transfers do not). If we're trying to find what versions we can offer for download, this is great behavior. If the server side is advertising a partial update to download, we shouldn't present it to the user. On the other hand, if we're enumerating what versions we have currently installed, this is a bad behavior. It makes sysupdate fragile. For example, if a sysext introduces a new .conf file into /usr/lib/sysupdate.d, suddenly the currently-installed OS stops being a version that we've enumerated. Since it's not enumerated, it's not protected, and so sysupdate will wipe the booted OS. So if we're looking for installed versions, we now loosen the restrictions and enumerate incomplete installations. Partial fix for https://github.com/systemd/systemd/issues/33339
497 lines
22 KiB
XML
497 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. Additional
|
|
options may be passed through the <varname>flags</varname> argument. Valid flags are defined as follows:
|
|
</para>
|
|
|
|
<programlisting>
|
|
#define SD_SYSUPDATE_OFFLINE (UINT64_C(1) << 0)
|
|
</programlisting>
|
|
|
|
<para>When <constant>SD_SYSUPDATE_OFFLINE</constant> 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 <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. This method supports the same flags
|
|
as <function>List()</function>. 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><literal>version</literal></term>
|
|
<listitem><para>A string containing the version number.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>newest</literal></term>
|
|
<listitem><para>A boolean indicating whether this version is the latest available for the target.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>available</literal></term>
|
|
<listitem><para>A boolean indicating whether this version is available for download.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>installed</literal></term>
|
|
<listitem><para>A boolean indicating whether this version is installed locally.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>obsolete</literal></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><literal>protected</literal></term>
|
|
<listitem><para>A boolean indicating whether this version is exempt from deletion by a
|
|
<function>Vacuum()</function> operation.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>incomplete</literal></term>
|
|
<listitem><para>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.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>changelog_urls</literal></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. Flags are mapped as follows:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para><constant>SD_SYSUPDATE_OFFLINE</constant> → <literal>update</literal></para></listitem>
|
|
</itemizedlist>
|
|
|
|
</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>
|