mirror of
https://github.com/systemd/systemd
synced 2024-09-06 16:56:43 +00:00
723 lines
33 KiB
XML
723 lines
33 KiB
XML
<?xml version='1.0'?>
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.5/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);
|
|
GetMachineSSHInfo(in s name,
|
|
out s ssh_address,
|
|
out s ssh_private_key_path);
|
|
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 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="GetMachineSSHInfo()"/>
|
|
|
|
<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://systemd.io/CONTROL_GROUP_INTERFACE">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>GetMachineSSHInfo()</function> retrieves the SSH information of a machine. This method
|
|
returns two strings, the SSH address which can be used to tell SSH where to connect, and the path
|
|
to the SSH private key required for the connection to succeed.</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);
|
|
GetSSHInfo(out s ssh_address,
|
|
out s ssh_private_key_path);
|
|
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("const")
|
|
readonly u VSockCID = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly s SSHAddress = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly s SSHPrivateKeyPath = '...';
|
|
@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="GetSSHInfo()"/>
|
|
|
|
<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="VSockCID"/>
|
|
|
|
<variablelist class="dbus-property" generated="True" extra-ref="SSHAddress"/>
|
|
|
|
<variablelist class="dbus-property" generated="True" extra-ref="SSHPrivateKeyPath"/>
|
|
|
|
<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>, <function>GetSSHInfo()</function> and <function>GetOSRelease()</function> get the IP address,
|
|
SSH connection and OS release information from the machine. These methods take the same arguments as
|
|
<function>GetMachineAddresses()</function>, <function>GetMachineSSHInfo()</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>VSockCID</varname> is the VSOCK CID of the VM if it is known, or
|
|
<constant>VMADDR_CID_ANY</constant> otherwise.</para>
|
|
|
|
<para><varname>SSHAddress</varname> is the address of the VM in a format <command>ssh</command> can understand
|
|
if it is known or the empty string.</para>
|
|
|
|
<para><varname>SSHPrivateKeyPath</varname> is the path to the SSH private key of the VM if it is known
|
|
or the empty string.</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>
|
|
<para><function>GetMachineSSHInfo()</function> was added in version 256.</para>
|
|
</refsect2>
|
|
<refsect2>
|
|
<title>Machine Objects</title>
|
|
<para><function>CopyFromWithFlags()</function> and
|
|
<function>CopyToWithFlags()</function> were added in version 252.</para>
|
|
<para><function>GetSSHInfo()</function>, <varname>VSockCID</varname>, <varname>SSHAddress</varname>
|
|
and <varname>SSHPrivateKeyPath</varname> were added in version 256.</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
</refentry>
|