diff options
Diffstat (limited to 'man/org.freedesktop.machine1.xml')
| -rw-r--r-- | man/org.freedesktop.machine1.xml | 687 |
1 files changed, 687 insertions, 0 deletions
diff --git a/man/org.freedesktop.machine1.xml b/man/org.freedesktop.machine1.xml new file mode 100644 index 0000000..1af77e0 --- /dev/null +++ b/man/org.freedesktop.machine1.xml @@ -0,0 +1,687 @@ +<?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-or-later --> + +<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); + @org.freedesktop.systemd1.Privileged("true") + 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); + @org.freedesktop.systemd1.Privileged("true") + 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); + @org.freedesktop.systemd1.Privileged("true") + RegisterMachine(in s name, + in ay id, + in s service, + in s class, + in u leader, + in s root_directory, + out o path); + @org.freedesktop.systemd1.Privileged("true") + 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); + @org.freedesktop.systemd1.Privileged("true") + 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); + CopyFromMachineWithFlags(in s name, + in s source, + in s destination, + in t flags); + CopyToMachineWithFlags(in s name, + in s source, + in s destination, + in t flags); + 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 CopyToMachineWithFlags 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="CopyFromMachineWithFlags()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="CopyToMachineWithFlags()"/> + + <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. + <function>CopyFromMachineWithFlags()</function> and <function>CopyToMachineWithFlags</function> do the same but take an additional flags argument.</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); + CopyFromWithFlags(in s source, + in s destination, + in t flags); + CopyToWithFlags(in s source, + in s destination, + in t flags); + 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 CopyFromWithFlags is not documented!--> + + <!--method CopyToWithFlags 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="CopyFromWithFlags()"/> + + <variablelist class="dbus-method" generated="True" extra-ref="CopyToWithFlags()"/> + + <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> + + <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/> + + <refsect1> + <title>History</title> + <refsect2> + <title>The Manager Object</title> + <para><function>CopyFromMachineWithFlags()</function> and + <function>CopyToMachineWithFlags()</function> were added in version 252.</para> + </refsect2> + <refsect2> + <title>Machine Objects</title> + <para><function>CopyFromWithFlags()</function> and + <function>CopyToWithFlags()</function> were added in version 252.</para> + </refsect2> + </refsect1> +</refentry> |