Debian Codegraph @

upstream/debian-unstable/man5/org.freedesktop.machine1.5

raw
1 '\" t
2 .TH "ORG\&.FREEDESKTOP\&.MACHINE1" "5" "" "systemd 261~rc3" "org.freedesktop.machine1"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 org.freedesktop.machine1 \- The D\-Bus interface of systemd\-machined
24 .SH "INTRODUCTION"
25 .PP
26 \fBsystemd-machined.service\fR(8)
27 is a system service that keeps track of locally running virtual machines and containers\&. This page describes the D\-Bus interface\&.
28 .SH "THE MANAGER OBJECT"
29 .PP
30 The service exposes the following interfaces on the Manager object on the bus:
31 .sp
32 .if n \{\
33 .RS 4
34 .\}
35 .nf
36 node /org/freedesktop/machine1 {
37 interface org\&.freedesktop\&.machine1\&.Manager {
38 methods:
39 GetMachine(in s name,
40 out o machine);
41 GetImage(in s name,
42 out o image);
43 GetMachineByPID(in u pid,
44 out o machine);
45 ListMachines(out a(ssso) machines);
46 ListImages(out a(ssbttto) images);
47 CreateMachine(in s name,
48 in ay id,
49 in s service,
50 in s class,
51 in u leader,
52 in s root_directory,
53 in a(sv) scope_properties,
54 out o path);
55 CreateMachineWithNetwork(in s name,
56 in ay id,
57 in s service,
58 in s class,
59 in u leader,
60 in s root_directory,
61 in ai ifindices,
62 in a(sv) scope_properties,
63 out o path);
64 CreateMachineEx(in s name,
65 in a(sv) properties,
66 in a(sv) scope_properties,
67 out o path);
68 RegisterMachine(in s name,
69 in ay id,
70 in s service,
71 in s class,
72 in u leader,
73 in s root_directory,
74 out o path);
75 RegisterMachineWithNetwork(in s name,
76 in ay id,
77 in s service,
78 in s class,
79 in u leader,
80 in s root_directory,
81 in ai ifindices,
82 out o path);
83 RegisterMachineEx(in s name,
84 in a(sv) properties,
85 out o path);
86 UnregisterMachine(in s name);
87 TerminateMachine(in s id);
88 KillMachine(in s name,
89 in s whom,
90 in i signal);
91 GetMachineAddresses(in s name,
92 out a(iay) addresses);
93 GetMachineSSHInfo(in s name,
94 out s ssh_address,
95 out s ssh_private_key_path);
96 GetMachineOSRelease(in s name,
97 out a{ss} fields);
98 OpenMachinePTY(in s name,
99 out h pty,
100 out s pty_path);
101 OpenMachineLogin(in s name,
102 out h pty,
103 out s pty_path);
104 OpenMachineShell(in s name,
105 in s user,
106 in s path,
107 in as args,
108 in as environment,
109 out h pty,
110 out s pty_path);
111 BindMountMachine(in s name,
112 in s source,
113 in s destination,
114 in b read_only,
115 in b mkdir);
116 CopyFromMachine(in s name,
117 in s source,
118 in s destination);
119 CopyToMachine(in s name,
120 in s source,
121 in s destination);
122 CopyFromMachineWithFlags(in s name,
123 in s source,
124 in s destination,
125 in t flags);
126 CopyToMachineWithFlags(in s name,
127 in s source,
128 in s destination,
129 in t flags);
130 OpenMachineRootDirectory(in s name,
131 out h fd);
132 GetMachineUIDShift(in s name,
133 out u shift);
134 RemoveImage(in s name);
135 RenameImage(in s name,
136 in s new_name);
137 CloneImage(in s name,
138 in s new_name,
139 in b read_only);
140 MarkImageReadOnly(in s name,
141 in b read_only);
142 GetImageHostname(in s name,
143 out s hostname);
144 GetImageMachineID(in s name,
145 out ay id);
146 GetImageMachineInfo(in s name,
147 out a{ss} machine_info);
148 GetImageOSRelease(in s name,
149 out a{ss} os_release);
150 SetPoolLimit(in t size);
151 SetImageLimit(in s name,
152 in t size);
153 CleanPool(in s mode,
154 out a(st) images);
155 MapFromMachineUser(in s name,
156 in u uid_inner,
157 out u uid_outer);
158 MapToMachineUser(in u uid_outer,
159 out s machine_name,
160 out o machine_path,
161 out u uid_inner);
162 MapFromMachineGroup(in s name,
163 in u gid_inner,
164 out u gid_outer);
165 MapToMachineGroup(in u gid_outer,
166 out s machine_name,
167 out o machine_path,
168 out u gid_inner);
169 signals:
170 MachineNew(s machine,
171 o path);
172 MachineRemoved(s machine,
173 o path);
174 properties:
175 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
176 readonly s PoolPath = \*(Aq\&.\&.\&.\*(Aq;
177 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
178 readonly t PoolUsage = \&.\&.\&.;
179 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
180 readonly t PoolLimit = \&.\&.\&.;
181 };
182 interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
183 interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
184 interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
185 };
186 .fi
187 .if n \{\
188 .RE
189 .\}
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238 .SS "Methods"
239 .PP
240 \fBGetMachine()\fR
241 may be used to get the machine object path for the machine with the specified name\&. Similarly,
242 \fBGetMachineByPID()\fR
243 gets the machine object the specified PID belongs to if there is any\&.
244 .PP
245 \fBGetImage()\fR
246 may be used to get the image object path of the image with the specified name\&.
247 .PP
248 \fBListMachines()\fR
249 returns an array of all currently registered machines\&. The structures in the array consist of the following fields: machine name, machine class, an identifier for the service that registered the machine and the machine object path\&.
250 .PP
251 \fBListImages()\fR
252 returns an array of all currently known images\&. The structures in the array consist of the following fields: image name, type, read\-only flag, creation time, modification time, current disk space, and image object path\&.
253 .PP
254 \fBCreateMachine()\fR
255 may be used to register a new virtual machine or container with
256 \fBsystemd\-machined\fR, creating a scope unit for it\&. It accepts the following arguments: a machine name chosen by the registrar, an optional UUID as a 32 byte array, a string that identifies the service that registers the machine, a class string, the PID of the leader process of the machine, an optional root directory of the container, and an array of additional properties to use for the scope registration\&. The virtual machine name must be suitable as a hostname, and hence should follow the usual DNS hostname rules, as well as the Linux hostname restrictions\&. Specifically, only 7 bit ASCII is permitted, a maximum length of 64 characters is enforced, only characters from the set
257 "a\-zA\-Z0\-9\-_\&."
258 are allowed, the name may not begin with a dot, and it may not contain two dots immediately following each other\&. Container and VM managers should ideally use the hostname used internally in the machine for this parameter\&. This recommendation is made in order to make the machine name naturally resolvable using
259 \fBnss-mymachines\fR(8)\&. If a container manager needs to embed characters outside of the indicated range, escaping is required, possibly using
260 "_"
261 as the escape character\&. Another (somewhat natural) option would be to utilize Internet IDNA encoding\&. The UUID is passed as a 32 byte array or, if no suitable UUID is available, an empty array (zero length) or zeroed out array shall be passed\&. The UUID should identify the virtual machine/container uniquely and should ideally be the same UUID that
262 /etc/machine\-id
263 in the VM/container is initialized from\&. The service string can be free\-form, but it is recommended to pass a short lowercase identifier like
264 "systemd\-nspawn",
265 "libvirt\-lxc"
266 or similar\&. The class string should be either
267 "container"
268 or
269 "vm"
270 indicating whether the machine to register is of the respective class\&. The leader PID should be the host PID of the init process of the container or the encapsulating process of the VM\&. If the root directory of the container is known and available in the host\*(Aqs hierarchy, it should be passed (note that this is for informational purposes only, and will not be used otherwise)\&. Otherwise, pass the empty string instead\&. Finally, the scope properties are passed as array in the same way as to PID1\*(Aqs
271 \fBStartTransientUnit()\fR
272 method\&. Calling this method will internally register a transient scope unit for the calling client (utilizing the passed scope_properties) and move the leader PID into it\&. The method returns an object path for the registered machine object that implements the
273 org\&.freedesktop\&.machine1\&.Machine
274 interface (see below)\&. Also see the
275 \m[blue]\fBNew Control Group Interfaces\fR\m[]\&\s-2\u[1]\d\s+2
276 for details about scope units and how to alter resource control settings on the created machine at runtime\&.
277 .PP
278 \fBRegisterMachine()\fR
279 is similar to
280 \fBCreateMachine()\fR\&. However, it only registers a machine and does not create a scope unit for it\&. Instead, the caller\*(Aqs unit is registered\&. We recommend to only use this method for container or VM managers that are run multiple times, one instance for each container/VM they manage, and are invoked as system services\&.
281 .PP
282 \fBRegisterMachineEx()\fR
283 and
284 \fBCreateMachineEx()\fR
285 are similar to the counterparts, but take a series of key/value pairs instead of a fixed number of parameters, to allow for future extensions, and take a PIDFD instead of a PID for the leader parameter\&. The currently supported parameters are:
286 .sp
287 .RS 4
288 .ie n \{\
289 \h'-04'\(bu\h'+03'\c
290 .\}
291 .el \{\
292 .sp -1
293 .IP \(bu 2.3
294 .\}
295 "Id"
296 ("ay"): the machine UUID\&.
297 .RE
298 .sp
299 .RS 4
300 .ie n \{\
301 \h'-04'\(bu\h'+03'\c
302 .\}
303 .el \{\
304 .sp -1
305 .IP \(bu 2.3
306 .\}
307 "Service"
308 ("s"): the service string\&.
309 .RE
310 .sp
311 .RS 4
312 .ie n \{\
313 \h'-04'\(bu\h'+03'\c
314 .\}
315 .el \{\
316 .sp -1
317 .IP \(bu 2.3
318 .\}
319 "Class"
320 ("s"): the class string\&.
321 .RE
322 .sp
323 .RS 4
324 .ie n \{\
325 \h'-04'\(bu\h'+03'\c
326 .\}
327 .el \{\
328 .sp -1
329 .IP \(bu 2.3
330 .\}
331 "LeaderPIDFD"
332 ("h"): A PIDFD for the leader process of the machine\&. This parameter is optional\&. If it is specified, it is preferred over the combination of
333 "LeaderPID"
334 and
335 "LeaderPIDFDID"\&.
336 .RE
337 .sp
338 .RS 4
339 .ie n \{\
340 \h'-04'\(bu\h'+03'\c
341 .\}
342 .el \{\
343 .sp -1
344 .IP \(bu 2.3
345 .\}
346 "LeaderPID"
347 ("u"): A PID for the leader process of the machine\&. This parameter is optional\&. Must be specified together with
348 "LeaderPIDFDID"\&.
349 .RE
350 .sp
351 .RS 4
352 .ie n \{\
353 \h'-04'\(bu\h'+03'\c
354 .\}
355 .el \{\
356 .sp -1
357 .IP \(bu 2.3
358 .\}
359 "LeaderPIDFDID"
360 ("t"): A PIDFDID for the leader process of the machine\&. This parameter is optional\&. Must be specified together with
361 "LeaderPID"\&.
362 .RE
363 .sp
364 .RS 4
365 .ie n \{\
366 \h'-04'\(bu\h'+03'\c
367 .\}
368 .el \{\
369 .sp -1
370 .IP \(bu 2.3
371 .\}
372 "RootDirectory"
373 ("s"): The root directory of the container\&. This parameter is optional and for informational purposes only\&.
374 .RE
375 .sp
376 .RS 4
377 .ie n \{\
378 \h'-04'\(bu\h'+03'\c
379 .\}
380 .el \{\
381 .sp -1
382 .IP \(bu 2.3
383 .\}
384 "NetworkInterfaces"
385 ("ai"): An array of network interface indices, as in
386 \fBCreateMachineWithNetwork()\fR\&. This parameter is optional\&.
387 .RE
388 .PP
389 \fBCreateMachineWithNetwork()\fR
390 and
391 \fBRegisterMachineWithNetwork()\fR
392 are similar to
393 \fBCreateMachine()\fR
394 and
395 \fBRegisterMachine()\fR
396 but take an extra argument: an array of network interface indices that point towards the virtual machine or container\&. The interface indices should reference one or more network interfaces on the host that can be used to communicate with the guest\&. Commonly, the passed interface index refers to the host side of a "veth" link (in case of containers), a "tun"/"tap" link (in case of VMs), or the host side of a bridge interface that bridges access to the VM/container interfaces\&. Specifying this information is useful to enable support for link\-local IPv6 communication to the machines since the scope field of sockaddr_in6 can be initialized by the specified ifindex\&.
397 \fBnss-mymachines\fR(8)
398 makes use of this information\&.
399 .PP
400 \fBKillMachine()\fR
401 sends a UNIX signal to the machine\*(Aqs processes\&. As its arguments, it takes a machine name (as originally passed to
402 \fBCreateMachine()\fR
403 or returned by
404 \fBListMachines()\fR), an identifier that specifies what precisely to send the signal to (either
405 "leader"
406 or
407 "all"), and a numeric UNIX signal integer\&.
408 .PP
409 \fBTerminateMachine()\fR
410 terminates a virtual machine, killing its processes\&. It takes a machine name as its only argument\&.
411 .PP
412 \fBGetMachineAddresses()\fR
413 retrieves the IP addresses of a container\&. This method returns an array of pairs consisting of an address family specifier (\fBAF_INET\fR
414 or
415 \fBAF_INET6\fR) and a byte array containing the addresses\&. This is only supported for containers that make use of network namespacing\&.
416 .PP
417 \fBGetMachineSSHInfo()\fR
418 retrieves the SSH information of a machine\&. This method returns two strings, the SSH address which can be used to tell SSH where to connect, and the path to the SSH private key required for the connection to succeed\&.
419 .PP
420 \fBGetMachineOSRelease()\fR
421 retrieves the OS release information of a container\&. This method returns an array of key value pairs read from the
422 \fBos-release\fR(5)
423 file in the container and is useful to identify the operating system used in a container\&.
424 .PP
425 \fBOpenMachinePTY()\fR
426 allocates a pseudo TTY in the container and returns a file descriptor and its path\&. This is equivalent to transitioning into the container and invoking
427 \fBposix_openpt\fR(3)\&.
428 .PP
429 \fBOpenMachineLogin()\fR
430 allocates a pseudo TTY in the container and ensures that a getty login prompt of the container is running on the other end\&. It returns the file descriptor of the PTY and the PTY path\&. This is useful for acquiring a pty with a login prompt from the container\&.
431 .PP
432 \fBOpenMachineShell()\fR
433 allocates a pseudo TTY in the container, as the specified user, and invokes the executable at the specified path with a list of arguments (starting from argv[0]) and an environment block\&. It then returns the file descriptor of the PTY and the PTY path\&.
434 .PP
435 \fBBindMountMachine()\fR
436 bind mounts a file or directory from the host into the container\&. Its arguments consist of a machine name, the source directory on the host, the destination directory in the container, and two booleans, one indicating whether the bind mount shall be read\-only, the other indicating whether the destination mount point shall be created first, if it is missing\&.
437 .PP
438 \fBCopyFromMachine()\fR
439 copies files or directories from a container into the host\&. It takes a container name, a source directory in the container and a destination directory on the host as arguments\&.
440 \fBCopyToMachine()\fR
441 does the opposite and copies files from a source directory on the host into a destination directory in the container\&.
442 \fBCopyFromMachineWithFlags()\fR
443 and
444 \fBCopyToMachineWithFlags()\fR
445 do the same but take an additional flags argument\&.
446 .PP
447 \fBRemoveImage()\fR
448 removes the image with the specified name\&.
449 .PP
450 \fBRenameImage()\fR
451 renames the specified image\&.
452 .PP
453 \fBCloneImage()\fR
454 clones the specified image under a new name\&. It also takes a boolean argument indicating whether the resulting image shall be read\-only or not\&.
455 .PP
456 \fBMarkImageReadOnly()\fR
457 toggles the read\-only flag of an image\&.
458 .PP
459 \fBSetPoolLimit()\fR
460 sets an overall quota limit on the pool of images\&.
461 .PP
462 \fBSetImageLimit()\fR
463 sets a per\-image quota limit\&.
464 .PP
465 \fBMapFromMachineUser()\fR,
466 \fBMapToMachineUser()\fR,
467 \fBMapFromMachineGroup()\fR, and
468 \fBMapToMachineGroup()\fR
469 may be used to map UIDs/GIDs from the host user namespace to a container user namespace or vice versa\&.
470 .SS "Signals"
471 .PP
472 \fBMachineNew()\fR
473 and
474 \fBMachineRemoved()\fR
475 are sent whenever a new machine is registered or removed\&. These signals carry the machine name and the object path to the corresponding
476 org\&.freedesktop\&.machine1\&.Machine
477 interface (see below)\&.
478 .SS "Properties"
479 .PP
480 \fIPoolPath\fR
481 specifies the file system path where images are written to\&.
482 .PP
483 \fIPoolUsage\fR
484 specifies the current usage size of the image pool in bytes\&.
485 .PP
486 \fIPoolLimit\fR
487 specifies the size limit of the image pool in bytes\&.
488 .SH "MACHINE OBJECTS"
489 .sp
490 .if n \{\
491 .RS 4
492 .\}
493 .nf
494 node /org/freedesktop/machine1/machine/rawhide {
495 interface org\&.freedesktop\&.machine1\&.Machine {
496 methods:
497 Terminate();
498 Kill(in s whom,
499 in i signal);
500 GetAddresses(out a(iay) addresses);
501 GetSSHInfo(out s ssh_address,
502 out s ssh_private_key_path);
503 GetOSRelease(out a{ss} fields);
504 GetUIDShift(out u shift);
505 OpenPTY(out h pty,
506 out s pty_path);
507 OpenLogin(out h pty,
508 out s pty_path);
509 OpenShell(in s user,
510 in s path,
511 in as args,
512 in as environment,
513 out h pty,
514 out s pty_path);
515 BindMount(in s source,
516 in s destination,
517 in b read_only,
518 in b mkdir);
519 CopyFrom(in s source,
520 in s destination);
521 CopyTo(in s source,
522 in s destination);
523 CopyFromWithFlags(in s source,
524 in s destination,
525 in t flags);
526 CopyToWithFlags(in s source,
527 in s destination,
528 in t flags);
529 OpenRootDirectory(out h fd);
530 properties:
531 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
532 readonly s Name = \*(Aq\&.\&.\&.\*(Aq;
533 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
534 readonly ay Id = [\&.\&.\&.];
535 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
536 readonly t Timestamp = \&.\&.\&.;
537 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
538 readonly t TimestampMonotonic = \&.\&.\&.;
539 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
540 readonly s Service = \*(Aq\&.\&.\&.\*(Aq;
541 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
542 readonly s Unit = \*(Aq\&.\&.\&.\*(Aq;
543 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
544 readonly s Subgroup = \*(Aq\&.\&.\&.\*(Aq;
545 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
546 readonly u Leader = \&.\&.\&.;
547 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
548 readonly t LeaderPIDFDId = \&.\&.\&.;
549 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
550 readonly u Supervisor = \&.\&.\&.;
551 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
552 readonly t SupervisorPIDFDId = \&.\&.\&.;
553 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
554 readonly s Class = \*(Aq\&.\&.\&.\*(Aq;
555 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
556 readonly s RootDirectory = \*(Aq\&.\&.\&.\*(Aq;
557 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
558 readonly ai NetworkInterfaces = [\&.\&.\&.];
559 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
560 readonly u VSockCID = \&.\&.\&.;
561 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
562 readonly s SSHAddress = \*(Aq\&.\&.\&.\*(Aq;
563 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
564 readonly s SSHPrivateKeyPath = \*(Aq\&.\&.\&.\*(Aq;
565 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
566 readonly s State = \*(Aq\&.\&.\&.\*(Aq;
567 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
568 readonly u UID = \&.\&.\&.;
569 };
570 interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
571 interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
572 interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
573 };
574 .fi
575 .if n \{\
576 .RE
577 .\}
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613 .SS "Methods"
614 .PP
615 \fBTerminate()\fR
616 and
617 \fBKill()\fR
618 terminate/kill the machine\&. These methods take the same arguments as
619 \fBTerminateMachine()\fR
620 and
621 \fBKillMachine()\fR
622 on the Manager interface, respectively\&.
623 .PP
624 \fBGetAddresses()\fR,
625 \fBGetSSHInfo()\fR
626 and
627 \fBGetOSRelease()\fR
628 get the IP address, SSH connection and OS release information from the machine\&. These methods take the same arguments as
629 \fBGetMachineAddresses()\fR,
630 \fBGetMachineSSHInfo()\fR
631 and
632 \fBGetMachineOSRelease()\fR
633 of the Manager interface, respectively\&.
634 .SS "Properties"
635 .PP
636 \fIName\fR
637 is the machine name as it was passed in during registration with
638 \fBCreateMachine()\fR
639 on the manager object\&.
640 .PP
641 \fIId\fR
642 is the machine UUID\&.
643 .PP
644 \fITimestamp\fR
645 and
646 \fITimestampMonotonic\fR
647 are the realtime and monotonic timestamps when the virtual machines where created in microseconds since the epoch\&.
648 .PP
649 \fIService\fR
650 contains a short string identifying the registering service as passed in during registration of the machine\&.
651 .PP
652 \fIUnit\fR
653 is the systemd scope or service unit name for the machine\&.
654 .PP
655 \fILeader\fR
656 is the PID of the leader process of the machine\&. (The leader process is the top\-level process of the payload of the machine, i\&.e\&. for containers PID 1 inside the container, and for VMs the process encapsulating the VM\&. Its lifetime defines the lifetime of the machine\&.)
657 .PP
658 \fILeaderPIDFDId\fR
659 encodes the Linux pidfd inode ID of the leader process of the machine\&.
660 .PP
661 \fISupervisor\fR
662 is the PID of the supervisor process of the machine\&. (The supervisor process is the process that manages the machine, if there\*(Aqs a separate one for it\&. A supervisor process is not always defined, and does not define the machine\*(Aqs lifetime\&.)
663 .PP
664 \fISupervisorPIDFDId\fR
665 encodes the Linux pidfd inode ID of the supervisor process of the machine\&.
666 .PP
667 \fIClass\fR
668 is the class of the machine and is either the string "vm" (for real VMs based on virtualized hardware) or "container" (for lightweight userspace virtualization sharing the same kernel as the host)\&.
669 .PP
670 \fIRootDirectory\fR
671 is the root directory of the container if it is known and applicable or the empty string\&.
672 .PP
673 \fINetworkInterfaces\fR
674 contains an array of network interface indices that point towards the container, the VM or the host\&. For details about this information see the description of
675 \fBCreateMachineWithNetwork()\fR
676 above\&.
677 .PP
678 \fIVSockCID\fR
679 is the VSOCK CID of the VM if it is known, or
680 \fBVMADDR_CID_ANY\fR
681 otherwise\&.
682 .PP
683 \fISSHAddress\fR
684 is the address of the VM in a format
685 \fBssh\fR
686 can understand if it is known or the empty string\&.
687 .PP
688 \fISSHPrivateKeyPath\fR
689 is the path to the SSH private key of the VM if it is known or the empty string\&.
690 .PP
691 \fIState\fR
692 is the state of the machine and is one of
693 "opening",
694 "running", or
695 "closing"\&. Note that the state machine is not considered part of the API and states might be removed or added without this being considered API breakage\&.
696 .PP
697 \fISubgroup\fR
698 contains the sub\-control\-group path this machine\*(Aqs processes reside in, relative to the specified unit\*(Aqs control group\&.
699 .PP
700 \fIUID\fR
701 contains the numeric UNIX UID of the user who registered the machine\&.
702 .SH "EXAMPLES"
703 .PP
704 \fBExample\ \&1.\ \&Introspect org\&.freedesktop\&.machine1\&.Manager on the bus\fR
705 .sp
706 .if n \{\
707 .RS 4
708 .\}
709 .nf
710 $ gdbus introspect \-\-system \e
711 \-\-dest org\&.freedesktop\&.machine1 \e
712 \-\-object\-path /org/freedesktop/machine1
713 .fi
714 .if n \{\
715 .RE
716 .\}
717 .PP
718 \fBExample\ \&2.\ \&Introspect org\&.freedesktop\&.machine1\&.Machine on the bus\fR
719 .sp
720 .if n \{\
721 .RS 4
722 .\}
723 .nf
724 $ gdbus introspect \-\-system \e
725 \-\-dest org\&.freedesktop\&.machine1 \e
726 \-\-object\-path /org/freedesktop/machine1/machine/rawhide
727 .fi
728 .if n \{\
729 .RE
730 .\}
731 .SH "VERSIONING"
732 .PP
733 These D\-Bus interfaces follow
734 \m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[2]\d\s+2\&.
735 .SH "HISTORY"
736 .SS "The Manager Object"
737 .PP
738 \fBCopyFromMachineWithFlags()\fR
739 and
740 \fBCopyToMachineWithFlags()\fR
741 were added in version 252\&.
742 .PP
743 \fBGetMachineSSHInfo()\fR
744 was added in version 256\&.
745 .SS "Machine Objects"
746 .PP
747 \fBCopyFromWithFlags()\fR
748 and
749 \fBCopyToWithFlags()\fR
750 were added in version 252\&.
751 .PP
752 \fBGetSSHInfo()\fR,
753 \fIVSockCID\fR,
754 \fISSHAddress\fR, and
755 \fISSHPrivateKeyPath\fR
756 were added in version 256\&.
757 .PP
758 \fILeaderPIDFDId\fR,
759 \fISupervisor\fR,
760 \fISupervisorPIDFDId\fR,
761 \fISubgroup\fR, and
762 \fIUID\fR
763 were added in version 258\&.
764 .PP
765 \fBCreateMachineEx()\fR, and
766 \fBRegisterMachineEx()\fR
767 were added in version 259\&.
768 .SH "SEE ALSO"
769 .PP
770 \fBsystemd\fR(1), \fBsystemd-machined.service\fR(8), \fBmachinectl\fR(1)
771 .SH "NOTES"
772 .IP " 1." 4
773 New Control Group Interfaces
774 .RS 4
775 \%https://systemd.io/CONTROL_GROUP_INTERFACE
776 .RE
777 .IP " 2." 4
778 the usual interface versioning guidelines
779 .RS 4
780 \%https://0pointer.de/blog/projects/versioning-dbus.html
781 .RE