portabled: add DBUS documentation

4 files changed, 431 insertions, 1 deletions

diff --git a/man/org.freedesktop.portable1.xml b/man/org.freedesktop.portable1.xml
new file mode 100644
index 0000000000..e6d2f4f536
--- /dev/null
+++ b/man/org.freedesktop.portable1.xml
@@ -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>
diff --git a/man/portablectl.xml b/man/portablectl.xml
index bd0c9e0573..3f37ad1164 100644
--- a/man/portablectl.xml
+++ b/man/portablectl.xml
@@ -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>
diff --git a/man/rules/meson.build b/man/rules/meson.build
index c13c8efc5c..c8e589e0f0 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -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'],
diff --git a/man/systemd-portabled.service.xml b/man/systemd-portabled.service.xml
index ce91b4fcbb..23906f2663 100644
--- a/man/systemd-portabled.service.xml
+++ b/man/systemd-portabled.service.xml
@@ -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>