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