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