| <?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.</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>. |
| The <varname>flag</varname> parameter is currently unused and reserved for future purposes.</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>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 cause |
| safety checks that ensure the units are not running while the new image is attached or detached |
| to be skipped. <varname>SD_SYSTEMD_PORTABLE_FORCE_SYSEXT</varname> will cause the check that the |
| <filename>extension-release.<replaceable>NAME</replaceable></filename> file in the extension image |
| matches the image name to be skipped. 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_SYSEXT (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); |
| ReattacheWithExtensions(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 ReattacheWithExtensions 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="ReattacheWithExtensions()"/> |
| |
| <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>ReattacheWithExtensions()</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"/> |
| </refentry> |
