|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | INTRODUCTION | THE MANAGER OBJECT | MACHINE OBJECTS | EXAMPLES | VERSIONING | HISTORY | SEE ALSO | NOTES | COLOPHON |
|
|
|
ORG.FREED....MACHINE1(5) org.freedesktop.machine1ORG.FREED....MACHINE1(5)
org.freedesktop.machine1 - The D-Bus interface of systemd-machined
systemd-machined.service(8) is a system service that keeps track
of locally running virtual machines and containers. This page
describes the D-Bus interface.
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 whom,
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);
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 { ... };
};
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[1] for details about scope units
and how to alter resource control settings on the created machine
at runtime.
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.
GetMachineSSHInfo() 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.
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. CopyFromMachineWithFlags() and
CopyToMachineWithFlags() do the same but take an additional flags
argument.
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.
node /org/freedesktop/machine1/machine/rawhide {
interface org.freedesktop.machine1.Machine {
methods:
Terminate();
Kill(in s whom,
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 s Subgroup = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly u Leader = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t LeaderPIDFDId = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly u Supervisor = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t SupervisorPIDFDId = ...;
@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 = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly u UID = ...;
};
interface org.freedesktop.DBus.Peer { ... };
interface org.freedesktop.DBus.Introspectable { ... };
interface org.freedesktop.DBus.Properties { ... };
};
Methods
Terminate() and Kill() terminate/kill the machine. These methods
take the same arguments as TerminateMachine() and KillMachine() on
the Manager interface, respectively.
GetAddresses(), GetSSHInfo() and GetOSRelease() get the IP
address, SSH connection and OS release information from the
machine. These methods take the same arguments as
GetMachineAddresses(), GetMachineSSHInfo() and
GetMachineOSRelease() of the Manager interface, respectively.
Properties
Name is the machine name as it was passed in during registration
with CreateMachine() on the manager object.
Id is the machine UUID.
Timestamp and TimestampMonotonic are the realtime and monotonic
timestamps when the virtual machines where created in microseconds
since the epoch.
Service contains a short string identifying the registering
service as passed in during registration of the machine.
Unit is the systemd scope or service unit name for the machine.
Leader is the PID of the leader process of the machine. (The
leader process is the top-level process of the payload of the
machine, i.e. for containers PID 1 inside the container, and for
VMs the process encapsulating the VM. Its lifetime defines the
lifetime of the machine.)
LeaderPIDFDId encodes the Linux pidfd inode ID of the leader
process of the machine.
Supervisor is the PID of the supervisor process of the machine.
(The supervisor process is the process that manages the machine,
if there's a separate one for it. A supervisor process is not
always defined, and does not define the machine's lifetime.)
SupervisorPIDFDId encodes the Linux pidfd inode ID of the
supervisor process of the machine.
Class is the class of the machine and is either the string "vm"
(for real VMs based on virtualized hardware) or "container" (for
lightweight userspace virtualization sharing the same kernel as
the host).
RootDirectory is the root directory of the container if it is
known and applicable or the empty string.
NetworkInterfaces 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
CreateMachineWithNetwork() above.
VSockCID is the VSOCK CID of the VM if it is known, or
VMADDR_CID_ANY otherwise.
SSHAddress is the address of the VM in a format ssh can understand
if it is known or the empty string.
SSHPrivateKeyPath is the path to the SSH private key of the VM if
it is known or the empty string.
State is the state of the machine and is one of "opening",
"running", or "closing". 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.
Subgroup contains the sub-control-group path this machine's
processes reside in, relative to the specified unit's control
group.
UID contains the numeric UNIX UID of the user who registered the
machine.
Example 1. Introspect org.freedesktop.machine1.Manager on the bus
$ gdbus introspect --system \
--dest org.freedesktop.machine1 \
--object-path /org/freedesktop/machine1
Example 2. Introspect org.freedesktop.machine1.Machine on the bus
$ gdbus introspect --system \
--dest org.freedesktop.machine1 \
--object-path /org/freedesktop/machine1/machine/rawhide
These D-Bus interfaces follow the usual interface versioning
guidelines[2].
The Manager Object
CopyFromMachineWithFlags() and CopyToMachineWithFlags() were added
in version 252.
GetMachineSSHInfo() was added in version 256.
Machine Objects
CopyFromWithFlags() and CopyToWithFlags() were added in version
252.
GetSSHInfo(), VSockCID, SSHAddress, and SSHPrivateKeyPath were
added in version 256.
LeaderPIDFDId, Supervisor, SupervisorPIDFDId, Subgroup, and UID
were added in version 258.
systemd(1), systemd-machined.service(8), machinectl(1)
1. New Control Group Interfaces
https://systemd.io/CONTROL_GROUP_INTERFACE
2. the usual interface versioning guidelines
https://0pointer.de/blog/projects/versioning-dbus.html
This page is part of the systemd (systemd system and service
manager) project. Information about the project can be found at
⟨http://www.freedesktop.org/wiki/Software/systemd⟩. If you have a
bug report for this manual page, see
⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩.
This page was obtained from the project's upstream Git repository
⟨https://github.com/systemd/systemd.git⟩ on 2025-08-11. (At that
time, the date of the most recent commit that was found in the
repository was 2025-08-11.) If you discover any rendering
problems in this HTML version of the page, or you believe there is
a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
[email protected]
systemd 258~rc2 ORG.FREED....MACHINE1(5)
Pages that refer to this page: org.freedesktop.import1(5), systemd.directives(7), systemd.index(7), systemd-machined.service(8)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|