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