| <?xml version='1.0'?> |
| <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" > |
| <!-- SPDX-License-Identifier: LGPL-2.1+ --> |
| |
| <refentry id="org.freedesktop.machine1" conditional='ENABLE_MACHINED' |
| xmlns:xi="http://www.w3.org/2001/XInclude"> |
| <refentryinfo> |
| <title>org.freedesktop.machine1</title> |
| <productname>systemd</productname> |
| </refentryinfo> |
| |
| <refmeta> |
| <refentrytitle>org.freedesktop.machine1</refentrytitle> |
| <manvolnum>5</manvolnum> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>org.freedesktop.machine1</refname> |
| <refpurpose>The D-Bus interface of systemd-machined</refpurpose> |
| </refnamediv> |
| |
| <refsect1> |
| <title>Introduction</title> |
| |
| <para> |
| <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> |
| is a system service that keeps track of locally running virtual machines and containers. |
| This page describes the D-Bus interface.</para> |
| </refsect1> |
| |
| <refsect1> |
| <title>The Manager Object</title> |
| |
| <para>The service exposes the following interfaces on the Manager object on the bus:</para> |
| |
| <programlisting executable="systemd-machined" node="/org/freedesktop/machine1" interface="org.freedesktop.machine1.Manager"> |
| node /org/freedesktop/machine1 { |
| interface org.freedesktop.machine1.Manager { |
| methods: |
| GetMachine(in s name, |
| out o machine); |
| GetImage(in s name, |
| out o image); |
| GetMachineByPID(in u pid, |
| out o machine); |
| ListMachines(out a(ssso) machines); |
| ListImages(out a(ssbttto) images); |
| CreateMachine(in s name, |
| in ay id, |
| in s service, |
| in s class, |
| in u leader, |
| in s root_directory, |
| in a(sv) scope_properties, |
| out o path); |
| CreateMachineWithNetwork(in s name, |
| in ay id, |
| in s service, |
| in s class, |
| in u leader, |
| in s root_directory, |
| in ai ifindices, |
| in a(sv) scope_properties, |
| out o path); |
| RegisterMachine(in s name, |
| in ay id, |
| in s service, |
| in s class, |
| in u leader, |
| in s root_directory, |
| out o path); |
| RegisterMachineWithNetwork(in s name, |
| in ay id, |
| in s service, |
| in s class, |
| in u leader, |
| in s root_directory, |
| in ai ifindices, |
| out o path); |
| UnregisterMachine(in s name); |
| TerminateMachine(in s id); |
| KillMachine(in s name, |
| in s who, |
| in i signal); |
| GetMachineAddresses(in s name, |
| out a(iay) addresses); |
| GetMachineOSRelease(in s name, |
| out a{ss} fields); |
| OpenMachinePTY(in s name, |
| out h pty, |
| out s pty_path); |
| OpenMachineLogin(in s name, |
| out h pty, |
| out s pty_path); |
| OpenMachineShell(in s name, |
| in s user, |
| in s path, |
| in as args, |
| in as environment, |
| out h pty, |
| out s pty_path); |
| BindMountMachine(in s name, |
| in s source, |
| in s destination, |
| in b read_only, |
| in b mkdir); |
| CopyFromMachine(in s name, |
| in s source, |
| in s destination); |
| CopyToMachine(in s name, |
| in s source, |
| in s destination); |
| OpenMachineRootDirectory(in s name, |
| out h fd); |
| GetMachineUIDShift(in s name, |
| out u shift); |
| RemoveImage(in s name); |
| RenameImage(in s name, |
| in s new_name); |
| CloneImage(in s name, |
| in s new_name, |
| in b read_only); |
| MarkImageReadOnly(in s name, |
| in b read_only); |
| GetImageHostname(in s name, |
| out s hostname); |
| GetImageMachineID(in s name, |
| out ay id); |
| GetImageMachineInfo(in s name, |
| out a{ss} machine_info); |
| GetImageOSRelease(in s name, |
| out a{ss} os_release); |
| SetPoolLimit(in t size); |
| SetImageLimit(in s name, |
| in t size); |
| CleanPool(in s mode, |
| out a(st) images); |
| MapFromMachineUser(in s name, |
| in u uid_inner, |
| out u uid_outer); |
| MapToMachineUser(in u uid_outer, |
| out s machine_name, |
| out o machine_path, |
| out u uid_inner); |
| MapFromMachineGroup(in s name, |
| in u gid_inner, |
| out u gid_outer); |
| MapToMachineGroup(in u gid_outer, |
| out s machine_name, |
| out o machine_path, |
| out u gid_inner); |
| signals: |
| MachineNew(s machine, |
| o path); |
| MachineRemoved(s machine, |
| o path); |
| properties: |
| @org.freedesktop.DBus.Property.EmitsChangedSignal("false") |
| readonly s PoolPath = '...'; |
| @org.freedesktop.DBus.Property.EmitsChangedSignal("false") |
| readonly t PoolUsage = ...; |
| @org.freedesktop.DBus.Property.EmitsChangedSignal("false") |
| readonly t PoolLimit = ...; |
| }; |
| interface org.freedesktop.DBus.Peer { ... }; |
| interface org.freedesktop.DBus.Introspectable { ... }; |
| interface org.freedesktop.DBus.Properties { ... }; |
| }; |
| </programlisting> |
| |
| <!--method UnregisterMachine is not documented!--> |
| |
| <!--method OpenMachineRootDirectory is not documented!--> |
| |
| <!--method GetMachineUIDShift is not documented!--> |
| |
| <!--method GetImageHostname is not documented!--> |
| |
| <!--method GetImageMachineID is not documented!--> |
| |
| <!--method GetImageMachineInfo is not documented!--> |
| |
| <!--method GetImageOSRelease is not documented!--> |
| |
| <!--method CleanPool is not documented!--> |
| |
| <!--Autogenerated cross-references for systemd.directives, do not edit--> |
| |
| <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.machine1.Manager"/> |
| |
| <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.machine1.Manager"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="GetMachine()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="GetImage()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="GetMachineByPID()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="ListMachines()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="ListImages()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="CreateMachine()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="CreateMachineWithNetwork()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="RegisterMachine()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="RegisterMachineWithNetwork()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="UnregisterMachine()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="TerminateMachine()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="KillMachine()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="GetMachineAddresses()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="GetMachineOSRelease()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="OpenMachinePTY()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="OpenMachineLogin()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="OpenMachineShell()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="BindMountMachine()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="CopyFromMachine()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="CopyToMachine()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="OpenMachineRootDirectory()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="GetMachineUIDShift()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="RemoveImage()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="RenameImage()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="CloneImage()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="MarkImageReadOnly()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="GetImageHostname()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="GetImageMachineID()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="GetImageMachineInfo()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="GetImageOSRelease()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="SetPoolLimit()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="SetImageLimit()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="CleanPool()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="MapFromMachineUser()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="MapToMachineUser()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="MapFromMachineGroup()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="MapToMachineGroup()"/> |
| |
| <variablelist class="dbus-signal" generated="True" extra-ref="MachineNew"/> |
| |
| <variablelist class="dbus-signal" generated="True" extra-ref="MachineRemoved"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="PoolPath"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="PoolUsage"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="PoolLimit"/> |
| |
| <!--End of Autogenerated section--> |
| |
| <refsect2> |
| <title>Methods</title> |
| |
| <para><function>GetMachine()</function> may be used to get the machine object path for the machine with |
| the specified name. Similarly, <function>GetMachineByPID()</function> gets the machine object the |
| specified PID belongs to if there is any.</para> |
| |
| <para><function>GetImage()</function> may be used to get the image object path of the image with the |
| specified name.</para> |
| |
| <para><function>ListMachines()</function> returns an array of all currently registered machines. The |
| structures in the array consist of the following fields: machine name, machine class, an identifier for |
| the service that registered the machine and the machine object path.</para> |
| |
| <para><function>ListImages()</function> returns an array of all currently known images. The |
| structures in the array consist of the following fields: image name, type, read-only flag, creation |
| time, modification time, current disk space, and image object path.</para> |
| |
| <para><function>CreateMachine()</function> may be used to register a new virtual machine or container |
| with <command>systemd-machined</command>, creating a scope unit for it. It accepts the following arguments: a |
| machine name chosen by the registrar, an optional UUID as a 32 byte array, a string that identifies the |
| service that registers the machine, a class string, the PID of the leader process of the machine, an |
| optional root directory of the container, and an array of additional properties to use for the scope |
| registration. The virtual machine name must be suitable as a hostname, and hence should follow the usual |
| DNS hostname rules, as well as the Linux hostname restrictions. Specifically, only 7 bit ASCII is |
| permitted, a maximum length of 64 characters is enforced, only characters from the set |
| <literal>a-zA-Z0-9-_.</literal> are allowed, the name may not begin with a dot, and it may not contain |
| two dots immediately following each other. Container and VM managers should ideally use the hostname |
| used internally in the machine for this parameter. This recommendation is made in order to make the |
| machine name naturally resolvable using |
| <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>. If |
| a container manager needs to embed characters outside of the indicated range, escaping is required, |
| possibly using <literal>_</literal> as the escape character. Another (somewhat natural) option would be |
| to utilize Internet IDNA encoding. The UUID is passed as a 32 byte array or, if no suitable UUID is |
| available, an empty array (zero length) or zeroed out array shall be passed. The UUID should identify |
| the virtual machine/container uniquely and should ideally be the same UUID that |
| <filename>/etc/machine-id</filename> in the VM/container is initialized from. The service string can be |
| free-form, but it is recommended to pass a short lowercase identifier like |
| <literal>systemd-nspawn</literal>, <literal>libvirt-lxc</literal> or similar. The class string should |
| be either <literal>container</literal> or <literal>vm</literal> indicating whether the machine to |
| register is of the respective class. The leader PID should be the host PID of the init process of the |
| container or the encapsulating process of the VM. If the root directory of the container is known and |
| available in the host's hierarchy, it should be passed. Otherwise, pass the empty string instead. Finally, the |
| scope properties are passed as array in the same way as to PID1's |
| <function>StartTransientUnit()</function> method. Calling this method will internally register a transient scope |
| unit for the calling client (utilizing the passed scope_properties) and move the leader PID into |
| it. The method returns an object path for the registered machine object that implements the |
| <interfacename>org.freedesktop.machine1.Machine</interfacename> interface (see below). Also see the |
| <ulink url="https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New Control Group |
| Interfaces</ulink> for details about scope units and how to alter resource control settings on the |
| created machine at runtime.</para> |
| |
| <para><function>RegisterMachine()</function> is similar to <function>CreateMachine()</function>. |
| However, it only registers a machine and does not create a scope unit for it. Instead, the caller's unit is |
| registered. We recommend to only use this method for container or VM managers that are run |
| multiple times, one instance for each container/VM they manage, and are invoked as system |
| services.</para> |
| |
| <para><function>CreateMachineWithNetwork()</function> and |
| <function>RegisterMachineWithNetwork()</function> are similar to <function>CreateMachine()</function> |
| and <function>RegisterMachine()</function> but take an extra argument: an array of network interface |
| indices that point towards the virtual machine or container. The interface indices should reference one |
| or more network interfaces on the host that can be used to communicate with the guest. Commonly, the |
| passed interface index refers to the host side of a "veth" link (in case of containers), a |
| "tun"/"tap" link (in case of VMs), or the host side of a bridge interface that bridges access to the |
| VM/container interfaces. Specifying this information is useful to enable support for link-local IPv6 |
| communication to the machines since the scope field of sockaddr_in6 can be initialized by the |
| specified ifindex. |
| <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry> |
| makes use of this information.</para> |
| |
| <para><function>KillMachine()</function> sends a UNIX signal to the machine's processes. As its arguments, it takes a |
| machine name (as originally passed to <function>CreateMachine()</function> or returned by |
| <function>ListMachines()</function>), an identifier that specifies what precisely to send the signal to (either |
| <literal>leader</literal> or <literal>all</literal>), and a numeric UNIX signal integer.</para> |
| |
| <para><function>TerminateMachine()</function> terminates a virtual machine, killing its processes. It |
| takes a machine name as its only argument.</para> |
| |
| <para><function>GetMachineAddresses()</function> retrieves the IP addresses of a container. This method |
| returns an array of pairs consisting of an address family specifier (<constant>AF_INET</constant> or |
| <constant>AF_INET6</constant>) and a byte array containing the addresses. This is only supported for |
| containers that make use of network namespacing.</para> |
| |
| <para><function>GetMachineOSRelease()</function> retrieves the OS release information of a |
| container. This method returns an array of key value pairs read from the |
| <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file in |
| the container and is useful to identify the operating system used in a container.</para> |
| |
| <para><function>OpenMachinePTY()</function> allocates a pseudo TTY in the container and returns a file |
| descriptor and its path. This is equivalent to transitioning into the container and invoking |
| <citerefentry project='man-pages'><refentrytitle>posix_openpt</refentrytitle><manvolnum>3</manvolnum></citerefentry>. |
| </para> |
| |
| <para><function>OpenMachineLogin()</function> allocates a pseudo TTY in the container and ensures that |
| a getty login prompt of the container is running on the other end. It returns the file descriptor of |
| the PTY and the PTY path. This is useful for acquiring a pty with a login prompt from the |
| container.</para> |
| |
| <para><function>OpenMachineShell()</function> allocates a pseudo TTY in the container, as the specified |
| user, and invokes the executable at the specified path with a list of arguments (starting from |
| argv[0]) and an environment block. It then returns the file descriptor of the PTY and the PTY |
| path.</para> |
| |
| <para><function>BindMountMachine()</function> bind mounts a file or directory from the host into the |
| container. Its arguments consist of a machine name, the source directory on the host, the destination directory in the |
| container, and two booleans, one indicating whether the bind mount shall be |
| read-only, the other indicating whether the destination mount point shall be created first, if it is |
| missing.</para> |
| |
| <para><function>CopyFromMachine()</function> copies files or directories from a container into the |
| host. It takes a container name, a source directory in the container and a destination directory on the |
| host as arguments. <function>CopyToMachine()</function> does the opposite and copies files from a source |
| directory on the host into a destination directory in the container.</para> |
| |
| <para><function>RemoveImage()</function> removes the image with the specified name.</para> |
| |
| <para><function>RenameImage()</function> renames the specified image.</para> |
| |
| <para><function>CloneImage()</function> clones the specified image under a new name. It also takes a |
| boolean argument indicating whether the resulting image shall be read-only or not.</para> |
| |
| <para><function>MarkImageReadOnly()</function> toggles the read-only flag of an image.</para> |
| |
| <para><function>SetPoolLimit()</function> sets an overall quota limit on the pool of images.</para> |
| |
| <para><function>SetImageLimit()</function> sets a per-image quota limit.</para> |
| |
| <para><function>MapFromMachineUser()</function>, <function>MapToMachineUser()</function>, |
| <function>MapFromMachineGroup()</function>, and <function>MapToMachineGroup()</function> may be used to map |
| UIDs/GIDs from the host user namespace to a container user namespace or vice versa.</para> |
| </refsect2> |
| |
| <refsect2> |
| <title>Signals</title> |
| |
| <para><function>MachineNew</function> and <function>MachineRemoved</function> are sent whenever a new |
| machine is registered or removed. These signals carry the machine name and the object path to the corresponding |
| <interfacename>org.freedesktop.machine1.Machine</interfacename> interface (see below).</para> |
| </refsect2> |
| |
| <refsect2> |
| <title>Properties</title> |
| |
| <para><varname>PoolPath</varname> specifies the file system path where images are written to.</para> |
| |
| <para><varname>PoolUsage</varname> specifies the current usage size of the image pool in bytes.</para> |
| |
| <para><varname>PoolLimit</varname> specifies the size limit of the image pool in bytes.</para> |
| </refsect2> |
| </refsect1> |
| |
| <refsect1> |
| <title>Machine Objects</title> |
| |
| <programlisting executable="systemd-machined" node="/org/freedesktop/machine1/machine/rawhide" interface="org.freedesktop.machine1.Machine"> |
| node /org/freedesktop/machine1/machine/rawhide { |
| interface org.freedesktop.machine1.Machine { |
| methods: |
| Terminate(); |
| Kill(in s who, |
| in i signal); |
| GetAddresses(out a(iay) addresses); |
| GetOSRelease(out a{ss} fields); |
| GetUIDShift(out u shift); |
| OpenPTY(out h pty, |
| out s pty_path); |
| OpenLogin(out h pty, |
| out s pty_path); |
| OpenShell(in s user, |
| in s path, |
| in as args, |
| in as environment, |
| out h pty, |
| out s pty_path); |
| BindMount(in s source, |
| in s destination, |
| in b read_only, |
| in b mkdir); |
| CopyFrom(in s source, |
| in s destination); |
| CopyTo(in s source, |
| in s destination); |
| OpenRootDirectory(out h fd); |
| properties: |
| @org.freedesktop.DBus.Property.EmitsChangedSignal("const") |
| readonly s Name = '...'; |
| @org.freedesktop.DBus.Property.EmitsChangedSignal("const") |
| readonly ay Id = [...]; |
| @org.freedesktop.DBus.Property.EmitsChangedSignal("const") |
| readonly t Timestamp = ...; |
| @org.freedesktop.DBus.Property.EmitsChangedSignal("const") |
| readonly t TimestampMonotonic = ...; |
| @org.freedesktop.DBus.Property.EmitsChangedSignal("const") |
| readonly s Service = '...'; |
| @org.freedesktop.DBus.Property.EmitsChangedSignal("const") |
| readonly s Unit = '...'; |
| @org.freedesktop.DBus.Property.EmitsChangedSignal("const") |
| readonly u Leader = ...; |
| @org.freedesktop.DBus.Property.EmitsChangedSignal("const") |
| readonly s Class = '...'; |
| @org.freedesktop.DBus.Property.EmitsChangedSignal("const") |
| readonly s RootDirectory = '...'; |
| @org.freedesktop.DBus.Property.EmitsChangedSignal("const") |
| readonly ai NetworkInterfaces = [...]; |
| @org.freedesktop.DBus.Property.EmitsChangedSignal("false") |
| readonly s State = '...'; |
| }; |
| interface org.freedesktop.DBus.Peer { ... }; |
| interface org.freedesktop.DBus.Introspectable { ... }; |
| interface org.freedesktop.DBus.Properties { ... }; |
| }; |
| </programlisting> |
| |
| <!--method GetUIDShift is not documented!--> |
| |
| <!--method OpenPTY is not documented!--> |
| |
| <!--method OpenLogin is not documented!--> |
| |
| <!--method OpenShell is not documented!--> |
| |
| <!--method BindMount is not documented!--> |
| |
| <!--method CopyFrom is not documented!--> |
| |
| <!--method CopyTo is not documented!--> |
| |
| <!--method OpenRootDirectory is not documented!--> |
| |
| <!--Autogenerated cross-references for systemd.directives, do not edit--> |
| |
| <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.machine1.Machine"/> |
| |
| <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.machine1.Machine"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="Terminate()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="Kill()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="GetAddresses()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="GetOSRelease()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="GetUIDShift()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="OpenPTY()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="OpenLogin()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="OpenShell()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="BindMount()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="CopyFrom()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="CopyTo()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="OpenRootDirectory()"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="Name"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="Id"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="Timestamp"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="TimestampMonotonic"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="Service"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="Unit"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="Leader"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="Class"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="RootDirectory"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="NetworkInterfaces"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="State"/> |
| |
| <!--End of Autogenerated section--> |
| |
| <refsect2> |
| <title>Methods</title> |
| |
| <para><function>Terminate()</function> and <function>Kill()</function> terminate/kill the machine. These methods |
| take the same arguments as <function>TerminateMachine()</function> and |
| <function>KillMachine()</function> on the Manager interface, respectively.</para> |
| |
| <para><function>GetAddresses()</function> and <function>GetOSRelease()</function> get the IP address and OS |
| release information from the machine. These methods take the same arguments as |
| <function>GetMachineAddresses()</function> and <function>GetMachineOSRelease()</function> of the |
| Manager interface, respectively.</para> |
| </refsect2> |
| |
| <refsect2> |
| <title>Properties</title> |
| |
| <para><varname>Name</varname> is the machine name as it was passed in during registration with |
| <function>CreateMachine()</function> on the manager object.</para> |
| |
| <para><varname>Id</varname> is the machine UUID.</para> |
| |
| <para><varname>Timestamp</varname> and <varname>TimestampMonotonic</varname> are the realtime and |
| monotonic timestamps when the virtual machines where created in microseconds since the epoch.</para> |
| |
| <para><varname>Service</varname> contains a short string identifying the registering service as passed |
| in during registration of the machine.</para> |
| |
| <para><varname>Unit</varname> is the systemd scope or service unit name for the machine.</para> |
| |
| <para><varname>Leader</varname> is the PID of the leader process of the machine.</para> |
| |
| <para><varname>Class</varname> is the class of the machine and is either the string "vm" (for real VMs |
| based on virtualized hardware) or "container" (for light-weight userspace virtualization sharing the |
| same kernel as the host).</para> |
| |
| <para><varname>RootDirectory</varname> is the root directory of the container if it is known and |
| applicable or the empty string.</para> |
| |
| <para><varname>NetworkInterfaces</varname> contains an array of network interface indices that point |
| towards the container, the VM or the host. For details about this information see the description of |
| <function>CreateMachineWithNetwork()</function> above.</para> |
| |
| <para><varname>State</varname> is the state of the machine and is one of <literal>opening</literal>, |
| <literal>running</literal>, or <literal>closing</literal>. Note that the state machine is not considered |
| part of the API and states might be removed or added without this being considered API breakage. |
| </para> |
| </refsect2> |
| </refsect1> |
| |
| <refsect1> |
| <title>Examples</title> |
| |
| <example> |
| <title>Introspect <interfacename>org.freedesktop.machine1.Manager</interfacename> on the bus</title> |
| |
| <programlisting> |
| $ gdbus introspect --system \ |
| --dest org.freedesktop.machine1 \ |
| --object-path /org/freedesktop/machine1 |
| </programlisting> |
| </example> |
| |
| <example> |
| <title>Introspect <interfacename>org.freedesktop.machine1.Machine</interfacename> on the bus</title> |
| |
| <programlisting> |
| $ gdbus introspect --system \ |
| --dest org.freedesktop.machine1 \ |
| --object-path /org/freedesktop/machine1/machine/rawhide |
| </programlisting> |
| </example> |
| </refsect1> |
| |
| <refsect1> |
| <title>Versioning</title> |
| |
| <para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html"> |
| the usual interface versioning guidelines</ulink>.</para> |
| </refsect1> |
| </refentry> |