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 AttachImage(in s image,
41 in as matches,
42 in s profile,
43 in b runtime,
44 in s copy_mode,
45 out a(sss) changes);
46 AttachImageWithExtensions(in s image,
47 in as extensions,
48 in as matches,
49 in s profile,
50 in s copy_mode,
51 in t flags,
52 out a(sss) changes);
53 DetachImage(in s image,
54 in b runtime,
55 out a(sss) changes);
56 DetachImageWithExtensions(in s image,
57 in as extensions,
58 in t flags,
59 out a(sss) changes);
60 ReattachImage(in s image,
61 in as matches,
62 in s profile,
63 in b runtime,
64 in s copy_mode,
65 out a(sss) changes_removed,
66 out a(sss) changes_updated);
67 ReattachImageWithExtensions(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_removed,
74 out a(sss) changes_updated);
75 RemoveImage(in s image);
76 MarkImageReadOnly(in s image,
77 in b read_only);
78 SetImageLimit(in s image,
79 in t limit);
80 SetPoolLimit(in t limit);
81 properties:
82 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
83 readonly s PoolPath = '...';
84 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
85 readonly t PoolUsage = ...;
86 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
87 readonly t PoolLimit = ...;
88 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
89 readonly as Profiles = ['...', ...];
90 };
91 interface org.freedesktop.DBus.Peer { ... };
92 interface org.freedesktop.DBus.Introspectable { ... };
93 interface org.freedesktop.DBus.Properties { ... };
94 };
95 Methods
119 GetImage() may be used to get the image object path of the image with
120 the specified name.
121 ListImages() returns an array of all currently known images. The
123 structures in the array consist of the following fields: image name,
124 type, read-only flag, creation time, modification time, current disk
125 space, usage and image object path.
126 GetImageOSRelease() retrieves the OS release information of an image.
128 This method returns an array of key value pairs read from the os-
129 release(5) file in the image and is useful to identify the operating
130 system used in a portable service.
131 GetImageMetadata() retrieves metadata associated with an image. This
133 method returns the image name, the image's os-release(5) content in the
134 form of a (streamable) array of bytes, and a list of portable units
135 contained in the image, in the form of a string (unit name) and an
136 array of bytes with the content.
137 GetImageMetadataWithExtensions() retrieves metadata associated with an
139 image. This method is a superset of GetImageMetadata() with the
140 addition of a list of extensions as input parameter, which were
141 overlaid on top of the main image via AttachImageWithExtensions(). The
142 path of each extension and an array of bytes with the content of the
143 respective extension-release file are returned, one such structure for
144 each extension named in the input arguments.
145 GetImageState() retrieves the image state as one of the following
147 strings:
148 • detached
150 • attached
152 • attached-runtime
154 • enabled
156 • enabled-runtime
158 • running
160 • running-runtime
162 AttachImage() attaches a portable image to the system. This method
164 takes an image path or name, a list of strings that will be used to
165 search for unit files inside the image (partial or complete matches), a
166 string indicating which portable profile to use for the image (see
167 Profiles property for a list of available profiles), a boolean
168 indicating whether to attach the image only for the current boot
169 session, and a string representing the preferred copy mode (whether to
170 copy the image or to just symlink it) with the following possible
171 values:
172 • (null)
174 • copy
176 • symlink
178 This method returns the list of changes applied to the system (for
180 example, which unit was added and is now available as a system
181 service). Each change is represented as a triplet of strings: the type
182 of change applied, the path on which it was applied, and the source (if
183 any). The type of change applied will be one of the following possible
184 values:
185 • copy
187 • symlink
189 • write
191 • mkdir
193 Note that an image cannot be attached if a unit that it contains is
195 already present on the system.
196 AttachImageWithExtensions() attaches a portable image to the system.
198 This method is a superset of AttachImage() with the addition of a list
199 of extensions as input parameter, which will be overlaid on top of the
200 main image. When this method is used, detaching must be done by passing
201 the same arguments via the DetachImageWithExtensions() method. For more
202 details on this functionality, see the MountImages= entry on
203 systemd.exec(5) and systemd-sysext(8). The flag parameter is currently
204 unused and reserved for future purposes.
205 DetachImage() detaches a portable image from the system. This method
207 takes an image path or name, and a boolean indicating whether the image
208 to detach was attached only for the current boot session or
209 persistently. This method returns the list of changes applied to the
210 system (for example, which unit was removed and is no longer available
211 as a system service). Each change is represented as a triplet of
212 strings: the type of change applied, the path on which it was applied,
213 and the source (if any). The type of change applied will be one of the
214 following possible values:
215 • unlink
217 Note that an image cannot be detached if a unit that it contains is
219 running.
220 DetachImageWithExtensions() detaches a portable image from the system.
222 This method is a superset of DetachImage() with the addition of a list
223 of extensions as input parameter, which were overlaid on top of the
224 main image via AttachImageWithExtensions(). The flag parameter is
225 currently unused and reserved for future purposes.
226 ReattachImage() combines the effects of the AttachImage() method and
228 the DetachImage() method. The difference is that it is allowed to
229 reattach an image while one or more of its units are running. The
230 reattach operation will fail if no matching image is attached. The
231 input parameters match the AttachImage() method, and the return
232 parameters are the combination of the return parameters of the
233 DetachImage() method (first array, units that were removed) and the
234 AttachImage() method (second array, units that were updated or added).
235 ReattachImageWithExtensions() reattaches a portable image to the
237 system. This method is a superset of ReattachImage() with the addition
238 of a list of extensions as input parameter, which will be overlaid on
239 top of the main image. For more details on this functionality, see the
240 MountImages= entry on systemd.exec(5) and systemd-sysext(8). The flag
241 parameter is currently unused and reserved for future purposes
242 RemoveImage() removes the image with the specified name.
244 MarkImageReadOnly() toggles the read-only flag of an image.
246 SetPoolLimit() sets an overall quota limit on the pool of images.
248 SetImageLimit() sets a per-image quota limit.
250 The AttachImageWithExtensions(), DetachImageWithExtensions() and
252 ReattachImageWithExtensions() methods take in options as flags instead
253 of booleans to allow for extendability, defined as follows:
254 #define SD_SYSTEMD_PORTABLE_RUNTIME (UINT64_C(1) << 0)
256 Properties
259 PoolPath specifies the file system path where images are written to.
260 PoolUsage specifies the current usage size of the image pool in bytes.
262 PoolLimit specifies the size limit of the image pool in bytes.
264 Profiles specifies the available runtime profiles for portable
266 services.
267
269 The service exposes the following interfaces on the Image object on the
270 bus:
271 node /org/freedesktop/portable1 {
273 interface org.freedesktop.portable1.Image {
274 methods:
275 GetOSRelease(out a{ss} os_release);
276 GetMetadata(in as matches,
277 out s image,
278 out ay os_release,
279 out a{say} units);
280 GetMetadataWithExtensions(in as extensions,
281 in as matches,
282 in t flags,
283 out s image,
284 out ay os_release,
285 out a{say} extensions,
286 out a{say} units);
287 GetState(out s state);
288 Attach(in as matches,
289 in s profile,
290 in b runtime,
291 in s copy_mode,
292 out a(sss) changes);
293 AttachWithExtensions(in as extensions,
294 in as matches,
295 in s profile,
296 in s copy_mode,
297 in t flags,
298 out a(sss) changes);
299 Detach(in b runtime,
300 out a(sss) changes);
301 DetachWithExtensions(in as extensions,
302 in t flags,
303 out a(sss) changes);
304 Reattach(in as matches,
305 in s profile,
306 in b runtime,
307 in s copy_mode,
308 out a(sss) changes_removed,
309 out a(sss) changes_updated);
310 ReattacheWithExtensions(in as extensions,
311 in as matches,
312 in s profile,
313 in s copy_mode,
314 in t flags,
315 out a(sss) changes_removed,
316 out a(sss) changes_updated);
317 Remove();
318 MarkReadOnly(in b read_only);
319 SetLimit(in t limit);
320 properties:
321 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
322 readonly s Name = '...';
323 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
324 readonly s Path = '...';
325 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
326 readonly s Type = '...';
327 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
328 readonly b ReadOnly = ...;
329 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
330 readonly t CreationTimestamp = ...;
331 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
332 readonly t ModificationTimestamp = ...;
333 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
334 readonly t Usage = ...;
335 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
336 readonly t Limit = ...;
337 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
338 readonly t UsageExclusive = ...;
339 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
340 readonly t LimitExclusive = ...;
341 };
342 interface org.freedesktop.DBus.Peer { ... };
343 interface org.freedesktop.DBus.Introspectable { ... };
344 interface org.freedesktop.DBus.Properties { ... };
345 };
346 Methods
373 The following methods implement the same operation as the respective
374 methods on the Manager object (see above). However, these methods
375 operate on the image object and hence does not take an image name
376 parameter. Invoking the methods directly on the Manager object has the
377 advantage of not requiring a GetImage() call to get the image object
378 for a specific image name. Calling the methods on the Manager object is
379 hence a round trip optimization. List of methods:
380 • GetOSRelease()
382 • GetMetadata()
384 • GetMetadataWithExtensions()
386 • GetState()
388 • Attach()
390 • AttachWithExtensions()
392 • Detach()
394 • DetachWithExtensions()
396 • Reattach()
398 • ReattacheWithExtensions()
400 • Remove()
402 • MarkReadOnly()
404 • SetLimit()
406 Properties
408 Name specifies the image name.
409 Path specifies the file system path where image is stored.
411 Type specifies the image type.
413 ReadOnly specifies whether the image is read-only.
415 CreationTimestamp specifies the image creation timestamp.
417 ModificationTimestamp specifies the image modification timestamp.
419 Usage specifies the image disk usage.
421 Limit specifies the image disk usage limit.
423 UsageExclusive specifies the image disk usage (exclusive).
425 LimitExclusive specifies the image disk usage limit (exclusive).
427
429 These D-Bus interfaces follow the usual interface versioning
430 guidelines[1].
431
433 1. the usual interface versioning guidelines
434 http://0pointer.de/blog/projects/versioning-dbus.html
435systemd 250 ORG.FREEDESKTOP.PORTABLE1(5)