1ORG.FREEDESKTOP.MACHINE1(5)org.freedesktop.machine1ORG.FREEDESKTOP.MACHINE1(5)
2
6 org.freedesktop.machine1 - The D-Bus interface of systemd-machined
7
9 systemd-machined.service(8) is a system service that keeps track of
10 locally running virtual machines and containers. This page describes
11 the D-Bus interface.
12
14 The service exposes the following interfaces on the Manager object on
15 the bus:
16 node /org/freedesktop/machine1 {
18 interface org.freedesktop.machine1.Manager {
19 methods:
20 GetMachine(in s name,
21 out o machine);
22 GetImage(in s name,
23 out o image);
24 GetMachineByPID(in u pid,
25 out o machine);
26 ListMachines(out a(ssso) machines);
27 ListImages(out a(ssbttto) images);
28 CreateMachine(in s name,
29 in ay id,
30 in s service,
31 in s class,
32 in u leader,
33 in s root_directory,
34 in a(sv) scope_properties,
35 out o path);
36 CreateMachineWithNetwork(in s name,
37 in ay id,
38 in s service,
39 in s class,
40 in u leader,
41 in s root_directory,
42 in ai ifindices,
43 in a(sv) scope_properties,
44 out o path);
45 RegisterMachine(in s name,
46 in ay id,
47 in s service,
48 in s class,
49 in u leader,
50 in s root_directory,
51 out o path);
52 RegisterMachineWithNetwork(in s name,
53 in ay id,
54 in s service,
55 in s class,
56 in u leader,
57 in s root_directory,
58 in ai ifindices,
59 out o path);
60 UnregisterMachine(in s name);
61 TerminateMachine(in s id);
62 KillMachine(in s name,
63 in s who,
64 in i signal);
65 GetMachineAddresses(in s name,
66 out a(iay) addresses);
67 GetMachineOSRelease(in s name,
68 out a{ss} fields);
69 OpenMachinePTY(in s name,
70 out h pty,
71 out s pty_path);
72 OpenMachineLogin(in s name,
73 out h pty,
74 out s pty_path);
75 OpenMachineShell(in s name,
76 in s user,
77 in s path,
78 in as args,
79 in as environment,
80 out h pty,
81 out s pty_path);
82 BindMountMachine(in s name,
83 in s source,
84 in s destination,
85 in b read_only,
86 in b mkdir);
87 CopyFromMachine(in s name,
88 in s source,
89 in s destination);
90 CopyToMachine(in s name,
91 in s source,
92 in s destination);
93 OpenMachineRootDirectory(in s name,
94 out h fd);
95 GetMachineUIDShift(in s name,
96 out u shift);
97 RemoveImage(in s name);
98 RenameImage(in s name,
99 in s new_name);
100 CloneImage(in s name,
101 in s new_name,
102 in b read_only);
103 MarkImageReadOnly(in s name,
104 in b read_only);
105 GetImageHostname(in s name,
106 out s hostname);
107 GetImageMachineID(in s name,
108 out ay id);
109 GetImageMachineInfo(in s name,
110 out a{ss} machine_info);
111 GetImageOSRelease(in s name,
112 out a{ss} os_release);
113 SetPoolLimit(in t size);
114 SetImageLimit(in s name,
115 in t size);
116 CleanPool(in s mode,
117 out a(st) images);
118 MapFromMachineUser(in s name,
119 in u uid_inner,
120 out u uid_outer);
121 MapToMachineUser(in u uid_outer,
122 out s machine_name,
123 out o machine_path,
124 out u uid_inner);
125 MapFromMachineGroup(in s name,
126 in u gid_inner,
127 out u gid_outer);
128 MapToMachineGroup(in u gid_outer,
129 out s machine_name,
130 out o machine_path,
131 out u gid_inner);
132 signals:
133 MachineNew(s machine,
134 o path);
135 MachineRemoved(s machine,
136 o path);
137 properties:
138 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
139 readonly s PoolPath = '...';
140 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
141 readonly t PoolUsage = ...;
142 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
143 readonly t PoolLimit = ...;
144 };
145 interface org.freedesktop.DBus.Peer { ... };
146 interface org.freedesktop.DBus.Introspectable { ... };
147 interface org.freedesktop.DBus.Properties { ... };
148 };
149 Methods
195 GetMachine() may be used to get the machine object path for the machine
196 with the specified name. Similarly, GetMachineByPID() gets the machine
197 object the specified PID belongs to if there is any.
198 GetImage() may be used to get the image object path of the image with
200 the specified name.
201 ListMachines() returns an array of all currently registered machines.
203 The structures in the array consist of the following fields: machine
204 name, machine class, an identifier for the service that registered the
205 machine and the machine object path.
206 ListImages() returns an array of all currently known images. The
208 structures in the array consist of the following fields: image name,
209 type, read-only flag, creation time, modification time, current disk
210 space, and image object path.
211 CreateMachine() may be used to register a new virtual machine or
213 container with systemd-machined, creating a scope unit for it. It
214 accepts the following arguments: a machine name chosen by the
215 registrar, an optional UUID as a 32 byte array, a string that
216 identifies the service that registers the machine, a class string, the
217 PID of the leader process of the machine, an optional root directory of
218 the container, and an array of additional properties to use for the
219 scope registration. The virtual machine name must be suitable as a
220 hostname, and hence should follow the usual DNS hostname rules, as well
221 as the Linux hostname restrictions. Specifically, only 7 bit ASCII is
222 permitted, a maximum length of 64 characters is enforced, only
223 characters from the set "a-zA-Z0-9-_." are allowed, the name may not
224 begin with a dot, and it may not contain two dots immediately following
225 each other. Container and VM managers should ideally use the hostname
226 used internally in the machine for this parameter. This recommendation
227 is made in order to make the machine name naturally resolvable using
228 nss-mymachines(8). If a container manager needs to embed characters
229 outside of the indicated range, escaping is required, possibly using
230 "_" as the escape character. Another (somewhat natural) option would be
231 to utilize Internet IDNA encoding. The UUID is passed as a 32 byte
232 array or, if no suitable UUID is available, an empty array (zero
233 length) or zeroed out array shall be passed. The UUID should identify
234 the virtual machine/container uniquely and should ideally be the same
235 UUID that /etc/machine-id in the VM/container is initialized from. The
236 service string can be free-form, but it is recommended to pass a short
237 lowercase identifier like "systemd-nspawn", "libvirt-lxc" or similar.
238 The class string should be either "container" or "vm" indicating
239 whether the machine to register is of the respective class. The leader
240 PID should be the host PID of the init process of the container or the
241 encapsulating process of the VM. If the root directory of the container
242 is known and available in the host's hierarchy, it should be passed.
243 Otherwise, pass the empty string instead. Finally, the scope properties
244 are passed as array in the same way as to PID1's StartTransientUnit()
245 method. Calling this method will internally register a transient scope
246 unit for the calling client (utilizing the passed scope_properties) and
247 move the leader PID into it. The method returns an object path for the
248 registered machine object that implements the
249 org.freedesktop.machine1.Machine interface (see below). Also see the
250 New Control Group Interfaces[1] for details about scope units and how
251 to alter resource control settings on the created machine at runtime.
252 RegisterMachine() is similar to CreateMachine(). However, it only
254 registers a machine and does not create a scope unit for it. Instead,
255 the caller's unit is registered. We recommend to only use this method
256 for container or VM managers that are run multiple times, one instance
257 for each container/VM they manage, and are invoked as system services.
258 CreateMachineWithNetwork() and RegisterMachineWithNetwork() are similar
260 to CreateMachine() and RegisterMachine() but take an extra argument: an
261 array of network interface indices that point towards the virtual
262 machine or container. The interface indices should reference one or
263 more network interfaces on the host that can be used to communicate
264 with the guest. Commonly, the passed interface index refers to the host
265 side of a "veth" link (in case of containers), a "tun"/"tap" link (in
266 case of VMs), or the host side of a bridge interface that bridges
267 access to the VM/container interfaces. Specifying this information is
268 useful to enable support for link-local IPv6 communication to the
269 machines since the scope field of sockaddr_in6 can be initialized by
270 the specified ifindex. nss-mymachines(8) makes use of this
271 information.
272 KillMachine() sends a UNIX signal to the machine's processes. As its
274 arguments, it takes a machine name (as originally passed to
275 CreateMachine() or returned by ListMachines()), an identifier that
276 specifies what precisely to send the signal to (either "leader" or
277 "all"), and a numeric UNIX signal integer.
278 TerminateMachine() terminates a virtual machine, killing its processes.
280 It takes a machine name as its only argument.
281 GetMachineAddresses() retrieves the IP addresses of a container. This
283 method returns an array of pairs consisting of an address family
284 specifier (AF_INET or AF_INET6) and a byte array containing the
285 addresses. This is only supported for containers that make use of
286 network namespacing.
287 GetMachineOSRelease() retrieves the OS release information of a
289 container. This method returns an array of key value pairs read from
290 the os-release(5) file in the container and is useful to identify the
291 operating system used in a container.
292 OpenMachinePTY() allocates a pseudo TTY in the container and returns a
294 file descriptor and its path. This is equivalent to transitioning into
295 the container and invoking posix_openpt(3).
296 OpenMachineLogin() allocates a pseudo TTY in the container and ensures
298 that a getty login prompt of the container is running on the other end.
299 It returns the file descriptor of the PTY and the PTY path. This is
300 useful for acquiring a pty with a login prompt from the container.
301 OpenMachineShell() allocates a pseudo TTY in the container, as the
303 specified user, and invokes the executable at the specified path with a
304 list of arguments (starting from argv[0]) and an environment block. It
305 then returns the file descriptor of the PTY and the PTY path.
306 BindMountMachine() bind mounts a file or directory from the host into
308 the container. Its arguments consist of a machine name, the source
309 directory on the host, the destination directory in the container, and
310 two booleans, one indicating whether the bind mount shall be read-only,
311 the other indicating whether the destination mount point shall be
312 created first, if it is missing.
313 CopyFromMachine() copies files or directories from a container into the
315 host. It takes a container name, a source directory in the container
316 and a destination directory on the host as arguments. CopyToMachine()
317 does the opposite and copies files from a source directory on the host
318 into a destination directory in the container.
319 RemoveImage() removes the image with the specified name.
321 RenameImage() renames the specified image.
323 CloneImage() clones the specified image under a new name. It also takes
325 a boolean argument indicating whether the resulting image shall be
326 read-only or not.
327 MarkImageReadOnly() toggles the read-only flag of an image.
329 SetPoolLimit() sets an overall quota limit on the pool of images.
331 SetImageLimit() sets a per-image quota limit.
333 MapFromMachineUser(), MapToMachineUser(), MapFromMachineGroup(), and
335 MapToMachineGroup() may be used to map UIDs/GIDs from the host user
336 namespace to a container user namespace or vice versa.
337 Signals
339 MachineNew and MachineRemoved are sent whenever a new machine is
340 registered or removed. These signals carry the machine name and the
341 object path to the corresponding org.freedesktop.machine1.Machine
342 interface (see below).
343 Properties
345 PoolPath specifies the file system path where images are written to.
346 PoolUsage specifies the current usage size of the image pool in bytes.
348 PoolLimit specifies the size limit of the image pool in bytes.
350
352 node /org/freedesktop/machine1/machine/rawhide {
353 interface org.freedesktop.machine1.Machine {
354 methods:
355 Terminate();
356 Kill(in s who,
357 in i signal);
358 GetAddresses(out a(iay) addresses);
359 GetOSRelease(out a{ss} fields);
360 GetUIDShift(out u shift);
361 OpenPTY(out h pty,
362 out s pty_path);
363 OpenLogin(out h pty,
364 out s pty_path);
365 OpenShell(in s user,
366 in s path,
367 in as args,
368 in as environment,
369 out h pty,
370 out s pty_path);
371 BindMount(in s source,
372 in s destination,
373 in b read_only,
374 in b mkdir);
375 CopyFrom(in s source,
376 in s destination);
377 CopyTo(in s source,
378 in s destination);
379 OpenRootDirectory(out h fd);
380 properties:
381 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
382 readonly s Name = '...';
383 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
384 readonly ay Id = [...];
385 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
386 readonly t Timestamp = ...;
387 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
388 readonly t TimestampMonotonic = ...;
389 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
390 readonly s Service = '...';
391 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
392 readonly s Unit = '...';
393 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
394 readonly u Leader = ...;
395 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
396 readonly s Class = '...';
397 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
398 readonly s RootDirectory = '...';
399 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
400 readonly ai NetworkInterfaces = [...];
401 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
402 readonly s State = '...';
403 };
404 interface org.freedesktop.DBus.Peer { ... };
405 interface org.freedesktop.DBus.Introspectable { ... };
406 interface org.freedesktop.DBus.Properties { ... };
407 };
408 Methods
435 Terminate() and Kill() terminate/kill the machine. These methods take
436 the same arguments as TerminateMachine() and KillMachine() on the
437 Manager interface, respectively.
438 GetAddresses() and GetOSRelease() get the IP address and OS release
440 information from the machine. These methods take the same arguments as
441 GetMachineAddresses() and GetMachineOSRelease() of the Manager
442 interface, respectively.
443 Properties
445 Name is the machine name as it was passed in during registration with
446 CreateMachine() on the manager object.
447 Id is the machine UUID.
449 Timestamp and TimestampMonotonic are the realtime and monotonic
451 timestamps when the virtual machines where created in microseconds
452 since the epoch.
453 Service contains a short string identifying the registering service as
455 passed in during registration of the machine.
456 Unit is the systemd scope or service unit name for the machine.
458 Leader is the PID of the leader process of the machine.
460 Class is the class of the machine and is either the string "vm" (for
462 real VMs based on virtualized hardware) or "container" (for
463 light-weight userspace virtualization sharing the same kernel as the
464 host).
465 RootDirectory is the root directory of the container if it is known and
467 applicable or the empty string.
468 NetworkInterfaces contains an array of network interface indices that
470 point towards the container, the VM or the host. For details about this
471 information see the description of CreateMachineWithNetwork() above.
472 State is the state of the machine and is one of "opening", "running",
474 or "closing". Note that the state machine is not considered part of the
475 API and states might be removed or added without this being considered
476 API breakage.
477
479 Example 1. Introspect org.freedesktop.machine1.Manager on the bus
480 $ gdbus introspect --system \
482 --dest org.freedesktop.machine1 \
483 --object-path /org/freedesktop/machine1
484 Example 2. Introspect org.freedesktop.machine1.Machine on the bus
487 $ gdbus introspect --system \
489 --dest org.freedesktop.machine1 \
490 --object-path /org/freedesktop/machine1/machine/rawhide
491
494 These D-Bus interfaces follow the usual interface versioning
495 guidelines[2].
496
498 1. New Control Group Interfaces
499 https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/
500 2. the usual interface versioning guidelines
502 http://0pointer.de/blog/projects/versioning-dbus.html
503systemd 249 ORG.FREEDESKTOP.MACHINE1(5)