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