picnoir
/
Systemd
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

man: import org.freedesktop.machine1(3) from the wiki 

The wiki was primarily describing the D-Bus API, but it also had a large
introduction to the daemon functionality. I moved that latter part into
the page that describes the daemon, and the API description into the new
page.

This is mostly a straighforward import. Apart from some required formatting
changes, I removed obvious repetitions, and made tiny grammar and typo fixes
where I noticed them. The goal is not to have a perfect text immediately.

<interfacename>org.foo.bar</interface> is used for interface names,
<function>function()</function> for methods, and <function>signal</function>
(no parentheses) for signal names. In D-Bus, signals are similar to methods,
and docbook doesn't have a nice tag for them.
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2020-04-07 21:22:13 +02:00
parent 4cb5fd0da8
commit de2efb75f7
3 changed files with 486 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

406
man/org.freedesktop.machine1.xml Normal file
View File

@ -0,0 +1,406 @@
<?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>
$ gdbus introspect --system \
--dest org.freedesktop.machine1 \
--object-path /org/freedesktop/machine1
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) machines);
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);
KillMachine(in s name,
in s who,
in s signal);
TerminateMachine(in s id);
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);
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);
SetPoolLimit(in t size);
SetImageLimit(in s name,
in t size);
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:
readonly s PoolPath = '/var/lib/machines';
readonly t PoolUsage = 18446744070652059648;
readonly t PoolLimit = 2160721920;
};
interface org.freedesktop.DBus.Properties {
};
interface org.freedesktop.DBus.Peer {
};
interface org.freedesktop.DBus.Introspectable {
};
};
</programlisting>
<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> get the machine object the
specified PID belongs to if there is any.</para>
<para><function>GetImage()</function> may be used to the the image object path for the image with the
specified name.</para>
<para><function>ListMachines()</function> returns an array with 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 with 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, 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. This takes as arguments: a
machine name chosen by the registrar, an optional UUID as 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 hostname, and hence should follow the usual
DNS hostname rules, as well as 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 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 one as
<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 use the empty string. Finally, the
scope properties are passed as array in the same way as to PID1's
<function>StartTransientUnit()</function>. This method call will internally register a transient scope
unit for the calling client (utilizing the passed scope_properties), and move the leader PID into
it. The call returns an object path for the registered machine object, implementing 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 only registers a machine, but does not create a scope unit for it. The caller's unit will be
registered instead. This call is only recommended to be used 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
indexes that point towards the virtual machine or container. The interface indexes 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), or 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. It takes a
machine name (as originally passed to <function>CreateMachine()</function> or returned by
<function>ListMachines()</function>). An identifier what precisely to send the signal to being either
<literal>leader</literal> or <literal>all</literal>, plus a numeric UNIX signal integer.</para>
<para><function>TerminateMachine()</function> terminates a virtual machine, killing its processes. It
takes a machine name as argument.</para>
<para><function>GetMachineAddresses()</function> retrieves the IP addresses of a container. This call
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 call 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><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 loging prompt of the container is running on the other end. It returns the file descriptor of
the PTY plus 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 an executable of 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 plus the PTY
path.</para>
<para><function>BindMountMachine()</function> bind mounts a file or directory from the host into the
container. Takes a machine name, the source directory on the host, and the destination directory in the
container as argument. Also takes 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. Takes a container name, a source directory in the container and a destination directory on the
host as argument. <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 by the specified name.</para>
<para><function>RenameImage()</function> renames the specified image to a new name.</para>
<para><function>CloneImage()</function> clones the specified image under a new name. Also takes a
boolean argument indicating whether the resuling 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>, <function>MapToMachineGroup()</function> may be used to map
UIDs/GIDs from the host user namespace to a container namespace or back.</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 plus the object path to the
<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>
$ gdbus introspect --system \
--dest org.freedesktop.machine1 \
--object-path /org/freedesktop/machine1/machine/rawhide
node /org/freedesktop/machine1/machine/fedora_2dtree {
interface org.freedesktop.machine1.Machine {
methods:
Terminate();
Kill(in s who,
in s signal);
GetAddresses(out a(iay) addresses);
GetOSRelease(out a{ss} fields);
signals:
properties:
readonly s Name = 'fedora-tree';
readonly ay Id = [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00];
readonly t Timestamp = 1374193370484284;
readonly t TimestampMonotonic = 128247251308;
readonly s Service = 'nspawn';
readonly s Unit = 'machine-fedora\\x2dtree.scope';
readonly u Leader = 30046;
readonly s Class = 'container';
readonly s RootDirectory = '/home/lennart/fedora-tree';
readonly ai NetworkInterfaces = [7];
readonly s State = 'running';
};
interface org.freedesktop.DBus.Properties {
};
interface org.freedesktop.DBus.Peer {
};
interface org.freedesktop.DBus.Introspectable {
};
};
</programlisting>
<refsect2>
<title>Methods</title>
<para><function>Terminate()</function> and <function>Kill()</function> terminate/kill the machine, and
take the same arguments as <function>TerminateMachine()</function> and
<function>KillMachine()</function> on the Manager interface.</para>
<para><function>GetAddresses()</function> and <function>GetOSRelease()</function> get IP address and OS
release information from the machine, and take the same arguments as
<function>GetMachineAddresses()</function> and <function>GetMachineOSRelease()</function> of the
Manager interface, described above.</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.</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 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 that is known and
applicable, or the empty string.</para>
<para><varname>NetworkInterfaces</varname> contains an array of network interface indexes that point
towards the container or 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 one of <literal>opening</literal>,
<literal>running</literal>, <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>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>

