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                 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
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
200
201
202
203
204
205
206
207
208
209   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
214       GetImage() may be used to get the image object path of the image with
215       the specified name.
216
217       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
222       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
227       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
268       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
274       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
288       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
294       TerminateMachine() terminates a virtual machine, killing its processes.
295       It takes a machine name as its only argument.
296
297       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
303       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
308       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
312       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
317       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
322       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
329       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
337       RemoveImage() removes the image with the specified name.
338
339       RenameImage() renames the specified image.
340
341       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
345       MarkImageReadOnly() toggles the read-only flag of an image.
346
347       SetPoolLimit() sets an overall quota limit on the pool of images.
348
349       SetImageLimit() sets a per-image quota limit.
350
351       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
355   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
361   Properties
362       PoolPath specifies the file system path where images are written to.
363
364       PoolUsage specifies the current usage size of the image pool in bytes.
365
366       PoolLimit specifies the size limit of the image pool in bytes.
367

MACHINE OBJECTS

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
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459   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
464       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
469   Properties
470       Name is the machine name as it was passed in during registration with
471       CreateMachine() on the manager object.
472
473       Id is the machine UUID.
474
475       Timestamp and TimestampMonotonic are the realtime and monotonic
476       timestamps when the virtual machines where created in microseconds
477       since the epoch.
478
479       Service contains a short string identifying the registering service as
480       passed in during registration of the machine.
481
482       Unit is the systemd scope or service unit name for the machine.
483
484       Leader is the PID of the leader process of the machine.
485
486       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
491       RootDirectory is the root directory of the container if it is known and
492       applicable or the empty string.
493
494       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
498       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

EXAMPLES

504       Example 1. Introspect org.freedesktop.machine1.Manager on the bus
505
506           $ gdbus introspect --system \
507             --dest org.freedesktop.machine1 \
508             --object-path /org/freedesktop/machine1
509
510
511       Example 2. Introspect org.freedesktop.machine1.Machine on the bus
512
513           $ gdbus introspect --system \
514             --dest org.freedesktop.machine1 \
515             --object-path /org/freedesktop/machine1/machine/rawhide
516
517

VERSIONING

519       These D-Bus interfaces follow the usual interface versioning
520       guidelines[2].
521

NOTES

523        1. New Control Group Interfaces
524           https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface
525
526        2. the usual interface versioning guidelines
527           https://0pointer.de/blog/projects/versioning-dbus.html
528
529
530
531systemd 253                                        ORG.FREEDESKTOP.MACHINE1(5)
Impressum