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