man/org.freedesktop.machine1.xml

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