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). The flag parameter is currently
215 unused and reserved for future purposes.
216 DetachImage() detaches a portable image from the system. This method
218 takes an image path or name, and a boolean indicating whether the image
219 to detach was attached only for the current boot session or
220 persistently. This method returns the list of changes applied to the
221 system (for example, which unit was removed and is no longer available
222 as a system service). Each change is represented as a triplet of
223 strings: the type of change applied, the path on which it was applied,
224 and the source (if any). The type of change applied will be one of the
225 following possible values:
226 • unlink
228 Note that an image cannot be detached if a unit that it contains is
230 running.
231 DetachImageWithExtensions() detaches a portable image from the system.
233 This method is a superset of DetachImage() with the addition of a list
234 of extensions as input parameter, which were overlaid on top of the
235 main image via AttachImageWithExtensions(). The flag parameter is
236 currently unused and reserved for future purposes.
237 ReattachImage() combines the effects of the AttachImage() method and
239 the DetachImage() method. The difference is that it is allowed to
240 reattach an image while one or more of its units are running. The
241 reattach operation will fail if no matching image is attached. The
242 input parameters match the AttachImage() method, and the return
243 parameters are the combination of the return parameters of the
244 DetachImage() method (first array, units that were removed) and the
245 AttachImage() method (second array, units that were updated or added).
246 ReattachImageWithExtensions() reattaches a portable image to the
248 system. This method is a superset of ReattachImage() with the addition
249 of a list of extensions as input parameter, which will be overlaid on
250 top of the main image. For more details on this functionality, see the
251 MountImages= entry on systemd.exec(5) and systemd-sysext(8). The flag
252 parameter is currently unused and reserved for future purposes
253 RemoveImage() removes the image with the specified name.
255 MarkImageReadOnly() toggles the read-only flag of an image.
257 SetPoolLimit() sets an overall quota limit on the pool of images.
259 SetImageLimit() sets a per-image quota limit.
261 The AttachImageWithExtensions(), DetachImageWithExtensions() and
263 ReattachImageWithExtensions() methods take in options as flags instead
264 of booleans to allow for extendability, defined as follows:
265 #define SD_SYSTEMD_PORTABLE_RUNTIME (UINT64_C(1) << 0)
267 Properties
270 PoolPath specifies the file system path where images are written to.
271 PoolUsage specifies the current usage size of the image pool in bytes.
273 PoolLimit specifies the size limit of the image pool in bytes.
275 Profiles specifies the available runtime profiles for portable
277 services.
278
280 The service exposes the following interfaces on the Image object on the
281 bus:
282 node /org/freedesktop/portable1 {
284 interface org.freedesktop.portable1.Image {
285 methods:
286 GetOSRelease(out a{ss} os_release);
287 GetMetadata(in as matches,
288 out s image,
289 out ay os_release,
290 out a{say} units);
291 GetMetadataWithExtensions(in as extensions,
292 in as matches,
293 in t flags,
294 out s image,
295 out ay os_release,
296 out a{say} extensions,
297 out a{say} units);
298 GetState(out s state);
299 GetStateWithExtensions(in as extensions,
300 in t flags,
301 out s state);
302 Attach(in as matches,
303 in s profile,
304 in b runtime,
305 in s copy_mode,
306 out a(sss) changes);
307 AttachWithExtensions(in as extensions,
308 in as matches,
309 in s profile,
310 in s copy_mode,
311 in t flags,
312 out a(sss) changes);
313 Detach(in b runtime,
314 out a(sss) changes);
315 DetachWithExtensions(in as extensions,
316 in t flags,
317 out a(sss) changes);
318 Reattach(in as matches,
319 in s profile,
320 in b runtime,
321 in s copy_mode,
322 out a(sss) changes_removed,
323 out a(sss) changes_updated);
324 ReattacheWithExtensions(in as extensions,
325 in as matches,
326 in s profile,
327 in s copy_mode,
328 in t flags,
329 out a(sss) changes_removed,
330 out a(sss) changes_updated);
331 Remove();
332 MarkReadOnly(in b read_only);
333 SetLimit(in t limit);
334 properties:
335 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
336 readonly s Name = '...';
337 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
338 readonly s Path = '...';
339 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
340 readonly s Type = '...';
341 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
342 readonly b ReadOnly = ...;
343 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
344 readonly t CreationTimestamp = ...;
345 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
346 readonly t ModificationTimestamp = ...;
347 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
348 readonly t Usage = ...;
349 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
350 readonly t Limit = ...;
351 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
352 readonly t UsageExclusive = ...;
353 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
354 readonly t LimitExclusive = ...;
355 };
356 interface org.freedesktop.DBus.Peer { ... };
357 interface org.freedesktop.DBus.Introspectable { ... };
358 interface org.freedesktop.DBus.Properties { ... };
359 };
360 Methods
388 The following methods implement the same operation as the respective
389 methods on the Manager object (see above). However, these methods
390 operate on the image object and hence does not take an image name
391 parameter. Invoking the methods directly on the Manager object has the
392 advantage of not requiring a GetImage() call to get the image object
393 for a specific image name. Calling the methods on the Manager object is
394 hence a round trip optimization. List of methods:
395 • GetOSRelease()
397 • GetMetadata()
399 • GetMetadataWithExtensions()
401 • GetState()
403 • Attach()
405 • AttachWithExtensions()
407 • Detach()
409 • DetachWithExtensions()
411 • Reattach()
413 • ReattacheWithExtensions()
415 • Remove()
417 • MarkReadOnly()
419 • SetLimit()
421 Properties
423 Name specifies the image name.
424 Path specifies the file system path where image is stored.
426 Type specifies the image type.
428 ReadOnly specifies whether the image is read-only.
430 CreationTimestamp specifies the image creation timestamp.
432 ModificationTimestamp specifies the image modification timestamp.
434 Usage specifies the image disk usage.
436 Limit specifies the image disk usage limit.
438 UsageExclusive specifies the image disk usage (exclusive).
440 LimitExclusive specifies the image disk usage limit (exclusive).
442
444 These D-Bus interfaces follow the usual interface versioning
445 guidelines[1].
446
448 1. the usual interface versioning guidelines
449 http://0pointer.de/blog/projects/versioning-dbus.html
450systemd 251 ORG.FREEDESKTOP.PORTABLE1(5)