интерфейс D-Bus системы systemd-machined (The D-Bus interface of systemd-machined)
Объект менеджера (The manager object)
The service exposes the following interfaces on the Manager
object on the bus:
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 { ... };
};
Methods
GetMachine() may be used to get the machine object path for the
machine with the specified name. Similarly, GetMachineByPID()
gets the machine object the specified PID belongs to if there is
any.
GetImage() may be used to get the image object path of the image
with the specified name.
ListMachines() 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.
ListImages() 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.
CreateMachine() may be used to register a new virtual machine or
container with systemd-machined, 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 "a-zA-Z0-9-_." 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 nss-mymachines(8). If a container
manager needs to embed characters outside of the indicated range,
escaping is required, possibly using "_" 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 /etc/machine-id 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 "systemd-nspawn",
"libvirt-lxc" or similar. The class string should be either
"container" or "vm" 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
StartTransientUnit() 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 org.freedesktop.machine1.Machine interface
(see below). Also see the New Control Group Interfaces
RegisterMachine() is similar to CreateMachine(). 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.
CreateMachineWithNetwork() and RegisterMachineWithNetwork() are
similar to CreateMachine() and RegisterMachine() 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. nss-mymachines(8) makes use of this
information.
KillMachine() sends a UNIX signal to the machine's processes. As
its arguments, it takes a machine name (as originally passed to
CreateMachine() or returned by ListMachines()), an identifier
that specifies what precisely to send the signal to (either
"leader" or "all"), and a numeric UNIX signal integer.
TerminateMachine() terminates a virtual machine, killing its
processes. It takes a machine name as its only argument.
GetMachineAddresses() retrieves the IP addresses of a container.
This method returns an array of pairs consisting of an address
family specifier (AF_INET or AF_INET6) and a byte array
containing the addresses. This is only supported for containers
that make use of network namespacing.
GetMachineOSRelease() retrieves the OS release information of a
container. This method returns an array of key value pairs read
from the os-release(5) file in the container and is useful to
identify the operating system used in a container.
OpenMachinePTY() 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 posix_openpt(3).
OpenMachineLogin() 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.
OpenMachineShell() 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.
BindMountMachine() 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.
CopyFromMachine() 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. CopyToMachine() does the opposite and copies files
from a source directory on the host into a destination directory
in the container.
RemoveImage() removes the image with the specified name.
RenameImage() renames the specified image.
CloneImage() 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.
MarkImageReadOnly() toggles the read-only flag of an image.
SetPoolLimit() sets an overall quota limit on the pool of images.
SetImageLimit() sets a per-image quota limit.
MapFromMachineUser(), MapToMachineUser(), MapFromMachineGroup(),
and MapToMachineGroup() may be used to map UIDs/GIDs from the
host user namespace to a container user namespace or vice versa.
Signals
MachineNew and MachineRemoved are sent whenever a new machine is
registered or removed. These signals carry the machine name and
the object path to the corresponding
org.freedesktop.machine1.Machine interface (see below).
Properties
PoolPath specifies the file system path where images are written
to.
PoolUsage specifies the current usage size of the image pool in
bytes.
PoolLimit specifies the size limit of the image pool in bytes.
