1ORG.FREEDESKTOP.MACHINE1(5)org.freedesktop.machine1ORG.FREEDESKTOP.MACHINE1(5)
2
3
4

NAME

6       org.freedesktop.machine1 - The D-Bus interface of systemd-machined
7

INTRODUCTION

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

THE MANAGER OBJECT

14       The service exposes the following interfaces on the Manager object on
15       the bus:
16
17           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
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199   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
204       GetImage() may be used to get the image object path of the image with
205       the specified name.
206
207       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
212       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
217       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
258       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
264       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
278       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
284       TerminateMachine() terminates a virtual machine, killing its processes.
285       It takes a machine name as its only argument.
286
287       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
293       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
298       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
302       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
307       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
312       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
319       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
325       RemoveImage() removes the image with the specified name.
326
327       RenameImage() renames the specified image.
328
329       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
333       MarkImageReadOnly() toggles the read-only flag of an image.
334
335       SetPoolLimit() sets an overall quota limit on the pool of images.
336
337       SetImageLimit() sets a per-image quota limit.
338
339       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
343   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
349   Properties
350       PoolPath specifies the file system path where images are written to.
351
352       PoolUsage specifies the current usage size of the image pool in bytes.
353
354       PoolLimit specifies the size limit of the image pool in bytes.
355

MACHINE OBJECTS

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
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439   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
444       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
449   Properties
450       Name is the machine name as it was passed in during registration with
451       CreateMachine() on the manager object.
452
453       Id is the machine UUID.
454
455       Timestamp and TimestampMonotonic are the realtime and monotonic
456       timestamps when the virtual machines where created in microseconds
457       since the epoch.
458
459       Service contains a short string identifying the registering service as
460       passed in during registration of the machine.
461
462       Unit is the systemd scope or service unit name for the machine.
463
464       Leader is the PID of the leader process of the machine.
465
466       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
471       RootDirectory is the root directory of the container if it is known and
472       applicable or the empty string.
473
474       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
478       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

EXAMPLES

484       Example 1. Introspect org.freedesktop.machine1.Manager on the bus
485
486           $ gdbus introspect --system \
487             --dest org.freedesktop.machine1 \
488             --object-path /org/freedesktop/machine1
489
490
491       Example 2. Introspect org.freedesktop.machine1.Machine on the bus
492
493           $ gdbus introspect --system \
494             --dest org.freedesktop.machine1 \
495             --object-path /org/freedesktop/machine1/machine/rawhide
496
497

VERSIONING

499       These D-Bus interfaces follow the usual interface versioning
500       guidelines[2].
501

NOTES

503        1. New Control Group Interfaces
504           https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/
505
506        2. the usual interface versioning guidelines
507           http://0pointer.de/blog/projects/versioning-dbus.html
508
509
510
511systemd 251                                        ORG.FREEDESKTOP.MACHINE1(5)
Impressum