1ORG.FREEDESKTOP.PORTABLE1(5)org.freedesktop.portableO1RG.FREEDESKTOP.PORTABLE1(5)
2
6 org.freedesktop.portable1 - The D-Bus interface of systemd-portabled
7
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
14 The service exposes the following interfaces on the Manager object on
15 the bus:
16 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 Methods
124 GetImage() may be used to get the image object path of the image with
125 the specified name.
126 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 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 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 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 GetImageState() retrieves the image state as one of the following
152 strings:
153 • detached
155 • attached
157 • attached-runtime
159 • enabled
161 • enabled-runtime
163 • running
165 • running-runtime
167 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 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 • (null)
185 • copy
187 • symlink
189 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 • copy
198 • symlink
200 • write
202 • mkdir
204 Note that an image cannot be attached if a unit that it contains is
206 already present on the system.
207 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 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 • unlink
227 Note that an image cannot be detached if a unit that it contains is
229 running.
230 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 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 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 RemoveImage() removes the image with the specified name.
254 MarkImageReadOnly() toggles the read-only flag of an image.
256 SetPoolLimit() sets an overall quota limit on the pool of images.
258 SetImageLimit() sets a per-image quota limit.
260 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 #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 Properties
276 PoolPath specifies the file system path where images are written to.
277 PoolUsage specifies the current usage size of the image pool in bytes.
279 PoolLimit specifies the size limit of the image pool in bytes.
281 Profiles specifies the available runtime profiles for portable
283 services.
284
286 The service exposes the following interfaces on the Image object on the
287 bus:
288 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 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 • GetOSRelease()
403 • GetMetadata()
405 • GetMetadataWithExtensions()
407 • GetState()
409 • Attach()
411 • AttachWithExtensions()
413 • Detach()
415 • DetachWithExtensions()
417 • Reattach()
419 • ReattachWithExtensions()
421 • Remove()
423 • MarkReadOnly()
425 • SetLimit()
427 Properties
429 Name specifies the image name.
430 Path specifies the file system path where image is stored.
432 Type specifies the image type.
434 ReadOnly specifies whether the image is read-only.
436 CreationTimestamp specifies the image creation timestamp.
438 ModificationTimestamp specifies the image modification timestamp.
440 Usage specifies the image disk usage.
442 Limit specifies the image disk usage limit.
444 UsageExclusive specifies the image disk usage (exclusive).
446 LimitExclusive specifies the image disk usage limit (exclusive).
448
450 These D-Bus interfaces follow the usual interface versioning
451 guidelines[1].
452
454 1. the usual interface versioning guidelines
455 https://0pointer.de/blog/projects/versioning-dbus.html
456systemd 254 ORG.FREEDESKTOP.PORTABLE1(5)