1ORG.FREEDESKTOP.PORTABLE1(5)org.freedesktop.portableO1RG.FREEDESKTOP.PORTABLE1(5)
2
3
4

NAME

6       org.freedesktop.portable1 - The D-Bus interface of systemd-portabled
7

INTRODUCTION

9       systemd-portabled.service(8) is a system service that may be used to
10       attach, detach and inspect portable services. This page describes the
11       D-Bus interface.
12

THE MANAGER OBJECT

14       The service exposes the following interfaces on the Manager object on
15       the bus:
16
17           node /org/freedesktop/portable1 {
18             interface org.freedesktop.portable1.Manager {
19               methods:
20                 GetImage(in  s image,
21                          out o object);
22                 ListImages(out a(ssbtttso) images);
23                 GetImageOSRelease(in  s image,
24                                   out a{ss} os_release);
25                 GetImageMetadata(in  s image,
26                                  in  as matches,
27                                  out s image,
28                                  out ay os_release,
29                                  out a{say} units);
30                 GetImageMetadataWithExtensions(in  s image,
31                                                in  as extensions,
32                                                in  as matches,
33                                                in  t flags,
34                                                out s image,
35                                                out ay os_release,
36                                                out a{say} extensions,
37                                                out a{say} units);
38                 GetImageState(in  s image,
39                               out s state);
40                 GetImageStateWithExtensions(in  s image,
41                                             in  as extensions,
42                                             in  t flags,
43                                             out s state);
44                 AttachImage(in  s image,
45                             in  as matches,
46                             in  s profile,
47                             in  b runtime,
48                             in  s copy_mode,
49                             out a(sss) changes);
50                 AttachImageWithExtensions(in  s image,
51                                           in  as extensions,
52                                           in  as matches,
53                                           in  s profile,
54                                           in  s copy_mode,
55                                           in  t flags,
56                                           out a(sss) changes);
57                 DetachImage(in  s image,
58                             in  b runtime,
59                             out a(sss) changes);
60                 DetachImageWithExtensions(in  s image,
61                                           in  as extensions,
62                                           in  t flags,
63                                           out a(sss) changes);
64                 ReattachImage(in  s image,
65                               in  as matches,
66                               in  s profile,
67                               in  b runtime,
68                               in  s copy_mode,
69                               out a(sss) changes_removed,
70                               out a(sss) changes_updated);
71                 ReattachImageWithExtensions(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_removed,
78                                             out a(sss) changes_updated);
79                 RemoveImage(in  s image);
80                 MarkImageReadOnly(in  s image,
81                                   in  b read_only);
82                 SetImageLimit(in  s image,
83                               in  t limit);
84                 SetPoolLimit(in  t limit);
85               properties:
86                 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
87                 readonly s PoolPath = '...';
88                 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
89                 readonly t PoolUsage = ...;
90                 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
91                 readonly t PoolLimit = ...;
92                 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
93                 readonly as Profiles = ['...', ...];
94             };
95             interface org.freedesktop.DBus.Peer { ... };
96             interface org.freedesktop.DBus.Introspectable { ... };
97             interface org.freedesktop.DBus.Properties { ... };
98           };
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123   Methods
124       GetImage() may be used to get the image object path of the image with
125       the specified name.
126
127       ListImages() returns an array of all currently known images. The
128       structures in the array consist of the following fields: image name,
129       type, read-only flag, creation time, modification time, current disk
130       space, usage and image object path.
131
132       GetImageOSRelease() retrieves the OS release information of an image.
133       This method returns an array of key value pairs read from the os-
134       release(5) file in the image and is useful to identify the operating
135       system used in a portable service.
136
137       GetImageMetadata() retrieves metadata associated with an image. This
138       method returns the image name, the image's os-release(5) content in the
139       form of a (streamable) array of bytes, and a list of portable units
140       contained in the image, in the form of a string (unit name) and an
141       array of bytes with the content.
142
143       GetImageMetadataWithExtensions() retrieves metadata associated with an
144       image. This method is a superset of GetImageMetadata() with the
145       addition of a list of extensions as input parameter, which were
146       overlaid on top of the main image via AttachImageWithExtensions(). The
147       path of each extension and an array of bytes with the content of the
148       respective extension-release file are returned, one such structure for
149       each extension named in the input arguments.
150
151       GetImageState() retrieves the image state as one of the following
152       strings:
153
154       •   detached
155
156       •   attached
157
158       •   attached-runtime
159
160       •   enabled
161
162       •   enabled-runtime
163
164       •   running
165
166       •   running-runtime
167
168       GetImageStateWithExtensions() is a superset of GetImageState(), with
169       additional support for a list of extensions as input parameters, which
170       is necessary to query the state in case the image was attached in that
171       particular way. The flag parameter is currently unused and reserved for
172       future purposes.
173
174       AttachImage() attaches a portable image to the system. This method
175       takes an image path or name, a list of strings that will be used to
176       search for unit files inside the image (partial or complete matches), a
177       string indicating which portable profile to use for the image (see
178       Profiles property for a list of available profiles), a boolean
179       indicating whether to attach the image only for the current boot
180       session, and a string representing the preferred copy mode (whether to
181       copy the image or to just symlink it) with the following possible
182       values:
183
184       •   (null)
185
186       •   copy
187
188       •   symlink
189
190       This method returns the list of changes applied to the system (for
191       example, which unit was added and is now available as a system
192       service). Each change is represented as a triplet of strings: the type
193       of change applied, the path on which it was applied, and the source (if
194       any). The type of change applied will be one of the following possible
195       values:
196
197       •   copy
198
199       •   symlink
200
201       •   write
202
203       •   mkdir
204
205       Note that an image cannot be attached if a unit that it contains is
206       already present on the system.
207
208       AttachImageWithExtensions() attaches a portable image to the system.
209       This method is a superset of AttachImage() with the addition of a list
210       of extensions as input parameter, which will be overlaid on top of the
211       main image. When this method is used, detaching must be done by passing
212       the same arguments via the DetachImageWithExtensions() method. For more
213       details on this functionality, see the MountImages= entry on
214       systemd.exec(5) and systemd-sysext(8).
215
216       DetachImage() detaches a portable image from the system. This method
217       takes an image path or name, and a boolean indicating whether the image
218       to detach was attached only for the current boot session or
219       persistently. This method returns the list of changes applied to the
220       system (for example, which unit was removed and is no longer available
221       as a system service). Each change is represented as a triplet of
222       strings: the type of change applied, the path on which it was applied,
223       and the source (if any). The type of change applied will be one of the
224       following possible values:
225
226       •   unlink
227
228       Note that an image cannot be detached if a unit that it contains is
229       running.
230
231       DetachImageWithExtensions() detaches a portable image from the system.
232       This method is a superset of DetachImage() with the addition of a list
233       of extensions as input parameter, which were overlaid on top of the
234       main image via AttachImageWithExtensions(). The flag parameter is
235       currently unused and reserved for future purposes.
236
237       ReattachImage() combines the effects of the AttachImage() method and
238       the DetachImage() method. The difference is that it is allowed to
239       reattach an image while one or more of its units are running. The
240       reattach operation will fail if no matching image is attached. The
241       input parameters match the AttachImage() method, and the return
242       parameters are the combination of the return parameters of the
243       DetachImage() method (first array, units that were removed) and the
244       AttachImage() method (second array, units that were updated or added).
245
246       ReattachImageWithExtensions() reattaches a portable image to the
247       system. This method is a superset of ReattachImage() with the addition
248       of a list of extensions as input parameter, which will be overlaid on
249       top of the main image. For more details on this functionality, see the
250       MountImages= entry on systemd.exec(5) and systemd-sysext(8). The flag
251       parameter is currently unused and reserved for future purposes
252
253       RemoveImage() removes the image with the specified name.
254
255       MarkImageReadOnly() toggles the read-only flag of an image.
256
257       SetPoolLimit() sets an overall quota limit on the pool of images.
258
259       SetImageLimit() sets a per-image quota limit.
260
261       The AttachImageWithExtensions(), DetachImageWithExtensions() and
262       ReattachImageWithExtensions() methods take in options as flags instead
263       of booleans to allow for extendability.
264       SD_SYSTEMD_PORTABLE_FORCE_ATTACH will cause safety checks that ensure
265       the units are not running while the new image is attached or detached
266       to be skipped.  SD_SYSTEMD_PORTABLE_FORCE_SYSEXT will cause the check
267       that the extension-release.NAME file in the extension image matches the
268       image name to be skipped. They are defined as follows:
269
270           #define SD_SYSTEMD_PORTABLE_RUNTIME         (UINT64_C(1) << 0)
271           #define SD_SYSTEMD_PORTABLE_FORCE_ATTACH    (UINT64_C(1) << 1)
272           #define SD_SYSTEMD_PORTABLE_FORCE_SYSEXT    (UINT64_C(1) << 2)
273
274
275   Properties
276       PoolPath specifies the file system path where images are written to.
277
278       PoolUsage specifies the current usage size of the image pool in bytes.
279
280       PoolLimit specifies the size limit of the image pool in bytes.
281
282       Profiles specifies the available runtime profiles for portable
283       services.
284

