1<?xml version='1.0'?> 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" > 4<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> 5 6<refentry id="org.freedesktop.machine1" conditional='ENABLE_MACHINED' 7 xmlns:xi="http://www.w3.org/2001/XInclude"> 8 <refentryinfo> 9 <title>org.freedesktop.machine1</title> 10 <productname>systemd</productname> 11 </refentryinfo> 12 13 <refmeta> 14 <refentrytitle>org.freedesktop.machine1</refentrytitle> 15 <manvolnum>5</manvolnum> 16 </refmeta> 17 18 <refnamediv> 19 <refname>org.freedesktop.machine1</refname> 20 <refpurpose>The D-Bus interface of systemd-machined</refpurpose> 21 </refnamediv> 22 23 <refsect1> 24 <title>Introduction</title> 25 26 <para> 27 <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> 28 is a system service that keeps track of locally running virtual machines and containers. 29 This page describes the D-Bus interface.</para> 30 </refsect1> 31 32 <refsect1> 33 <title>The Manager Object</title> 34 35 <para>The service exposes the following interfaces on the Manager object on the bus:</para> 36 37 <programlisting executable="systemd-machined" node="/org/freedesktop/machine1" interface="org.freedesktop.machine1.Manager"> 38node /org/freedesktop/machine1 { 39 interface org.freedesktop.machine1.Manager { 40 methods: 41 GetMachine(in s name, 42 out o machine); 43 GetImage(in s name, 44 out o image); 45 GetMachineByPID(in u pid, 46 out o machine); 47 ListMachines(out a(ssso) machines); 48 ListImages(out a(ssbttto) images); 49 @org.freedesktop.systemd1.Privileged("true") 50 CreateMachine(in s name, 51 in ay id, 52 in s service, 53 in s class, 54 in u leader, 55 in s root_directory, 56 in a(sv) scope_properties, 57 out o path); 58 @org.freedesktop.systemd1.Privileged("true") 59 CreateMachineWithNetwork(in s name, 60 in ay id, 61 in s service, 62 in s class, 63 in u leader, 64 in s root_directory, 65 in ai ifindices, 66 in a(sv) scope_properties, 67 out o path); 68 @org.freedesktop.systemd1.Privileged("true") 69 RegisterMachine(in s name, 70 in ay id, 71 in s service, 72 in s class, 73 in u leader, 74 in s root_directory, 75 out o path); 76 @org.freedesktop.systemd1.Privileged("true") 77 RegisterMachineWithNetwork(in s name, 78 in ay id, 79 in s service, 80 in s class, 81 in u leader, 82 in s root_directory, 83 in ai ifindices, 84 out o path); 85 UnregisterMachine(in s name); 86 TerminateMachine(in s id); 87 KillMachine(in s name, 88 in s who, 89 in i signal); 90 GetMachineAddresses(in s name, 91 out a(iay) addresses); 92 GetMachineOSRelease(in s name, 93 out a{ss} fields); 94 @org.freedesktop.systemd1.Privileged("true") 95 OpenMachinePTY(in s name, 96 out h pty, 97 out s pty_path); 98 OpenMachineLogin(in s name, 99 out h pty, 100 out s pty_path); 101 OpenMachineShell(in s name, 102 in s user, 103 in s path, 104 in as args, 105 in as environment, 106 out h pty, 107 out s pty_path); 108 BindMountMachine(in s name, 109 in s source, 110 in s destination, 111 in b read_only, 112 in b mkdir); 113 CopyFromMachine(in s name, 114 in s source, 115 in s destination); 116 CopyToMachine(in s name, 117 in s source, 118 in s destination); 119 OpenMachineRootDirectory(in s name, 120 out h fd); 121 GetMachineUIDShift(in s name, 122 out u shift); 123 RemoveImage(in s name); 124 RenameImage(in s name, 125 in s new_name); 126 CloneImage(in s name, 127 in s new_name, 128 in b read_only); 129 MarkImageReadOnly(in s name, 130 in b read_only); 131 GetImageHostname(in s name, 132 out s hostname); 133 GetImageMachineID(in s name, 134 out ay id); 135 GetImageMachineInfo(in s name, 136 out a{ss} machine_info); 137 GetImageOSRelease(in s name, 138 out a{ss} os_release); 139 SetPoolLimit(in t size); 140 SetImageLimit(in s name, 141 in t size); 142 CleanPool(in s mode, 143 out a(st) images); 144 MapFromMachineUser(in s name, 145 in u uid_inner, 146 out u uid_outer); 147 MapToMachineUser(in u uid_outer, 148 out s machine_name, 149 out o machine_path, 150 out u uid_inner); 151 MapFromMachineGroup(in s name, 152 in u gid_inner, 153 out u gid_outer); 154 MapToMachineGroup(in u gid_outer, 155 out s machine_name, 156 out o machine_path, 157 out u gid_inner); 158 signals: 159 MachineNew(s machine, 160 o path); 161 MachineRemoved(s machine, 162 o path); 163 properties: 164 @org.freedesktop.DBus.Property.EmitsChangedSignal("false") 165 readonly s PoolPath = '...'; 166 @org.freedesktop.DBus.Property.EmitsChangedSignal("false") 167 readonly t PoolUsage = ...; 168 @org.freedesktop.DBus.Property.EmitsChangedSignal("false") 169 readonly t PoolLimit = ...; 170 }; 171 interface org.freedesktop.DBus.Peer { ... }; 172 interface org.freedesktop.DBus.Introspectable { ... }; 173 interface org.freedesktop.DBus.Properties { ... }; 174}; 175 </programlisting> 176 177 <!--method UnregisterMachine is not documented!--> 178 179 <!--method OpenMachineRootDirectory is not documented!--> 180 181 <!--method GetMachineUIDShift is not documented!--> 182 183 <!--method GetImageHostname is not documented!--> 184 185 <!--method GetImageMachineID is not documented!--> 186 187 <!--method GetImageMachineInfo is not documented!--> 188 189 <!--method GetImageOSRelease is not documented!--> 190 191 <!--method CleanPool is not documented!--> 192 193 <!--Autogenerated cross-references for systemd.directives, do not edit--> 194 195 <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.machine1.Manager"/> 196 197 <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.machine1.Manager"/> 198 199 <variablelist class="dbus-method" generated="True" extra-ref="GetMachine()"/> 200 201 <variablelist class="dbus-method" generated="True" extra-ref="GetImage()"/> 202 203 <variablelist class="dbus-method" generated="True" extra-ref="GetMachineByPID()"/> 204 205 <variablelist class="dbus-method" generated="True" extra-ref="ListMachines()"/> 206 207 <variablelist class="dbus-method" generated="True" extra-ref="ListImages()"/> 208 209 <variablelist class="dbus-method" generated="True" extra-ref="CreateMachine()"/> 210 211 <variablelist class="dbus-method" generated="True" extra-ref="CreateMachineWithNetwork()"/> 212 213 <variablelist class="dbus-method" generated="True" extra-ref="RegisterMachine()"/> 214 215 <variablelist class="dbus-method" generated="True" extra-ref="RegisterMachineWithNetwork()"/> 216 217 <variablelist class="dbus-method" generated="True" extra-ref="UnregisterMachine()"/> 218 219 <variablelist class="dbus-method" generated="True" extra-ref="TerminateMachine()"/> 220 221 <variablelist class="dbus-method" generated="True" extra-ref="KillMachine()"/> 222 223 <variablelist class="dbus-method" generated="True" extra-ref="GetMachineAddresses()"/> 224 225 <variablelist class="dbus-method" generated="True" extra-ref="GetMachineOSRelease()"/> 226 227 <variablelist class="dbus-method" generated="True" extra-ref="OpenMachinePTY()"/> 228 229 <variablelist class="dbus-method" generated="True" extra-ref="OpenMachineLogin()"/> 230 231 <variablelist class="dbus-method" generated="True" extra-ref="OpenMachineShell()"/> 232 233 <variablelist class="dbus-method" generated="True" extra-ref="BindMountMachine()"/> 234 235 <variablelist class="dbus-method" generated="True" extra-ref="CopyFromMachine()"/> 236 237 <variablelist class="dbus-method" generated="True" extra-ref="CopyToMachine()"/> 238 239 <variablelist class="dbus-method" generated="True" extra-ref="OpenMachineRootDirectory()"/> 240 241 <variablelist class="dbus-method" generated="True" extra-ref="GetMachineUIDShift()"/> 242 243 <variablelist class="dbus-method" generated="True" extra-ref="RemoveImage()"/> 244 245 <variablelist class="dbus-method" generated="True" extra-ref="RenameImage()"/> 246 247 <variablelist class="dbus-method" generated="True" extra-ref="CloneImage()"/> 248 249 <variablelist class="dbus-method" generated="True" extra-ref="MarkImageReadOnly()"/> 250 251 <variablelist class="dbus-method" generated="True" extra-ref="GetImageHostname()"/> 252 253 <variablelist class="dbus-method" generated="True" extra-ref="GetImageMachineID()"/> 254 255 <variablelist class="dbus-method" generated="True" extra-ref="GetImageMachineInfo()"/> 256 257 <variablelist class="dbus-method" generated="True" extra-ref="GetImageOSRelease()"/> 258 259 <variablelist class="dbus-method" generated="True" extra-ref="SetPoolLimit()"/> 260 261 <variablelist class="dbus-method" generated="True" extra-ref="SetImageLimit()"/> 262 263 <variablelist class="dbus-method" generated="True" extra-ref="CleanPool()"/> 264 265 <variablelist class="dbus-method" generated="True" extra-ref="MapFromMachineUser()"/> 266 267 <variablelist class="dbus-method" generated="True" extra-ref="MapToMachineUser()"/> 268 269 <variablelist class="dbus-method" generated="True" extra-ref="MapFromMachineGroup()"/> 270 271 <variablelist class="dbus-method" generated="True" extra-ref="MapToMachineGroup()"/> 272 273 <variablelist class="dbus-signal" generated="True" extra-ref="MachineNew"/> 274 275 <variablelist class="dbus-signal" generated="True" extra-ref="MachineRemoved"/> 276 277 <variablelist class="dbus-property" generated="True" extra-ref="PoolPath"/> 278 279 <variablelist class="dbus-property" generated="True" extra-ref="PoolUsage"/> 280 281 <variablelist class="dbus-property" generated="True" extra-ref="PoolLimit"/> 282 283 <!--End of Autogenerated section--> 284 285 <refsect2> 286 <title>Methods</title> 287 288 <para><function>GetMachine()</function> may be used to get the machine object path for the machine with 289 the specified name. Similarly, <function>GetMachineByPID()</function> gets the machine object the 290 specified PID belongs to if there is any.</para> 291 292 <para><function>GetImage()</function> may be used to get the image object path of the image with the 293 specified name.</para> 294 295 <para><function>ListMachines()</function> returns an array of all currently registered machines. The 296 structures in the array consist of the following fields: machine name, machine class, an identifier for 297 the service that registered the machine and the machine object path.</para> 298 299 <para><function>ListImages()</function> returns an array of all currently known images. The 300 structures in the array consist of the following fields: image name, type, read-only flag, creation 301 time, modification time, current disk space, and image object path.</para> 302 303 <para><function>CreateMachine()</function> may be used to register a new virtual machine or container 304 with <command>systemd-machined</command>, creating a scope unit for it. It accepts the following arguments: a 305 machine name chosen by the registrar, an optional UUID as a 32 byte array, a string that identifies the 306 service that registers the machine, a class string, the PID of the leader process of the machine, an 307 optional root directory of the container, and an array of additional properties to use for the scope 308 registration. The virtual machine name must be suitable as a hostname, and hence should follow the usual 309 DNS hostname rules, as well as the Linux hostname restrictions. Specifically, only 7 bit ASCII is 310 permitted, a maximum length of 64 characters is enforced, only characters from the set 311 <literal>a-zA-Z0-9-_.</literal> are allowed, the name may not begin with a dot, and it may not contain 312 two dots immediately following each other. Container and VM managers should ideally use the hostname 313 used internally in the machine for this parameter. This recommendation is made in order to make the 314 machine name naturally resolvable using 315 <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>. If 316 a container manager needs to embed characters outside of the indicated range, escaping is required, 317 possibly using <literal>_</literal> as the escape character. Another (somewhat natural) option would be 318 to utilize Internet IDNA encoding. The UUID is passed as a 32 byte array or, if no suitable UUID is 319 available, an empty array (zero length) or zeroed out array shall be passed. The UUID should identify 320 the virtual machine/container uniquely and should ideally be the same UUID that 321 <filename>/etc/machine-id</filename> in the VM/container is initialized from. The service string can be 322 free-form, but it is recommended to pass a short lowercase identifier like 323 <literal>systemd-nspawn</literal>, <literal>libvirt-lxc</literal> or similar. The class string should 324 be either <literal>container</literal> or <literal>vm</literal> indicating whether the machine to 325 register is of the respective class. The leader PID should be the host PID of the init process of the 326 container or the encapsulating process of the VM. If the root directory of the container is known and 327 available in the host's hierarchy, it should be passed. Otherwise, pass the empty string instead. Finally, the 328 scope properties are passed as array in the same way as to PID1's 329 <function>StartTransientUnit()</function> method. Calling this method will internally register a transient scope 330 unit for the calling client (utilizing the passed scope_properties) and move the leader PID into 331 it. The method returns an object path for the registered machine object that implements the 332 <interfacename>org.freedesktop.machine1.Machine</interfacename> interface (see below). Also see the 333 <ulink url="https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New Control Group 334 Interfaces</ulink> for details about scope units and how to alter resource control settings on the 335 created machine at runtime.</para> 336 337 <para><function>RegisterMachine()</function> is similar to <function>CreateMachine()</function>. 338 However, it only registers a machine and does not create a scope unit for it. Instead, the caller's unit is 339 registered. We recommend to only use this method for container or VM managers that are run 340 multiple times, one instance for each container/VM they manage, and are invoked as system 341 services.</para> 342 343 <para><function>CreateMachineWithNetwork()</function> and 344 <function>RegisterMachineWithNetwork()</function> are similar to <function>CreateMachine()</function> 345 and <function>RegisterMachine()</function> but take an extra argument: an array of network interface 346 indices that point towards the virtual machine or container. The interface indices should reference one 347 or more network interfaces on the host that can be used to communicate with the guest. Commonly, the 348 passed interface index refers to the host side of a "veth" link (in case of containers), a 349 "tun"/"tap" link (in case of VMs), or the host side of a bridge interface that bridges access to the 350 VM/container interfaces. Specifying this information is useful to enable support for link-local IPv6 351 communication to the machines since the scope field of sockaddr_in6 can be initialized by the 352 specified ifindex. 353 <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry> 354 makes use of this information.</para> 355 356 <para><function>KillMachine()</function> sends a UNIX signal to the machine's processes. As its arguments, it takes a 357 machine name (as originally passed to <function>CreateMachine()</function> or returned by 358 <function>ListMachines()</function>), an identifier that specifies what precisely to send the signal to (either 359 <literal>leader</literal> or <literal>all</literal>), and a numeric UNIX signal integer.</para> 360 361 <para><function>TerminateMachine()</function> terminates a virtual machine, killing its processes. It 362 takes a machine name as its only argument.</para> 363 364 <para><function>GetMachineAddresses()</function> retrieves the IP addresses of a container. This method 365 returns an array of pairs consisting of an address family specifier (<constant>AF_INET</constant> or 366 <constant>AF_INET6</constant>) and a byte array containing the addresses. This is only supported for 367 containers that make use of network namespacing.</para> 368 369 <para><function>GetMachineOSRelease()</function> retrieves the OS release information of a 370 container. This method returns an array of key value pairs read from the 371 <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file in 372 the container and is useful to identify the operating system used in a container.</para> 373 374 <para><function>OpenMachinePTY()</function> allocates a pseudo TTY in the container and returns a file 375 descriptor and its path. This is equivalent to transitioning into the container and invoking 376 <citerefentry project="man-pages"><refentrytitle>posix_openpt</refentrytitle><manvolnum>3</manvolnum></citerefentry>. 377 </para> 378 379 <para><function>OpenMachineLogin()</function> allocates a pseudo TTY in the container and ensures that 380 a getty login prompt of the container is running on the other end. It returns the file descriptor of 381 the PTY and the PTY path. This is useful for acquiring a pty with a login prompt from the 382 container.</para> 383 384 <para><function>OpenMachineShell()</function> allocates a pseudo TTY in the container, as the specified 385 user, and invokes the executable at the specified path with a list of arguments (starting from 386 argv[0]) and an environment block. It then returns the file descriptor of the PTY and the PTY 387 path.</para> 388 389 <para><function>BindMountMachine()</function> bind mounts a file or directory from the host into the 390 container. Its arguments consist of a machine name, the source directory on the host, the destination directory in the 391 container, and two booleans, one indicating whether the bind mount shall be 392 read-only, the other indicating whether the destination mount point shall be created first, if it is 393 missing.</para> 394 395 <para><function>CopyFromMachine()</function> copies files or directories from a container into the 396 host. It takes a container name, a source directory in the container and a destination directory on the 397 host as arguments. <function>CopyToMachine()</function> does the opposite and copies files from a source 398 directory on the host into a destination directory in the container.</para> 399 400 <para><function>RemoveImage()</function> removes the image with the specified name.</para> 401 402 <para><function>RenameImage()</function> renames the specified image.</para> 403 404 <para><function>CloneImage()</function> clones the specified image under a new name. It also takes a 405 boolean argument indicating whether the resulting image shall be read-only or not.</para> 406 407 <para><function>MarkImageReadOnly()</function> toggles the read-only flag of an image.</para> 408 409 <para><function>SetPoolLimit()</function> sets an overall quota limit on the pool of images.</para> 410 411 <para><function>SetImageLimit()</function> sets a per-image quota limit.</para> 412 413 <para><function>MapFromMachineUser()</function>, <function>MapToMachineUser()</function>, 414 <function>MapFromMachineGroup()</function>, and <function>MapToMachineGroup()</function> may be used to map 415 UIDs/GIDs from the host user namespace to a container user namespace or vice versa.</para> 416 </refsect2> 417 418 <refsect2> 419 <title>Signals</title> 420 421 <para><function>MachineNew</function> and <function>MachineRemoved</function> are sent whenever a new 422 machine is registered or removed. These signals carry the machine name and the object path to the corresponding 423 <interfacename>org.freedesktop.machine1.Machine</interfacename> interface (see below).</para> 424 </refsect2> 425 426 <refsect2> 427 <title>Properties</title> 428 429 <para><varname>PoolPath</varname> specifies the file system path where images are written to.</para> 430 431 <para><varname>PoolUsage</varname> specifies the current usage size of the image pool in bytes.</para> 432 433 <para><varname>PoolLimit</varname> specifies the size limit of the image pool in bytes.</para> 434 </refsect2> 435 </refsect1> 436 437 <refsect1> 438 <title>Machine Objects</title> 439 440 <programlisting executable="systemd-machined" node="/org/freedesktop/machine1/machine/rawhide" interface="org.freedesktop.machine1.Machine"> 441node /org/freedesktop/machine1/machine/rawhide { 442 interface org.freedesktop.machine1.Machine { 443 methods: 444 Terminate(); 445 Kill(in s who, 446 in i signal); 447 GetAddresses(out a(iay) addresses); 448 GetOSRelease(out a{ss} fields); 449 GetUIDShift(out u shift); 450 OpenPTY(out h pty, 451 out s pty_path); 452 OpenLogin(out h pty, 453 out s pty_path); 454 OpenShell(in s user, 455 in s path, 456 in as args, 457 in as environment, 458 out h pty, 459 out s pty_path); 460 BindMount(in s source, 461 in s destination, 462 in b read_only, 463 in b mkdir); 464 CopyFrom(in s source, 465 in s destination); 466 CopyTo(in s source, 467 in s destination); 468 OpenRootDirectory(out h fd); 469 properties: 470 @org.freedesktop.DBus.Property.EmitsChangedSignal("const") 471 readonly s Name = '...'; 472 @org.freedesktop.DBus.Property.EmitsChangedSignal("const") 473 readonly ay Id = [...]; 474 @org.freedesktop.DBus.Property.EmitsChangedSignal("const") 475 readonly t Timestamp = ...; 476 @org.freedesktop.DBus.Property.EmitsChangedSignal("const") 477 readonly t TimestampMonotonic = ...; 478 @org.freedesktop.DBus.Property.EmitsChangedSignal("const") 479 readonly s Service = '...'; 480 @org.freedesktop.DBus.Property.EmitsChangedSignal("const") 481 readonly s Unit = '...'; 482 @org.freedesktop.DBus.Property.EmitsChangedSignal("const") 483 readonly u Leader = ...; 484 @org.freedesktop.DBus.Property.EmitsChangedSignal("const") 485 readonly s Class = '...'; 486 @org.freedesktop.DBus.Property.EmitsChangedSignal("const") 487 readonly s RootDirectory = '...'; 488 @org.freedesktop.DBus.Property.EmitsChangedSignal("const") 489 readonly ai NetworkInterfaces = [...]; 490 @org.freedesktop.DBus.Property.EmitsChangedSignal("false") 491 readonly s State = '...'; 492 }; 493 interface org.freedesktop.DBus.Peer { ... }; 494 interface org.freedesktop.DBus.Introspectable { ... }; 495 interface org.freedesktop.DBus.Properties { ... }; 496}; 497 </programlisting> 498 499 <!--method GetUIDShift is not documented!--> 500 501 <!--method OpenPTY is not documented!--> 502 503 <!--method OpenLogin is not documented!--> 504 505 <!--method OpenShell is not documented!--> 506 507 <!--method BindMount is not documented!--> 508 509 <!--method CopyFrom is not documented!--> 510 511 <!--method CopyTo is not documented!--> 512 513 <!--method OpenRootDirectory is not documented!--> 514 515 <!--Autogenerated cross-references for systemd.directives, do not edit--> 516 517 <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.machine1.Machine"/> 518 519 <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.machine1.Machine"/> 520 521 <variablelist class="dbus-method" generated="True" extra-ref="Terminate()"/> 522 523 <variablelist class="dbus-method" generated="True" extra-ref="Kill()"/> 524 525 <variablelist class="dbus-method" generated="True" extra-ref="GetAddresses()"/> 526 527 <variablelist class="dbus-method" generated="True" extra-ref="GetOSRelease()"/> 528 529 <variablelist class="dbus-method" generated="True" extra-ref="GetUIDShift()"/> 530 531 <variablelist class="dbus-method" generated="True" extra-ref="OpenPTY()"/> 532 533 <variablelist class="dbus-method" generated="True" extra-ref="OpenLogin()"/> 534 535 <variablelist class="dbus-method" generated="True" extra-ref="OpenShell()"/> 536 537 <variablelist class="dbus-method" generated="True" extra-ref="BindMount()"/> 538 539 <variablelist class="dbus-method" generated="True" extra-ref="CopyFrom()"/> 540 541 <variablelist class="dbus-method" generated="True" extra-ref="CopyTo()"/> 542 543 <variablelist class="dbus-method" generated="True" extra-ref="OpenRootDirectory()"/> 544 545 <variablelist class="dbus-property" generated="True" extra-ref="Name"/> 546 547 <variablelist class="dbus-property" generated="True" extra-ref="Id"/> 548 549 <variablelist class="dbus-property" generated="True" extra-ref="Timestamp"/> 550 551 <variablelist class="dbus-property" generated="True" extra-ref="TimestampMonotonic"/> 552 553 <variablelist class="dbus-property" generated="True" extra-ref="Service"/> 554 555 <variablelist class="dbus-property" generated="True" extra-ref="Unit"/> 556 557 <variablelist class="dbus-property" generated="True" extra-ref="Leader"/> 558 559 <variablelist class="dbus-property" generated="True" extra-ref="Class"/> 560 561 <variablelist class="dbus-property" generated="True" extra-ref="RootDirectory"/> 562 563 <variablelist class="dbus-property" generated="True" extra-ref="NetworkInterfaces"/> 564 565 <variablelist class="dbus-property" generated="True" extra-ref="State"/> 566 567 <!--End of Autogenerated section--> 568 569 <refsect2> 570 <title>Methods</title> 571 572 <para><function>Terminate()</function> and <function>Kill()</function> terminate/kill the machine. These methods 573 take the same arguments as <function>TerminateMachine()</function> and 574 <function>KillMachine()</function> on the Manager interface, respectively.</para> 575 576 <para><function>GetAddresses()</function> and <function>GetOSRelease()</function> get the IP address and OS 577 release information from the machine. These methods take the same arguments as 578 <function>GetMachineAddresses()</function> and <function>GetMachineOSRelease()</function> of the 579 Manager interface, respectively.</para> 580 </refsect2> 581 582 <refsect2> 583 <title>Properties</title> 584 585 <para><varname>Name</varname> is the machine name as it was passed in during registration with 586 <function>CreateMachine()</function> on the manager object.</para> 587 588 <para><varname>Id</varname> is the machine UUID.</para> 589 590 <para><varname>Timestamp</varname> and <varname>TimestampMonotonic</varname> are the realtime and 591 monotonic timestamps when the virtual machines where created in microseconds since the epoch.</para> 592 593 <para><varname>Service</varname> contains a short string identifying the registering service as passed 594 in during registration of the machine.</para> 595 596 <para><varname>Unit</varname> is the systemd scope or service unit name for the machine.</para> 597 598 <para><varname>Leader</varname> is the PID of the leader process of the machine.</para> 599 600 <para><varname>Class</varname> is the class of the machine and is either the string "vm" (for real VMs 601 based on virtualized hardware) or "container" (for light-weight userspace virtualization sharing the 602 same kernel as the host).</para> 603 604 <para><varname>RootDirectory</varname> is the root directory of the container if it is known and 605 applicable or the empty string.</para> 606 607 <para><varname>NetworkInterfaces</varname> contains an array of network interface indices that point 608 towards the container, the VM or the host. For details about this information see the description of 609 <function>CreateMachineWithNetwork()</function> above.</para> 610 611 <para><varname>State</varname> is the state of the machine and is one of <literal>opening</literal>, 612 <literal>running</literal>, or <literal>closing</literal>. Note that the state machine is not considered 613 part of the API and states might be removed or added without this being considered API breakage. 614 </para> 615 </refsect2> 616 </refsect1> 617 618 <refsect1> 619 <title>Examples</title> 620 621 <example> 622 <title>Introspect <interfacename>org.freedesktop.machine1.Manager</interfacename> on the bus</title> 623 624 <programlisting> 625$ gdbus introspect --system \ 626 --dest org.freedesktop.machine1 \ 627 --object-path /org/freedesktop/machine1 628 </programlisting> 629 </example> 630 631 <example> 632 <title>Introspect <interfacename>org.freedesktop.machine1.Machine</interfacename> on the bus</title> 633 634 <programlisting> 635$ gdbus introspect --system \ 636 --dest org.freedesktop.machine1 \ 637 --object-path /org/freedesktop/machine1/machine/rawhide 638 </programlisting> 639 </example> 640 </refsect1> 641 642 <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/> 643</refentry> 644