--- /dev/null
+<?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>
projects / thirdparty / systemd.git / commitdiff
