mirror of
https://github.com/systemd/systemd.git
synced 2025-02-22 09:57:34 +03:00
portabled: add DBUS documentation
This commit is contained in:
Luca Boccassi
parent
598f938e3b
commit
23e5c8d296
427
man/org.freedesktop.portable1.xml
Normal file
427
man/org.freedesktop.portable1.xml
Normal file
@ -0,0 +1,427 @@
|
||||
<?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.portable1" conditional='ENABLE_PORTABLED'
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude">
|
||||
<refentryinfo>
|
||||
<title>org.freedesktop.portable1</title>
|
||||
<productname>systemd</productname>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>org.freedesktop.portable1</refentrytitle>
|
||||
<manvolnum>5</manvolnum>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>org.freedesktop.portable1</refname>
|
||||
<refpurpose>The D-Bus interface of systemd-portabled</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsect1>
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>
|
||||
<citerefentry><refentrytitle>systemd-portabled.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
||||
is a system service that may be used to attach, detach and inspect portable services. 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-portabled" node="/org/freedesktop/portable1" interface="org.freedesktop.portable1.Manager">
|
||||
node /org/freedesktop/portable1 {
|
||||
interface org.freedesktop.portable1.Manager {
|
||||
methods:
|
||||
GetImage(in s image,
|
||||
out o object);
|
||||
ListImages(out a(ssbtttso) UNNAMED);
|
||||
GetImageOSRelease(in s image,
|
||||
out a{ss} os_release);
|
||||
GetImageMetadata(in s image,
|
||||
in as matches,
|
||||
out s image,
|
||||
out ay os_release,
|
||||
out a{say} units);
|
||||
GetImageState(in s image,
|
||||
out s state);
|
||||
AttachImage(in s image,
|
||||
in as matches,
|
||||
in s profile,
|
||||
in b runtime,
|
||||
in s copy_mode,
|
||||
out a(sss) changes);
|
||||
DetachImage(in s image,
|
||||
in b runtime,
|
||||
out a(sss) changes);
|
||||
ReattachImage(in s image,
|
||||
in as matches,
|
||||
in s profile,
|
||||
in b runtime,
|
||||
in s copy_mode,
|
||||
out a(sss) changes_removed,
|
||||
out a(sss) changes_updated);
|
||||
RemoveImage(in s image);
|
||||
MarkImageReadOnly(in s image,
|
||||
in b read_only);
|
||||
SetImageLimit(in s image,
|
||||
in t limit);
|
||||
SetPoolLimit(in t limit);
|
||||
properties:
|
||||
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
||||
readonly s PoolPath = '...';
|
||||
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
||||
readonly t PoolUsage = ...;
|
||||
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
||||
readonly t PoolLimit = ...;
|
||||
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
||||
readonly as Profiles = ['...', ...];
|
||||
};
|
||||
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.portable1.Manager"/>
|
||||
|
||||
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.portable1.Manager"/>
|
||||
|
||||
<variablelist class="dbus-method" generated="True" extra-ref="GetImage()"/>
|
||||
|
||||
<variablelist class="dbus-method" generated="True" extra-ref="ListImages()"/>
|
||||
|
||||
<variablelist class="dbus-method" generated="True" extra-ref="GetImageOSRelease()"/>
|
||||
|
||||
<variablelist class="dbus-method" generated="True" extra-ref="GetImageMetadata()"/>
|
||||
|
||||
<variablelist class="dbus-method" generated="True" extra-ref="GetImageState()"/>
|
||||
|
||||
<variablelist class="dbus-method" generated="True" extra-ref="AttachImage()"/>
|
||||
|
||||
<variablelist class="dbus-method" generated="True" extra-ref="DetachImage()"/>
|
||||
|
||||
<variablelist class="dbus-method" generated="True" extra-ref="ReattachImage()"/>
|
||||
|
||||
<variablelist class="dbus-method" generated="True" extra-ref="RemoveImage()"/>
|
||||
|
||||
<variablelist class="dbus-method" generated="True" extra-ref="MarkImageReadOnly()"/>
|
||||
|
||||
<variablelist class="dbus-method" generated="True" extra-ref="SetImageLimit()"/>
|
||||
|
||||
<variablelist class="dbus-method" generated="True" extra-ref="SetPoolLimit()"/>
|
||||
|
||||
<variablelist class="dbus-property" generated="True" extra-ref="PoolPath"/>
|
||||
|
||||
<variablelist class="dbus-property" generated="True" extra-ref="PoolUsage"/>
|
||||
|
||||
<variablelist class="dbus-property" generated="True" extra-ref="PoolLimit"/>
|
||||
|
||||
<variablelist class="dbus-property" generated="True" extra-ref="Profiles"/>
|
||||
|
||||
<!--End of Autogenerated section-->
|
||||
|
||||
<refsect2>
|
||||
<title>Methods</title>
|
||||
|
||||
<para><function>GetImage()</function> may be used to get the image object path of the image with the
|
||||
specified name.</para>
|
||||
|
||||
<para><function>ListImages()</function> returns an array of all currently known images. The
|
||||
structures in the array consist of the following fields: image name, type, read-only flag, creation
|
||||
time, modification time, current disk space, usage and image object path.</para>
|
||||
|
||||
<para><function>GetImageOSRelease()</function> retrieves the OS release information of an image.
|
||||
This method returns an array of key value pairs read from the
|
||||
<citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file in
|
||||
the image and is useful to identify the operating system used in a portable service.</para>
|
||||
|
||||
<para><function>GetImageMetadata()</function> retrieves metadata associated with an image.
|
||||
This method returns the image name, the image's <citerefentry><refentrytitle>os-release</refentrytitle>
|
||||
<manvolnum>5</manvolnum></citerefentry> content in the form of a (streamable) array of bytes,
|
||||
and a list of portable units contained in the image, in the form of a string (unit name) and
|
||||
an array of bytes with the content.</para>
|
||||
|
||||
<para><function>GetImageState()</function> retrieves the image state as one of the following
|
||||
strings:
|
||||
<itemizedlist>
|
||||
<listitem><para>detached</para></listitem>
|
||||
|
||||
<listitem><para>attached</para></listitem>
|
||||
|
||||
<listitem><para>attached-runtime</para></listitem>
|
||||
|
||||
<listitem><para>enabled</para></listitem>
|
||||
|
||||
<listitem><para>enabled-runtime</para></listitem>
|
||||
|
||||
<listitem><para>running</para></listitem>
|
||||
|
||||
<listitem><para>running-runtime</para></listitem>
|
||||
</itemizedlist></para>
|
||||
|
||||
<para><function>AttachImage()</function> attaches a portable image to the system.
|
||||
This method takes an image path or name, a list of strings that will be used to search for
|
||||
unit files inside the image (partial or complete matches), a string indicating which
|
||||
portable profile to use for the image (see <varname>Profiles</varname> property for
|
||||
a list of available profiles), a boolean indicating whether to attach the image only
|
||||
for the current boot session, and a string representing the preferred copy mode
|
||||
(whether to copy the image or to just symlink it) with the following possible values:
|
||||
<itemizedlist>
|
||||
<listitem><para>(null)</para></listitem>
|
||||
|
||||
<listitem><para>copy</para></listitem>
|
||||
|
||||
<listitem><para>symlink</para></listitem>
|
||||
</itemizedlist>
|
||||
This method returns the list of changes applied to the system (for example, which unit was
|
||||
added and is now available as a system service). Each change is represented as a triplet of
|
||||
strings: the type of change applied, the path on which it was applied, and the source
|
||||
(if any). The type of change applied will be one of the following possible values:
|
||||
<itemizedlist>
|
||||
<listitem><para>copy</para></listitem>
|
||||
|
||||
<listitem><para>symlink</para></listitem>
|
||||
|
||||
<listitem><para>write</para></listitem>
|
||||
|
||||
<listitem><para>mkdir</para></listitem>
|
||||
</itemizedlist>
|
||||
Note that an image cannot be attached if a unit that it contains is already present
|
||||
on the system.</para>
|
||||
|
||||
<para><function>DetachImage()</function> detaches a portable image from the system.
|
||||
This method takes an image path or name, and a boolean indicating whether the image to
|
||||
detach was attached only for the current boot session or persistently. This method
|
||||
returns the list of changes applied to the system (for example, which unit was removed
|
||||
and is no longer available as a system service). Each change is represented as a triplet of
|
||||
strings: the type of change applied, the path on which it was applied, and the source
|
||||
(if any). The type of change applied will be one of the following possible values:
|
||||
<itemizedlist>
|
||||
<listitem><para>unlink</para></listitem>
|
||||
</itemizedlist>
|
||||
Note that an image cannot be detached if a unit that it contains is running.</para>
|
||||
|
||||
<para><function>ReattachImage()</function> combines the effects of the
|
||||
<function>AttachImage()</function> method and the <function>DetachImage()</function> method.
|
||||
The difference is that it is allowed to reattach an image while one or more of its units
|
||||
are running. The reattach operation will fail if no matching image is attached.
|
||||
The input parameters match the <function>AttachImage()</function> method, and the return
|
||||
parameters are the combination of the return parameters of the
|
||||
<function>DetachImage()</function> method (first array, units that were removed) and the
|
||||
<function>AttachImage()</function> method (second array, units that were updated or added).</para>
|
||||
|
||||
<para><function>RemoveImage()</function> removes the image with the specified name.</para>
|
||||
|
||||
<para><function>MarkImageReadOnly()</function> toggles the read-only flag of an image.</para>
|
||||
|
||||
<para><function>SetPoolLimit()</function> sets an overall quota limit on the pool of images.</para>
|
||||
|
||||
<para><function>SetImageLimit()</function> sets a per-image quota limit.</para>
|
||||
</refsect2>
|
||||
|
||||
<refsect2>
|
||||
<title>Properties</title>
|
||||
|
||||
<para><varname>PoolPath</varname> specifies the file system path where images are written to.</para>
|
||||
|
||||
<para><varname>PoolUsage</varname> specifies the current usage size of the image pool in bytes.</para>
|
||||
|
||||
<para><varname>PoolLimit</varname> specifies the size limit of the image pool in bytes.</para>
|
||||
|
||||
<para><varname>Profiles</varname> specifies the available runtime profiles for portable services.</para>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>The Image Object</title>
|
||||
|
||||
<para>The service exposes the following interfaces on the Image object on the bus:</para>
|
||||
|
||||
<programlisting executable="systemd-portabled" node="/org/freedesktop/portable1" interface="org.freedesktop.portable1.Image">
|
||||
node /org/freedesktop/portable1 {
|
||||
interface org.freedesktop.portable1.Image {
|
||||
methods:
|
||||
GetOSRelease(out a{ss} UNNAMED);
|
||||
GetMetadata(in as matches,
|
||||
out s image,
|
||||
out ay os_release,
|
||||
out a{say} units);
|
||||
GetState(out s UNNAMED);
|
||||
Attach(in as matches,
|
||||
in s profile,
|
||||
in b runtime,
|
||||
in s copy_mode,
|
||||
out a(sss) changes);
|
||||
Detach(in b runtime,
|
||||
out a(sss) changes);
|
||||
Reattach(in as matches,
|
||||
in s profile,
|
||||
in b runtime,
|
||||
in s copy_mode,
|
||||
out a(sss) changes_removed,
|
||||
out a(sss) changes_updated);
|
||||
Remove();
|
||||
MarkReadOnly(in b read_only);
|
||||
SetLimit(in t limit);
|
||||
properties:
|
||||
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
||||
readonly s Name = '...';
|
||||
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
||||
readonly s Path = '...';
|
||||
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
||||
readonly s Type = '...';
|
||||
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
||||
readonly b ReadOnly = ...;
|
||||
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
||||
readonly t CreationTimestamp = ...;
|
||||
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
||||
readonly t ModificationTimestamp = ...;
|
||||
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
||||
readonly t Usage = ...;
|
||||
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
||||
readonly t Limit = ...;
|
||||
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
||||
readonly t UsageExclusive = ...;
|
||||
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
||||
readonly t LimitExclusive = ...;
|
||||
};
|
||||
interface org.freedesktop.DBus.Peer { ... };
|
||||
interface org.freedesktop.DBus.Introspectable { ... };
|
||||
interface org.freedesktop.DBus.Properties { ... };
|
||||
};
|
||||
</programlisting>
|
||||
|
||||
<!--method GetOSRelease is not documented!-->
|
||||
|
||||
<!--method GetMetadata is not documented!-->
|
||||
|
||||
<!--method GetState is not documented!-->
|
||||
|
||||
<!--method Attach is not documented!-->
|
||||
|
||||
<!--method Detach is not documented!-->
|
||||
|
||||
<!--method Reattach is not documented!-->
|
||||
|
||||
<!--method Remove is not documented!-->
|
||||
|
||||
<!--method MarkReadOnly is not documented!-->
|
||||
|
||||
<!--method SetLimit is not documented!-->
|
||||
|
||||
<!--Autogenerated cross-references for systemd.directives, do not edit-->
|
||||
|
||||
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.portable1.Image"/>
|
||||
|
||||
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.portable1.Image"/>
|
||||
|
||||
<variablelist class="dbus-method" generated="True" extra-ref="GetOSRelease()"/>
|
||||
|
||||
<variablelist class="dbus-method" generated="True" extra-ref="GetMetadata()"/>
|
||||
|
||||
<variablelist class="dbus-method" generated="True" extra-ref="GetState()"/>
|
||||
|
||||
<variablelist class="dbus-method" generated="True" extra-ref="Attach()"/>
|
||||
|
||||
<variablelist class="dbus-method" generated="True" extra-ref="Detach()"/>
|
||||
|
||||
<variablelist class="dbus-method" generated="True" extra-ref="Reattach()"/>
|
||||
|
||||
<variablelist class="dbus-method" generated="True" extra-ref="Remove()"/>
|
||||
|
||||
<variablelist class="dbus-method" generated="True" extra-ref="MarkReadOnly()"/>
|
||||
|
||||
<variablelist class="dbus-method" generated="True" extra-ref="SetLimit()"/>
|
||||
|
||||
<variablelist class="dbus-property" generated="True" extra-ref="Name"/>
|
||||
|
||||
<variablelist class="dbus-property" generated="True" extra-ref="Path"/>
|
||||
|
||||
<variablelist class="dbus-property" generated="True" extra-ref="Type"/>
|
||||
|
||||
<variablelist class="dbus-property" generated="True" extra-ref="ReadOnly"/>
|
||||
|
||||
<variablelist class="dbus-property" generated="True" extra-ref="CreationTimestamp"/>
|
||||
|
||||
<variablelist class="dbus-property" generated="True" extra-ref="ModificationTimestamp"/>
|
||||
|
||||
<variablelist class="dbus-property" generated="True" extra-ref="Usage"/>
|
||||
|
||||
<variablelist class="dbus-property" generated="True" extra-ref="Limit"/>
|
||||
|
||||
<variablelist class="dbus-property" generated="True" extra-ref="UsageExclusive"/>
|
||||
|
||||
<variablelist class="dbus-property" generated="True" extra-ref="LimitExclusive"/>
|
||||
|
||||
<!--End of Autogenerated section-->
|
||||
|
||||
<refsect2>
|
||||
<title>Methods</title>
|
||||
|
||||
<para>The following methods implement the same operation as the respective methods on the
|
||||
<interfacename>Manager</interfacename> object (see above). However, these methods operate on the image
|
||||
object and hence does not take an image name parameter. Invoking the methods directly on the Manager
|
||||
object has the advantage of not requiring a <function>GetImage()</function> call to get the image object
|
||||
for a specific image name. Calling the methods on the Manager object is hence a round trip
|
||||
optimization. List of methods:
|
||||
<itemizedlist>
|
||||
<listitem><para>GetOSRelease()</para></listitem>
|
||||
|
||||
<listitem><para>GetMetadata()</para></listitem>
|
||||
|
||||
<listitem><para>GetState()</para></listitem>
|
||||
|
||||
<listitem><para>Attach()</para></listitem>
|
||||
|
||||
<listitem><para>Detach()</para></listitem>
|
||||
|
||||
<listitem><para>Reattach()</para></listitem>
|
||||
|
||||
<listitem><para>Remove()</para></listitem>
|
||||
|
||||
<listitem><para>MarkReadOnly()</para></listitem>
|
||||
|
||||
<listitem><para>SetLimit()</para></listitem>
|
||||
</itemizedlist></para>
|
||||
</refsect2>
|
||||
|
||||
<refsect2>
|
||||
<title>Properties</title>
|
||||
|
||||
<para><varname>Name</varname> specifies the image name.</para>
|
||||
|
||||
<para><varname>Path</varname> specifies the file system path where image is stored.</para>
|
||||
|
||||
<para><varname>Type</varname> specifies the image type.</para>
|
||||
|
||||
<para><varname>ReadOnly</varname> specifies whether the image is read-only.</para>
|
||||
|
||||
<para><varname>CreationTimestamp</varname> specifies the image creation timestamp.</para>
|
||||
|
||||
<para><varname>ModificationTimestamp</varname> specifies the image modification timestamp.</para>
|
||||
|
||||
<para><varname>Usage</varname> specifies the image disk usage.</para>
|
||||
|
||||
<para><varname>Limit</varname> specifies the image disk usage limit.</para>
|
||||
|
||||
<para><varname>UsageExclusive</varname> specifies the image disk usage (exclusive).</para>
|
||||
|
||||
<para><varname>LimitExclusive</varname> specifies the image disk usage limit (exclusive).</para>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Versioning</title>
|
||||
|
||||
<para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html">
|
||||
the usual interface versioning guidelines</ulink>.</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
@ -434,6 +434,7 @@
|
||||
<title>See Also</title>
|
||||
<para>
|
||||
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>org.freedesktop.portable1</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>systemd-portabled.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
@ -57,6 +57,7 @@ manpages = [
|
||||
['org.freedesktop.login1', '5', [], 'ENABLE_LOGIND'],
|
||||
['org.freedesktop.machine1', '5', [], 'ENABLE_MACHINED'],
|
||||
['org.freedesktop.oom1', '5', [], 'ENABLE_OOMD'],
|
||||
['org.freedesktop.portable1', '5', [], 'ENABLE_PORTABLED'],
|
||||
['org.freedesktop.resolve1', '5', [], 'ENABLE_RESOLVE'],
|
||||
['org.freedesktop.systemd1', '5', [], ''],
|
||||
['org.freedesktop.timedate1', '5', [], 'ENABLE_TIMEDATED'],
|
||||
|
||||
@ -43,7 +43,8 @@
|
||||
<title>See Also</title>
|
||||
<para>
|
||||
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>portablectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
||||
<citerefentry><refentrytitle>portablectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>org.freedesktop.portable1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user