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 GetImageState(in s image,
31 out s state);
32 AttachImage(in s image,
33 in as matches,
34 in s profile,
35 in b runtime,
36 in s copy_mode,
37 out a(sss) changes);
38 DetachImage(in s image,
39 in b runtime,
40 out a(sss) changes);
41 ReattachImage(in s image,
42 in as matches,
43 in s profile,
44 in b runtime,
45 in s copy_mode,
46 out a(sss) changes_removed,
47 out a(sss) changes_updated);
48 RemoveImage(in s image);
49 MarkImageReadOnly(in s image,
50 in b read_only);
51 SetImageLimit(in s image,
52 in t limit);
53 SetPoolLimit(in t limit);
54 properties:
55 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
56 readonly s PoolPath = '...';
57 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
58 readonly t PoolUsage = ...;
59 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
60 readonly t PoolLimit = ...;
61 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
62 readonly as Profiles = ['...', ...];
63 };
64 interface org.freedesktop.DBus.Peer { ... };
65 interface org.freedesktop.DBus.Introspectable { ... };
66 interface org.freedesktop.DBus.Properties { ... };
67 };
68 Methods
88 GetImage() may be used to get the image object path of the image with
89 the specified name.
90 ListImages() returns an array of all currently known images. The
92 structures in the array consist of the following fields: image name,
93 type, read-only flag, creation time, modification time, current disk
94 space, usage and image object path.
95 GetImageOSRelease() retrieves the OS release information of an image.
97 This method returns an array of key value pairs read from the os-
98 release(5) file in the image and is useful to identify the operating
99 system used in a portable service.
100 GetImageMetadata() retrieves metadata associated with an image. This
102 method returns the image name, the image's os-release(5) content in the
103 form of a (streamable) array of bytes, and a list of portable units
104 contained in the image, in the form of a string (unit name) and an
105 array of bytes with the content.
106 GetImageState() retrieves the image state as one of the following
108 strings:
109 • detached
111 • attached
113 • attached-runtime
115 • enabled
117 • enabled-runtime
119 • running
121 • running-runtime
123 AttachImage() attaches a portable image to the system. This method
125 takes an image path or name, a list of strings that will be used to
126 search for unit files inside the image (partial or complete matches), a
127 string indicating which portable profile to use for the image (see
128 Profiles property for a list of available profiles), a boolean
129 indicating whether to attach the image only for the current boot
130 session, and a string representing the preferred copy mode (whether to
131 copy the image or to just symlink it) with the following possible
132 values:
133 • (null)
135 • copy
137 • symlink
139 This method returns the list of changes applied to the system (for
141 example, which unit was added and is now available as a system
142 service). Each change is represented as a triplet of strings: the type
143 of change applied, the path on which it was applied, and the source (if
144 any). The type of change applied will be one of the following possible
145 values:
146 • copy
148 • symlink
150 • write
152 • mkdir
154 Note that an image cannot be attached if a unit that it contains is
156 already present on the system.
157 DetachImage() detaches a portable image from the system. This method
159 takes an image path or name, and a boolean indicating whether the image
160 to detach was attached only for the current boot session or
161 persistently. This method returns the list of changes applied to the
162 system (for example, which unit was removed and is no longer available
163 as a system service). Each change is represented as a triplet of
164 strings: the type of change applied, the path on which it was applied,
165 and the source (if any). The type of change applied will be one of the
166 following possible values:
167 • unlink
169 Note that an image cannot be detached if a unit that it contains is
171 running.
172 ReattachImage() combines the effects of the AttachImage() method and
174 the DetachImage() method. The difference is that it is allowed to
175 reattach an image while one or more of its units are running. The
176 reattach operation will fail if no matching image is attached. The
177 input parameters match the AttachImage() method, and the return
178 parameters are the combination of the return parameters of the
179 DetachImage() method (first array, units that were removed) and the
180 AttachImage() method (second array, units that were updated or added).
181 RemoveImage() removes the image with the specified name.
183 MarkImageReadOnly() toggles the read-only flag of an image.
185 SetPoolLimit() sets an overall quota limit on the pool of images.
187 SetImageLimit() sets a per-image quota limit.
189 Properties
191 PoolPath specifies the file system path where images are written to.
192 PoolUsage specifies the current usage size of the image pool in bytes.
194 PoolLimit specifies the size limit of the image pool in bytes.
196 Profiles specifies the available runtime profiles for portable
198 services.
199
201 The service exposes the following interfaces on the Image object on the
202 bus:
203 node /org/freedesktop/portable1 {
205 interface org.freedesktop.portable1.Image {
206 methods:
207 GetOSRelease(out a{ss} os_release);
208 GetMetadata(in as matches,
209 out s image,
210 out ay os_release,
211 out a{say} units);
212 GetState(out s state);
213 Attach(in as matches,
214 in s profile,
215 in b runtime,
216 in s copy_mode,
217 out a(sss) changes);
218 Detach(in b runtime,
219 out a(sss) changes);
220 Reattach(in as matches,
221 in s profile,
222 in b runtime,
223 in s copy_mode,
224 out a(sss) changes_removed,
225 out a(sss) changes_updated);
226 Remove();
227 MarkReadOnly(in b read_only);
228 SetLimit(in t limit);
229 properties:
230 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
231 readonly s Name = '...';
232 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
233 readonly s Path = '...';
234 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
235 readonly s Type = '...';
236 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
237 readonly b ReadOnly = ...;
238 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
239 readonly t CreationTimestamp = ...;
240 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
241 readonly t ModificationTimestamp = ...;
242 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
243 readonly t Usage = ...;
244 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
245 readonly t Limit = ...;
246 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
247 readonly t UsageExclusive = ...;
248 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
249 readonly t LimitExclusive = ...;
250 };
251 interface org.freedesktop.DBus.Peer { ... };
252 interface org.freedesktop.DBus.Introspectable { ... };
253 interface org.freedesktop.DBus.Properties { ... };
254 };
255 Methods
278 The following methods implement the same operation as the respective
279 methods on the Manager object (see above). However, these methods
280 operate on the image object and hence does not take an image name
281 parameter. Invoking the methods directly on the Manager object has the
282 advantage of not requiring a GetImage() call to get the image object
283 for a specific image name. Calling the methods on the Manager object is
284 hence a round trip optimization. List of methods:
285 • GetOSRelease()
287 • GetMetadata()
289 • GetState()
291 • Attach()
293 • Detach()
295 • Reattach()
297 • Remove()
299 • MarkReadOnly()
301 • SetLimit()
303 Properties
305 Name specifies the image name.
306 Path specifies the file system path where image is stored.
308 Type specifies the image type.
310 ReadOnly specifies whether the image is read-only.
312 CreationTimestamp specifies the image creation timestamp.
314 ModificationTimestamp specifies the image modification timestamp.
316 Usage specifies the image disk usage.
318 Limit specifies the image disk usage limit.
320 UsageExclusive specifies the image disk usage (exclusive).
322 LimitExclusive specifies the image disk usage limit (exclusive).
324
326 These D-Bus interfaces follow the usual interface versioning
327 guidelines[1].
328
330 1. the usual interface versioning guidelines
331 http://0pointer.de/blog/projects/versioning-dbus.html
332systemd 248 ORG.FREEDESKTOP.PORTABLE1(5)