1
man/rules/meson.build
View File

@ -45,6 +45,7 @@ manpages = [
['nss-resolve', '8', ['libnss_resolve.so.2'], 'ENABLE_NSS_RESOLVE'],
['nss-systemd', '8', ['libnss_systemd.so.2'], 'ENABLE_NSS_SYSTEMD'],
['org.freedesktop.login1', '5', [], 'ENABLE_LOGIND'],
['org.freedesktop.machine1', '5', [], 'ENABLE_MACHINED'],
['os-release', '5', [], ''],
['pam_systemd', '8', [], 'HAVE_PAM'],
['pam_systemd_home', '8', [], 'ENABLE_PAM_HOME'],

91
man/systemd-machined.service.xml
View File

@ -29,24 +29,91 @@
<refsect1>
<title>Description</title>
<para><command>systemd-machined</command> is a system service that
keeps track of virtual machines and containers, and processes
belonging to them.</para>
<para><command>systemd-machined</command> is a system service that keeps track of locally running virtual
machines and containers.</para>
<para><command>systemd-machined</command> is useful for registering and keeping track of both OS
containers (containers that share the host kernel but run a full init system of their own and behave in
most regards like a full virtual operating system rather than just one virtualized app) and full virtual
machines (virtualized hardware running normal operating systems and possibly different kernels).</para>
<para><command>systemd-machined</command> should <emphasis>not</emphasis> be used for registering/keeping
track of application sandbox containers. A <emphasis>machine</emphasis> in the context of
<command>systemd-machined</command> is supposed to be an abstract term covering both OS containers and
full virtual machines, but not application sandboxes.</para>
<para>Machines registered with machined are exposed in various ways in the system. For example:
<itemizedlist>
<listitem><para>Tools like
<citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>
will show to which machine a specific process belongs in a column of
its own, and so will
<ulink url="https://help.gnome.org/users/gnome-system-monitor/">gnome-system-monitor</ulink> or
<citerefentry><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
</listitem>
<listitem><para>systemd's various tools
(<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, ...)
support the <option>-M</option> switch to operate on local containers instead of the host system.
</para></listitem>
<listitem><para><command>systemctl list-machines</command> will show the system state of all local
containers, connecting to the container's init system for that.</para></listitem>
<listitem><para>systemctl's <option>--recursive</option> switch has the effect of not only showing the
locally running services, but recursively the services of all registered containers.</para></listitem>
<listitem><para>The <command>machinectl</command> command provides access to a number of useful
operations on registered containers, such as introspecting them, rebooting, shutting them down, and
getting a login prompt on them.</para></listitem>
<listitem><para>The
<citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry> library
exposes the
<citerefentry><refentrytitle>sd_bus_open_system_container</refentrytitle><manvolnum>3</manvolnum></citerefentry>
call to connect to the system bus of any registered container.</para></listitem>
<listitem><para>The
<citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>
module makes sure all registered containers can be resolved via normal glibc
<citerefentry project='man-pages'><refentrytitle>gethostbyname</refentrytitle><manvolnum>3</manvolnum></citerefentry>
or
<citerefentry project='man-pages'><refentrytitle>getaddrinfo</refentrytitle><manvolnum>3</manvolnum></citerefentry>
calls.</para></listitem>
</itemizedlist></para>
<para>See
<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
for some examples on how to run containers with OS tools.</para>
<para>Use
<citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>
to make the names of local containers known to
<command>systemd-machined</command> locally resolvable as host
names.</para>
<para>If you are interested in writing a VM or container manager that makes use of machined, please have
look at <ulink url="https://www.freedesktop.org/wiki/Software/systemd/writing-vm-managers">Writing
Virtual Machine or Container Managers</ulink>. Also see the <ulink
url="https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New Control Group
Interfaces</ulink>.</para>
<para>See the
<ulink url="https://www.freedesktop.org/wiki/Software/systemd/machined">
machined D-Bus API Documentation</ulink> for information about the
APIs <filename>systemd-machined</filename> provides.</para>
<para>The daemon provides both a C library interface
(which is shared with <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>)
as well as a D-Bus interface.
The library interface may be used to introspect and watch the state of virtual machines/containers.
The bus interface provides the same but in addition may also be used to register or terminate
machines.
For more information please consult
<citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>
and
<citerefentry><refentrytitle>org.freedesktop.machine1</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
<para>A small companion daemon
<citerefentry><refentrytitle>systemd-importd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
is also available, which implements importing, exporting, and downloading of container and VM images.
</para>
</refsect1>
<refsect1>