man/org.freedesktop.portable1.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" >
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="org.freedesktop.portable1" conditional='ENABLE_PORTABLED'
   7     xmlns:xi="http://www.w3.org/2001/XInclude">
   8   <refentryinfo>
   9     <title>org.freedesktop.portable1</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>org.freedesktop.portable1</refentrytitle>
  15     <manvolnum>5</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>org.freedesktop.portable1</refname>
  20     <refpurpose>The D-Bus interface of systemd-portabled</refpurpose>
  21   </refnamediv>
  22
  23   <refsect1>
  24     <title>Introduction</title>
  25
  26     <para>
  27     <citerefentry><refentrytitle>systemd-portabled.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  28     is a system service that may be used to attach, detach and inspect portable services. This page describes the
  29     D-Bus interface.</para>
  30   </refsect1>
  31
  32   <refsect1>
  33     <title>The Manager Object</title>
  34
  35     <para>The service exposes the following interfaces on the Manager object on the bus:</para>
  36
  37     <programlisting executable="systemd-portabled" node="/org/freedesktop/portable1" interface="org.freedesktop.portable1.Manager">
  38 node /org/freedesktop/portable1 {
  39   interface org.freedesktop.portable1.Manager {
  40     methods:
  41       GetImage(in  s image,
  42                out o object);
  43       ListImages(out a(ssbtttso) images);
  44       GetImageOSRelease(in  s image,
  45                         out a{ss} os_release);
  46       GetImageMetadata(in  s image,
  47                        in  as matches,
  48                        out s image,
  49                        out ay os_release,
  50                        out a{say} units);
  51       GetImageMetadataWithExtensions(in  s image,
  52                                      in  as extensions,
  53                                      in  as matches,
  54                                      in  t flags,
  55                                      out s image,
  56                                      out ay os_release,
  57                                      out a{say} extensions,
  58                                      out a{say} units);
  59       GetImageState(in  s image,
  60                     out s state);
  61       AttachImage(in  s image,
  62                   in  as matches,
  63                   in  s profile,
  64                   in  b runtime,
  65                   in  s copy_mode,
  66                   out a(sss) changes);
  67       AttachImageWithExtensions(in  s image,
  68                                 in  as extensions,
  69                                 in  as matches,
  70                                 in  s profile,
  71                                 in  s copy_mode,
  72                                 in  t flags,
  73                                 out a(sss) changes);
  74       DetachImage(in  s image,
  75                   in  b runtime,
  76                   out a(sss) changes);
  77       DetachImageWithExtensions(in  s image,
  78                                 in  as extensions,
  79                                 in  t flags,
  80                                 out a(sss) changes);
  81       ReattachImage(in  s image,
  82                     in  as matches,
  83                     in  s profile,
  84                     in  b runtime,
  85                     in  s copy_mode,
  86                     out a(sss) changes_removed,
  87                     out a(sss) changes_updated);
  88       ReattachImageWithExtensions(in  s image,
  89                                   in  as extensions,
  90                                   in  as matches,
  91                                   in  s profile,
  92                                   in  s copy_mode,
  93                                   in  t flags,
  94                                   out a(sss) changes_removed,
  95                                   out a(sss) changes_updated);
  96       RemoveImage(in  s image);
  97       MarkImageReadOnly(in  s image,
  98                         in  b read_only);
  99       SetImageLimit(in  s image,
 100                     in  t limit);
 101       SetPoolLimit(in  t limit);
 102     properties:
 103       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 104       readonly s PoolPath = '...';
 105       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 106       readonly t PoolUsage = ...;
 107       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 108       readonly t PoolLimit = ...;
 109       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 110       readonly as Profiles = ['...', ...];
 111   };
 112   interface org.freedesktop.DBus.Peer { ... };
 113   interface org.freedesktop.DBus.Introspectable { ... };
 114   interface org.freedesktop.DBus.Properties { ... };
 115 };
 116     </programlisting>
 117
 118     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 119
 120     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.portable1.Manager"/>
 121
 122     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.portable1.Manager"/>
 123
 124     <variablelist class="dbus-method" generated="True" extra-ref="GetImage()"/>
 125
 126     <variablelist class="dbus-method" generated="True" extra-ref="ListImages()"/>
 127
 128     <variablelist class="dbus-method" generated="True" extra-ref="GetImageOSRelease()"/>
 129
 130     <variablelist class="dbus-method" generated="True" extra-ref="GetImageMetadata()"/>
 131
 132     <variablelist class="dbus-method" generated="True" extra-ref="GetImageMetadataWithExtensions()"/>
 133
 134     <variablelist class="dbus-method" generated="True" extra-ref="GetImageState()"/>
 135
 136     <variablelist class="dbus-method" generated="True" extra-ref="AttachImage()"/>
 137
 138     <variablelist class="dbus-method" generated="True" extra-ref="AttachImageWithExtensions()"/>
 139
 140     <variablelist class="dbus-method" generated="True" extra-ref="DetachImage()"/>
 141
 142     <variablelist class="dbus-method" generated="True" extra-ref="DetachImageWithExtensions()"/>
 143
 144     <variablelist class="dbus-method" generated="True" extra-ref="ReattachImage()"/>
 145
 146     <variablelist class="dbus-method" generated="True" extra-ref="ReattachImageWithExtensions()"/>
 147
 148     <variablelist class="dbus-method" generated="True" extra-ref="RemoveImage()"/>
 149
 150     <variablelist class="dbus-method" generated="True" extra-ref="MarkImageReadOnly()"/>
 151
 152     <variablelist class="dbus-method" generated="True" extra-ref="SetImageLimit()"/>
 153
 154     <variablelist class="dbus-method" generated="True" extra-ref="SetPoolLimit()"/>
 155
 156     <variablelist class="dbus-property" generated="True" extra-ref="PoolPath"/>
 157
 158     <variablelist class="dbus-property" generated="True" extra-ref="PoolUsage"/>
 159
 160     <variablelist class="dbus-property" generated="True" extra-ref="PoolLimit"/>
 161
 162     <variablelist class="dbus-property" generated="True" extra-ref="Profiles"/>
 163
 164     <!--End of Autogenerated section-->
 165
 166     <refsect2>
 167       <title>Methods</title>
 168
 169       <para><function>GetImage()</function> may be used to get the image object path of the image with the
 170       specified name.</para>
 171
 172       <para><function>ListImages()</function> returns an array of all currently known images. The
 173       structures in the array consist of the following fields: image name, type, read-only flag, creation
 174       time, modification time, current disk space, usage and image object path.</para>
 175
 176       <para><function>GetImageOSRelease()</function> retrieves the OS release information of an image.
 177       This method returns an array of key value pairs read from the
 178       <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file in
 179       the image and is useful to identify the operating system used in a portable service.</para>
 180
 181       <para><function>GetImageMetadata()</function> retrieves metadata associated with an image.
 182       This method returns the image name, the image's <citerefentry><refentrytitle>os-release</refentrytitle>
 183       <manvolnum>5</manvolnum></citerefentry> content in the form of a (streamable) array of bytes,
 184       and a list of portable units contained in the image, in the form of a string (unit name) and
 185       an array of bytes with the content.</para>
 186
 187       <para><function>GetImageMetadataWithExtensions()</function> retrieves metadata associated with an
 188       image. This method is a superset of <function>GetImageMetadata()</function> with the addition of a list
 189       of extensions as input parameter, which were overlaid on top of the main image via
 190       <function>AttachImageWithExtensions()</function>. The path of each extension and an array of bytes with
 191       the content of the respective extension-release file are returned, one such structure for each
 192       extension named in the input arguments.</para>
 193
 194       <para><function>GetImageState()</function> retrieves the image state as one of the following
 195       strings:
 196       <itemizedlist>
 197         <listitem><para>detached</para></listitem>
 198
 199         <listitem><para>attached</para></listitem>
 200
 201         <listitem><para>attached-runtime</para></listitem>
 202
 203         <listitem><para>enabled</para></listitem>
 204
 205         <listitem><para>enabled-runtime</para></listitem>
 206
 207         <listitem><para>running</para></listitem>
 208
 209         <listitem><para>running-runtime</para></listitem>
 210       </itemizedlist></para>
 211
 212       <para><function>AttachImage()</function> attaches a portable image to the system.
 213       This method takes an image path or name, a list of strings that will be used to search for
 214       unit files inside the image (partial or complete matches), a string indicating which
 215       portable profile to use for the image (see <varname>Profiles</varname> property for
 216       a list of available profiles), a boolean indicating whether to attach the image only
 217       for the current boot session, and a string representing the preferred copy mode
 218       (whether to copy the image or to just symlink it) with the following possible values:
 219       <itemizedlist>
 220         <listitem><para>(null)</para></listitem>
 221
 222         <listitem><para>copy</para></listitem>
 223
 224         <listitem><para>symlink</para></listitem>
 225       </itemizedlist>
 226       This method returns the list of changes applied to the system (for example, which unit was
 227       added and is now available as a system service). Each change is represented as a triplet of
 228       strings: the type of change applied, the path on which it was applied, and the source
 229       (if any). The type of change applied will be one of the following possible values:
 230       <itemizedlist>
 231         <listitem><para>copy</para></listitem>
 232
 233         <listitem><para>symlink</para></listitem>
 234
 235         <listitem><para>write</para></listitem>
 236
 237         <listitem><para>mkdir</para></listitem>
 238       </itemizedlist>
 239       Note that an image cannot be attached if a unit that it contains is already present
 240       on the system.</para>
 241
 242       <para><function>AttachImageWithExtensions()</function> attaches a portable image to the system.
 243       This method is a superset of <function>AttachImage()</function> with the addition of
 244       a list of extensions as input parameter, which will be overlaid on top of the main
 245       image. When this method is used, detaching must be done by passing the same arguments via the
 246       <function>DetachImageWithExtensions()</function> method. For more details on this functionality,
 247       see the <varname>MountImages=</varname> entry on
 248       <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 249       and <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 250       The <varname>flag</varname> parameter is currently unused and reserved for future purposes.</para>
 251
 252       <para><function>DetachImage()</function> detaches a portable image from the system.
 253       This method takes an image path or name, and a boolean indicating whether the image to
 254       detach was attached only for the current boot session or persistently. This method
 255       returns the list of changes applied to the system (for example, which unit was removed
 256       and is no longer available as a system service). Each change is represented as a triplet of
 257       strings: the type of change applied, the path on which it was applied, and the source
 258       (if any). The type of change applied will be one of the following possible values:
 259       <itemizedlist>
 260         <listitem><para>unlink</para></listitem>
 261       </itemizedlist>
 262       Note that an image cannot be detached if a unit that it contains is running.</para>
 263
 264       <para><function>DetachImageWithExtensions()</function> detaches a portable image from the system.
 265       This method is a superset of <function>DetachImage()</function> with the addition of
 266       a list of extensions as input parameter, which were overlaid on top of the main
 267       image via <function>AttachImageWithExtensions()</function>.
 268       The <varname>flag</varname> parameter is currently unused and reserved for future purposes.</para>
 269
 270       <para><function>ReattachImage()</function> combines the effects of the
 271       <function>AttachImage()</function> method and the <function>DetachImage()</function> method.
 272       The difference is that it is allowed to reattach an image while one or more of its units
 273       are running. The reattach operation will fail if no matching image is attached.
 274       The input parameters match the <function>AttachImage()</function> method, and the return
 275       parameters are the combination of the return parameters of the
 276       <function>DetachImage()</function> method (first array, units that were removed) and the
 277       <function>AttachImage()</function> method (second array, units that were updated or added).</para>
 278
 279       <para><function>ReattachImageWithExtensions()</function> reattaches a portable image to the system.
 280       This method is a superset of <function>ReattachImage()</function> with the addition of
 281       a list of extensions as input parameter, which will be overlaid on top of the main
 282       image. For more details on this functionality, see the <varname>MountImages=</varname> entry on
 283       <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 284       and <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 285       The <varname>flag</varname> parameter is currently unused and reserved for future purposes</para>
 286
 287       <para><function>RemoveImage()</function> removes the image with the specified name.</para>
 288
 289       <para><function>MarkImageReadOnly()</function> toggles the read-only flag of an image.</para>
 290
 291       <para><function>SetPoolLimit()</function> sets an overall quota limit on the pool of images.</para>
 292
 293       <para><function>SetImageLimit()</function> sets a per-image quota limit.</para>
 294
 295       <para>The <function>AttachImageWithExtensions()</function>,
 296       <function>DetachImageWithExtensions()</function> and
 297       <function>ReattachImageWithExtensions()</function> methods take in options as flags instead of
 298       booleans to allow for extendability, defined as follows:</para>
 299
 300       <programlisting>
 301 #define SD_SYSTEMD_PORTABLE_RUNTIME  (UINT64_C(1) &lt;&lt; 0)
 302       </programlisting>
 303     </refsect2>
 304
 305     <refsect2>
 306       <title>Properties</title>
 307
 308       <para><varname>PoolPath</varname> specifies the file system path where images are written to.</para>
 309
 310       <para><varname>PoolUsage</varname> specifies the current usage size of the image pool in bytes.</para>
 311
 312       <para><varname>PoolLimit</varname> specifies the size limit of the image pool in bytes.</para>
 313
 314       <para><varname>Profiles</varname> specifies the available runtime profiles for portable services.</para>
 315     </refsect2>
 316   </refsect1>
 317
 318   <refsect1>
 319     <title>The Image Object</title>
 320
 321     <para>The service exposes the following interfaces on the Image object on the bus:</para>
 322
 323     <programlisting executable="systemd-portabled" node="/org/freedesktop/portable1" interface="org.freedesktop.portable1.Image">
 324 node /org/freedesktop/portable1 {
 325   interface org.freedesktop.portable1.Image {
 326     methods:
 327       GetOSRelease(out a{ss} os_release);
 328       GetMetadata(in  as matches,
 329                   out s image,
 330                   out ay os_release,
 331                   out a{say} units);
 332       GetMetadataWithExtensions(in  as extensions,
 333                                 in  as matches,
 334                                 in  t flags,
 335                                 out s image,
 336                                 out ay os_release,
 337                                 out a{say} extensions,
 338                                 out a{say} units);
 339       GetState(out s state);
 340       Attach(in  as matches,
 341              in  s profile,
 342              in  b runtime,
 343              in  s copy_mode,
 344              out a(sss) changes);
 345       AttachWithExtensions(in  as extensions,
 346                            in  as matches,
 347                            in  s profile,
 348                            in  s copy_mode,
 349                            in  t flags,
 350                            out a(sss) changes);
 351       Detach(in  b runtime,
 352              out a(sss) changes);
 353       DetachWithExtensions(in  as extensions,
 354                            in  t flags,
 355                            out a(sss) changes);
 356       Reattach(in  as matches,
 357                in  s profile,
 358                in  b runtime,
 359                in  s copy_mode,
 360                out a(sss) changes_removed,
 361                out a(sss) changes_updated);
 362       ReattacheWithExtensions(in  as extensions,
 363                               in  as matches,
 364                               in  s profile,
 365                               in  s copy_mode,
 366                               in  t flags,
 367                               out a(sss) changes_removed,
 368                               out a(sss) changes_updated);
 369       Remove();
 370       MarkReadOnly(in  b read_only);
 371       SetLimit(in  t limit);
 372     properties:
 373       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 374       readonly s Name = '...';
 375       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 376       readonly s Path = '...';
 377       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 378       readonly s Type = '...';
 379       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 380       readonly b ReadOnly = ...;
 381       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 382       readonly t CreationTimestamp = ...;
 383       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 384       readonly t ModificationTimestamp = ...;
 385       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 386       readonly t Usage = ...;
 387       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 388       readonly t Limit = ...;
 389       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 390       readonly t UsageExclusive = ...;
 391       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 392       readonly t LimitExclusive = ...;
 393   };
 394   interface org.freedesktop.DBus.Peer { ... };
 395   interface org.freedesktop.DBus.Introspectable { ... };
 396   interface org.freedesktop.DBus.Properties { ... };
 397 };
 398     </programlisting>
 399
 400     <!--method GetOSRelease is not documented!-->
 401
 402     <!--method GetMetadata is not documented!-->
 403
 404     <!--method GetMetadataWithExtensions is not documented!-->
 405
 406     <!--method GetState is not documented!-->
 407
 408     <!--method Attach is not documented!-->
 409
 410     <!--method AttachWithExtensions is not documented!-->
 411
 412     <!--method Detach is not documented!-->
 413
 414     <!--method DetachWithExtensions is not documented!-->
 415
 416     <!--method Reattach is not documented!-->
 417
 418     <!--method ReattacheWithExtensions is not documented!-->
 419
 420     <!--method Remove is not documented!-->
 421
 422     <!--method MarkReadOnly is not documented!-->
 423
 424     <!--method SetLimit is not documented!-->
 425
 426     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 427
 428     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.portable1.Image"/>
 429
 430     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.portable1.Image"/>
 431
 432     <variablelist class="dbus-method" generated="True" extra-ref="GetOSRelease()"/>
 433
 434     <variablelist class="dbus-method" generated="True" extra-ref="GetMetadata()"/>
 435
 436     <variablelist class="dbus-method" generated="True" extra-ref="GetMetadataWithExtensions()"/>
 437
 438     <variablelist class="dbus-method" generated="True" extra-ref="GetState()"/>
 439
 440     <variablelist class="dbus-method" generated="True" extra-ref="Attach()"/>
 441
 442     <variablelist class="dbus-method" generated="True" extra-ref="AttachWithExtensions()"/>
 443
 444     <variablelist class="dbus-method" generated="True" extra-ref="Detach()"/>
 445
 446     <variablelist class="dbus-method" generated="True" extra-ref="DetachWithExtensions()"/>
 447
 448     <variablelist class="dbus-method" generated="True" extra-ref="Reattach()"/>
 449
 450     <variablelist class="dbus-method" generated="True" extra-ref="ReattacheWithExtensions()"/>
 451
 452     <variablelist class="dbus-method" generated="True" extra-ref="Remove()"/>
 453
 454     <variablelist class="dbus-method" generated="True" extra-ref="MarkReadOnly()"/>
 455
 456     <variablelist class="dbus-method" generated="True" extra-ref="SetLimit()"/>
 457
 458     <variablelist class="dbus-property" generated="True" extra-ref="Name"/>
 459
 460     <variablelist class="dbus-property" generated="True" extra-ref="Path"/>
 461
 462     <variablelist class="dbus-property" generated="True" extra-ref="Type"/>
 463
 464     <variablelist class="dbus-property" generated="True" extra-ref="ReadOnly"/>
 465
 466     <variablelist class="dbus-property" generated="True" extra-ref="CreationTimestamp"/>
 467
 468     <variablelist class="dbus-property" generated="True" extra-ref="ModificationTimestamp"/>
 469
 470     <variablelist class="dbus-property" generated="True" extra-ref="Usage"/>
 471
 472     <variablelist class="dbus-property" generated="True" extra-ref="Limit"/>
 473
 474     <variablelist class="dbus-property" generated="True" extra-ref="UsageExclusive"/>
 475
 476     <variablelist class="dbus-property" generated="True" extra-ref="LimitExclusive"/>
 477
 478     <!--End of Autogenerated section-->
 479
 480     <refsect2>
 481       <title>Methods</title>
 482
 483       <para>The following methods implement the same operation as the respective methods on the
 484       <interfacename>Manager</interfacename> object (see above). However, these methods operate on the image
 485       object and hence does not take an image name parameter. Invoking the methods directly on the Manager
 486       object has the advantage of not requiring a <function>GetImage()</function> call to get the image object
 487       for a specific image name. Calling the methods on the Manager object is hence a round trip
 488       optimization. List of methods:
 489       <itemizedlist>
 490         <listitem><para>GetOSRelease()</para></listitem>
 491
 492         <listitem><para>GetMetadata()</para></listitem>
 493
 494         <listitem><para>GetMetadataWithExtensions()</para></listitem>
 495
 496         <listitem><para>GetState()</para></listitem>
 497
 498         <listitem><para>Attach()</para></listitem>
 499
 500         <listitem><para>AttachWithExtensions()</para></listitem>
 501
 502         <listitem><para>Detach()</para></listitem>
 503
 504         <listitem><para>DetachWithExtensions()</para></listitem>
 505
 506         <listitem><para>Reattach()</para></listitem>
 507
 508         <listitem><para>ReattacheWithExtensions()</para></listitem>
 509
 510         <listitem><para>Remove()</para></listitem>
 511
 512         <listitem><para>MarkReadOnly()</para></listitem>
 513
 514         <listitem><para>SetLimit()</para></listitem>
 515       </itemizedlist></para>
 516     </refsect2>
 517
 518     <refsect2>
 519       <title>Properties</title>
 520
 521       <para><varname>Name</varname> specifies the image name.</para>
 522
 523       <para><varname>Path</varname> specifies the file system path where image is stored.</para>
 524
 525       <para><varname>Type</varname> specifies the image type.</para>
 526
 527       <para><varname>ReadOnly</varname> specifies whether the image is read-only.</para>
 528
 529       <para><varname>CreationTimestamp</varname> specifies the image creation timestamp.</para>
 530
 531       <para><varname>ModificationTimestamp</varname> specifies the image modification timestamp.</para>
 532
 533       <para><varname>Usage</varname> specifies the image disk usage.</para>
 534
 535       <para><varname>Limit</varname> specifies the image disk usage limit.</para>
 536
 537       <para><varname>UsageExclusive</varname> specifies the image disk usage (exclusive).</para>
 538
 539       <para><varname>LimitExclusive</varname> specifies the image disk usage limit (exclusive).</para>
 540     </refsect2>
 541   </refsect1>
 542
 543   <refsect1>
 544     <title>Versioning</title>
 545
 546     <para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html">
 547     the usual interface versioning guidelines</ulink>.</para>
 548   </refsect1>
 549 </refentry>