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