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-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">
  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       @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">
 441 node /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   <refsect1>
 643     <title>Versioning</title>
 644
 645     <para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html">
 646     the usual interface versioning guidelines</ulink>.</para>
 647   </refsect1>
 648 </refentry>