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