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                 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
150
151
152
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   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
199       GetImage() may be used to get the image object path of the image with
200       the specified name.
201
202       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
207       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
212       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
253       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
259       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
273       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
279       TerminateMachine() terminates a virtual machine, killing its processes.
280       It takes a machine name as its only argument.
281
282       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
288       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
293       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
297       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
302       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
307       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
314       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
320       RemoveImage() removes the image with the specified name.
321
322       RenameImage() renames the specified image.
323
324       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
328       MarkImageReadOnly() toggles the read-only flag of an image.
329
330       SetPoolLimit() sets an overall quota limit on the pool of images.
331
332       SetImageLimit() sets a per-image quota limit.
333
334       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
338   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
344   Properties
345       PoolPath specifies the file system path where images are written to.
346
347       PoolUsage specifies the current usage size of the image pool in bytes.
348
349       PoolLimit specifies the size limit of the image pool in bytes.
350

MACHINE OBJECTS

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

EXAMPLES

479       Example 1. Introspect org.freedesktop.machine1.Manager on the bus
480
481           $ gdbus introspect --system \
482             --dest org.freedesktop.machine1 \
483             --object-path /org/freedesktop/machine1
484
485
486       Example 2. Introspect org.freedesktop.machine1.Machine on the bus
487
488           $ gdbus introspect --system \
489             --dest org.freedesktop.machine1 \
490             --object-path /org/freedesktop/machine1/machine/rawhide
491
492

VERSIONING

494       These D-Bus interfaces follow the usual interface versioning
495       guidelines[2].
496

NOTES

498        1. New Control Group Interfaces
499           https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/
500
501        2. the usual interface versioning guidelines
502           http://0pointer.de/blog/projects/versioning-dbus.html
503
504
505
506systemd 248                                        ORG.FREEDESKTOP.MACHINE1(5)
Impressum