diff options
Diffstat (limited to 'man/org.freedesktop.portable1.xml')
| -rw-r--r-- | man/org.freedesktop.portable1.xml | 585 |
1 files changed, 585 insertions, 0 deletions
diff --git a/man/org.freedesktop.portable1.xml b/man/org.freedesktop.portable1.xml new file mode 100644 index 0000000..6da7b0c --- /dev/null +++ b/man/org.freedesktop.portable1.xml @@ -0,0 +1,585 @@ +<?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) images); + 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); + GetImageMetadataWithExtensions(in s image, + in as extensions, + in as matches, + in t flags, + out s image, + out ay os_release, + out a{say} extensions, + out a{say} units); + GetImageState(in s image, + out s state); + GetImageStateWithExtensions(in s image, + in as extensions, + in t flags, + out s state); + AttachImage(in s image, + in as matches, + in s profile, + in b runtime, + in s copy_mode, + out a(sss) changes); + AttachImageWithExtensions(in s image, + in as extensions, + in as matches, + in s profile, + in s copy_mode, + in t flags, + out a(sss) changes); + DetachImage(in s image, + in b runtime, + out a(sss) changes); + DetachImageWithExtensions(in s image, + in as extensions, + in t flags, + 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); + ReattachImageWithExtensions(in s image, + in as extensions, + in as matches, + in s profile, + in s copy_mode, + in t flags, + 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="GetImageMetadataWithExtensions()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="GetImageState()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="GetImageStateWithExtensions()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="AttachImage()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="AttachImageWithExtensions()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="DetachImage()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="DetachImageWithExtensions()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="ReattachImage()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="ReattachImageWithExtensions()"/> + + <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>GetImageMetadataWithExtensions()</function> retrieves metadata associated with an + image. This method is a superset of <function>GetImageMetadata()</function> with the addition of a list + of extensions as input parameter, which were overlaid on top of the main image via + <function>AttachImageWithExtensions()</function>. The path of each extension and an array of bytes with + the content of the respective extension-release file are returned, one such structure for each + extension named in the input arguments.</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>GetImageStateWithExtensions()</function> is a superset of + <function>GetImageState()</function>, with additional support for a list of extensions + as input parameters, which is necessary to query the state in case the image was attached + in that particular way. The <varname>flag</varname> parameter is currently unused and + reserved for future purposes.</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. Note that this method returns only after all the listed operations are completed, + and due to the I/O involved it might take some time.</para> + + <para><function>AttachImageWithExtensions()</function> attaches a portable image to the system. + This method is a superset of <function>AttachImage()</function> with the addition of + a list of extensions as input parameter, which will be overlaid on top of the main + image. When this method is used, detaching must be done by passing the same arguments via the + <function>DetachImageWithExtensions()</function> method. For more details on this functionality, + see the <varname>MountImages=</varname> entry on + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + </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. Note that this method + returns only after all the listed operations are completed, and due to the I/O involved it might take + some time.</para> + + <para><function>DetachImageWithExtensions()</function> detaches a portable image from the system. + This method is a superset of <function>DetachImage()</function> with the addition of + a list of extensions as input parameter, which were overlaid on top of the main + image via <function>AttachImageWithExtensions()</function>. + The <varname>flag</varname> parameter is currently unused and reserved for future purposes.</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>ReattachImageWithExtensions()</function> reattaches a portable image to the system. + This method is a superset of <function>ReattachImage()</function> with the addition of + a list of extensions as input parameter, which will be overlaid on top of the main + image. For more details on this functionality, see the <varname>MountImages=</varname> entry on + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + The <varname>flag</varname> parameter is currently unused and reserved for future purposes</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> + + <para>The <function>AttachImageWithExtensions()</function>, + <function>DetachImageWithExtensions()</function> and + <function>ReattachImageWithExtensions()</function> methods take in options as flags instead of + booleans to allow for extendability. <varname>SD_SYSTEMD_PORTABLE_FORCE_ATTACH</varname> will bypass + the safety checks that ensure the units are not running while the image is attached or detached. + <varname>SD_SYSTEMD_PORTABLE_FORCE_EXTENSION</varname> will bypass the check that ensures the + <filename>extension-release.<replaceable>NAME</replaceable></filename> file in the extension image + matches the image name. They are defined as follows:</para> + + <programlisting> +#define SD_SYSTEMD_PORTABLE_RUNTIME (UINT64_C(1) << 0) +#define SD_SYSTEMD_PORTABLE_FORCE_ATTACH (UINT64_C(1) << 1) +#define SD_SYSTEMD_PORTABLE_FORCE_EXTENSION (UINT64_C(1) << 2) + </programlisting> + </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} os_release); + GetMetadata(in as matches, + out s image, + out ay os_release, + out a{say} units); + GetMetadataWithExtensions(in as extensions, + in as matches, + in t flags, + out s image, + out ay os_release, + out a{say} extensions, + out a{say} units); + GetState(out s state); + GetStateWithExtensions(in as extensions, + in t flags, + out s state); + Attach(in as matches, + in s profile, + in b runtime, + in s copy_mode, + out a(sss) changes); + AttachWithExtensions(in as extensions, + in as matches, + in s profile, + in s copy_mode, + in t flags, + out a(sss) changes); + Detach(in b runtime, + out a(sss) changes); + DetachWithExtensions(in as extensions, + in t flags, + 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); + ReattachWithExtensions(in as extensions, + in as matches, + in s profile, + in s copy_mode, + in t flags, + 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 GetMetadataWithExtensions is not documented!--> + + <!--method GetState is not documented!--> + + <!--method GetStateWithExtensions is not documented!--> + + <!--method Attach is not documented!--> + + <!--method AttachWithExtensions is not documented!--> + + <!--method Detach is not documented!--> + + <!--method DetachWithExtensions is not documented!--> + + <!--method Reattach is not documented!--> + + <!--method ReattachWithExtensions 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="GetMetadataWithExtensions()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="GetState()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="GetStateWithExtensions()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="Attach()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="AttachWithExtensions()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="Detach()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="DetachWithExtensions()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="Reattach()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="ReattachWithExtensions()"/> + + <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>GetMetadataWithExtensions()</para></listitem> + + <listitem><para>GetState()</para></listitem> + + <listitem><para>Attach()</para></listitem> + + <listitem><para>AttachWithExtensions()</para></listitem> + + <listitem><para>Detach()</para></listitem> + + <listitem><para>DetachWithExtensions()</para></listitem> + + <listitem><para>Reattach()</para></listitem> + + <listitem><para>ReattachWithExtensions()</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> + + <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/> + + <refsect1> + <title>History</title> + <refsect2> + <title>The Manager Object</title> + <para><function>GetImageStateWithExtensions()</function> was added in version 251.</para> + </refsect2> + <refsect2> + <title>The Image Object</title> + <para><function>GetStateWithExtensions()</function> was added in version 251.</para> + <para><function>ReattachWithExtensions()</function> was added in version 254.</para> + </refsect2> + </refsect1> +</refentry> |