THE IMAGE OBJECT

286       The service exposes the following interfaces on the Image object on the
287       bus:
288
289           node /org/freedesktop/portable1 {
290             interface org.freedesktop.portable1.Image {
291               methods:
292                 GetOSRelease(out a{ss} os_release);
293                 GetMetadata(in  as matches,
294                             out s image,
295                             out ay os_release,
296                             out a{say} units);
297                 GetMetadataWithExtensions(in  as extensions,
298                                           in  as matches,
299                                           in  t flags,
300                                           out s image,
301                                           out ay os_release,
302                                           out a{say} extensions,
303                                           out a{say} units);
304                 GetState(out s state);
305                 GetStateWithExtensions(in  as extensions,
306                                        in  t flags,
307                                        out s state);
308                 Attach(in  as matches,
309                        in  s profile,
310                        in  b runtime,
311                        in  s copy_mode,
312                        out a(sss) changes);
313                 AttachWithExtensions(in  as extensions,
314                                      in  as matches,
315                                      in  s profile,
316                                      in  s copy_mode,
317                                      in  t flags,
318                                      out a(sss) changes);
319                 Detach(in  b runtime,
320                        out a(sss) changes);
321                 DetachWithExtensions(in  as extensions,
322                                      in  t flags,
323                                      out a(sss) changes);
324                 Reattach(in  as matches,
325                          in  s profile,
326                          in  b runtime,
327                          in  s copy_mode,
328                          out a(sss) changes_removed,
329                          out a(sss) changes_updated);
330                 ReattachWithExtensions(in  as extensions,
331                                        in  as matches,
332                                        in  s profile,
333                                        in  s copy_mode,
334                                        in  t flags,
335                                        out a(sss) changes_removed,
336                                        out a(sss) changes_updated);
337                 Remove();
338                 MarkReadOnly(in  b read_only);
339                 SetLimit(in  t limit);
340               properties:
341                 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
342                 readonly s Name = '...';
343                 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
344                 readonly s Path = '...';
345                 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
346                 readonly s Type = '...';
347                 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
348                 readonly b ReadOnly = ...;
349                 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
350                 readonly t CreationTimestamp = ...;
351                 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
352                 readonly t ModificationTimestamp = ...;
353                 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
354                 readonly t Usage = ...;
355                 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
356                 readonly t Limit = ...;
357                 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
358                 readonly t UsageExclusive = ...;
359                 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
360                 readonly t LimitExclusive = ...;
361             };
362             interface org.freedesktop.DBus.Peer { ... };
363             interface org.freedesktop.DBus.Introspectable { ... };
364             interface org.freedesktop.DBus.Properties { ... };
365           };
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393   Methods
394       The following methods implement the same operation as the respective
395       methods on the Manager object (see above). However, these methods
396       operate on the image object and hence does not take an image name
397       parameter. Invoking the methods directly on the Manager object has the
398       advantage of not requiring a GetImage() call to get the image object
399       for a specific image name. Calling the methods on the Manager object is
400       hence a round trip optimization. List of methods:
401
402       •   GetOSRelease()
403
404       •   GetMetadata()
405
406       •   GetMetadataWithExtensions()
407
408       •   GetState()
409
410       •   Attach()
411
412       •   AttachWithExtensions()
413
414       •   Detach()
415
416       •   DetachWithExtensions()
417
418       •   Reattach()
419
420       •   ReattachWithExtensions()
421
422       •   Remove()
423
424       •   MarkReadOnly()
425
426       •   SetLimit()
427
428   Properties
429       Name specifies the image name.
430
431       Path specifies the file system path where image is stored.
432
433       Type specifies the image type.
434
435       ReadOnly specifies whether the image is read-only.
436
437       CreationTimestamp specifies the image creation timestamp.
438
439       ModificationTimestamp specifies the image modification timestamp.
440
441       Usage specifies the image disk usage.
442
443       Limit specifies the image disk usage limit.
444
445       UsageExclusive specifies the image disk usage (exclusive).
446
447       LimitExclusive specifies the image disk usage limit (exclusive).
448

VERSIONING

450       These D-Bus interfaces follow the usual interface versioning
451       guidelines[1].
452

NOTES

454        1. the usual interface versioning guidelines
455           https://0pointer.de/blog/projects/versioning-dbus.html
456
457
458
459systemd 254                                       ORG.FREEDESKTOP.PORTABLE1(5)
Impressum