ORG.FREEDESKTOP.MACHINE1(5)
✨ NAME ✨
ok so this is org.freedesktop.machine1, bestie — it's the D-Bus interface of systemd-machined, and yeah it lives in section 5 of the manual. 💅
🫶 INTRODUCTION 🫶
systemd-machined.service(8) is that girl — a system service whose whole job is keeping track of the virtual machines and containers running locally on your machine. She's the main character doing the bookkeeping. 📚✨
And this page? This page is all about the D-Bus interface. periodt.
👑 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);
CreateMachineEx(in s name,
in a(sv) properties,
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);
RegisterMachineEx(in s name,
in a(sv) properties,
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 { ... };
};ok that's a LOT of methods, but like... it's fine, we're gonna go through them. grab a snack. 🍓
🌸 Methods 🌸
GetMachine() — use this when you want the machine object path for the machine with the name you specify. And GetMachineByPID()? same vibe, but instead you hand it a PID and it gives you back the machine object that PID belongs to, if there is any. 🕵️♀️
GetImage() — this one gets you the image object path of the image with the specified name. easy. ✨
ListMachines() — returns an array of all the machines currently registered. Each struct in that array has these fields: the machine name, the machine class, an identifier for the service that registered the machine, and the machine object path. four little guys per entry. 🫶
ListImages() — returns an array of all the images currently known. Each struct has: image name, type, read-only flag, creation time, modification time, current disk space, and the image object path. 💖
CreateMachine() — okay bestie, this is the big one. Use it to register a brand new virtual machine or container with systemd-machined, and it creates a scope unit for it while it's at it. it takes these arguments:
- a machine name that the registrar picks,
- an optional UUID as a 32 byte array,
- a string identifying 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 extra properties to use for the scope registration.
Now the machine name — it has to be suitable as a hostname, so it should follow the usual DNS hostname rules AND 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. why? because of nss-mymachines(8) — this recommendation is made so the machine name is naturally resolvable using it. 🧚 If a container manager needs to embed characters outside of that 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 a 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's recommended to pass a short lowercase identifier like "systemd-nspawn", "libvirt-lxc" or similar. The class string should be either "container" or "vm" — that's telling it whether the machine you're registering 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 — though note that this is for informational purposes only, and will not be used otherwise. Otherwise, pass the empty string instead.
And finally, the scope properties are passed as an 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()</p> is basically CreateMachine()'s lowkey chill sibling 💅 — it only registers a machine and does not create a scope unit for it. Instead, the caller's own unit gets registered. And bestie, the recommended use case is very specific: only use this for container or VM managers that get run multiple times — one instance for each container/VM they manage — and that are invoked as system services. That's the vibe, don't fight it 🫶
RegisterMachineEx() and CreateMachineEx() are the glow-up versions of their counterparts: instead of a fixed number of parameters they take a series of key/value pairs (so future extensions can just slide in ✨), and for the leader parameter they take a PIDFD instead of a PID. The parameters currently supported are:
"Id"("ay") — the machine UUID."Service"("s") — the service string."Class"("s") — the class string."LeaderPIDFD"("h") — a PIDFD for the leader process of the machine. This one is optional. If you do specify it, it gets preferred over the combination of"LeaderPID"and"LeaderPIDFDID"👑"LeaderPID"("u") — a PID for the leader process of the machine. Optional. Must be specified together with"LeaderPIDFDID"."LeaderPIDFDID"("t") — a PIDFDID for the leader process of the machine. Optional. Must be specified together with"LeaderPID"."RootDirectory"("s") — the root directory of the container. Optional, and for informational purposes only (so like, aesthetic, not functional 💅)."NetworkInterfaces"("ai") — an array of network interface indices, exactly as inCreateMachineWithNetwork(). Optional.
CreateMachineWithNetwork()</p> and RegisterMachineWithNetwork()</p> are like CreateMachine() and RegisterMachine() but with one 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 interface index you pass refers to:
- the host side of a
"veth"link (when it's a container), - a
"tun"/"tap"link (when it's a VM), or - the host side of a bridge interface that bridges access to the VM/container interfaces.
Specifying this info is genuinely useful because it enables support for link-local IPv6 communication to the machines — the scope field of sockaddr_in6 can be initialized from the specified ifindex. And nss-mymachines(8) literally makes use of this information, so it's giving teamwork 🌈
KillMachine()</p> sends a UNIX signal to the machine's processes 🔥 As its arguments it takes:
- a machine name (as originally passed to
CreateMachine()or returned byListMachines()), - an identifier saying what precisely to send the signal to — either
"leader"or"all", - and a numeric UNIX signal integer.
TerminateMachine()</p> terminates a virtual machine, killing its processes 💀 It takes a machine name as its only argument. Periodt.
GetMachineAddresses()</p> retrieves the IP addresses of a container. This method returns an array of pairs — an address family specifier (AF_INET or AF_INET6) plus a byte array containing the addresses. This is only supported for containers that make use of network namespacing, so heads up if yours doesn't 🫠
GetMachineSSHInfo()</p> retrieves the SSH information of a machine 🔐 It returns two strings: the SSH address, which you can use to tell SSH where to connect, and the path to the SSH private key required for the connection to actually succeed.
GetMachineOSRelease()</p> retrieves the OS release information of a container 🐧 It returns an array of key value pairs read from the os-release(5) file inside the container, which is super useful for identifying which operating system a container is running.
OpenMachinePTY()</p> allocates a pseudo TTY in the container and returns a file descriptor plus its path ✨ This is equivalent to transitioning into the container and invoking posix_openpt(3).
OpenMachineLogin()</p> allocates a pseudo TTY in the container and makes sure 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. Very handy if you want a pty with a login prompt from the container.
OpenMachineShell()</p> allocates a pseudo TTY in the container as the specified user, then 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()</p> bind mounts a file or directory from the host into the container 🦋 Its arguments are: a machine name, the source directory on the host, the destination directory in the container, and two booleans — one saying whether the bind mount shall be read-only, the other saying whether the destination mount point shall be created first if it's missing.
CopyFromMachine()</p> 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()</p> does the opposite and copies files from a source directory on the host into a destination directory in the container. And CopyFromMachineWithFlags()</p> and CopyToMachineWithFlags()</p> do the same thing but take an additional flags argument 🌸
RemoveImage()</p> removes the image with the specified name. Bye bestie 👋
RenameImage()</p> renames the specified image.
CloneImage()</p> 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()</p> toggles the read-only flag of an image 🔒
SetPoolLimit()</p> sets an overall quota limit on the pool of images.
SetImageLimit()</p> sets a per-image quota limit.
MapFromMachineUser()</p>, MapToMachineUser()</p>, MapFromMachineGroup()</p>, and MapToMachineGroup()</p> may be used to map UIDs/GIDs from the host user namespace to a container user namespace, or vice versa 🌈
🌟 Signals 🌟
MachineNew()</p> and MachineRemoved()</p> 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</p> — specifies the file system path where images are written to.PoolUsage</p> — specifies the current usage size of the image pool in bytes.PoolLimit</p> — specifies the size limit of the image pool in bytes.
🌈 MACHINE OBJECTS 🌈
okay bestie, so when you actually land on a single machine (not the manager), the object path looks like this — for example the one for a machine literally named rawhide:
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()andKill()— these are the ones that end a machine / kill a machine 💀. And ngl they take exactly the same arguments asTerminateMachine()andKillMachine()on the Manager interface, respectively. Same energy, smaller scope.GetAddresses(),GetSSHInfo()andGetOSRelease()— these pull the IP address, the SSH connection info, and the OS release info straight out of the machine 🫶. And yes, same deal: they take the same arguments asGetMachineAddresses(),GetMachineSSHInfo()andGetMachineOSRelease()of the Manager interface, respectively.
🎀 Properties 🎀
okay this is the part where every single field gets its moment, no skipping, periodt:
Name— the machine name, exactly as it was passed in when it got registered withCreateMachine()on the manager object.Id— the machine UUID.TimestampandTimestampMonotonic— the realtime and monotonic timestamps for when the virtual machines were created, in microseconds since the epoch ⏱️.Service— a short string identifying the registering service, as passed in during registration of the machine.Unit— the systemd scope or service unit name for the machine.Leader— the PID of the leader process of the machine. (Bestie, the leader process is the top-level process of the payload of the machine, i.e. for containers it's PID 1 inside the container, and for VMs it's the process encapsulating the VM. Its lifetime defines the lifetime of the machine. So like… it's the main character and when it's gone, everything's gone 👑.)LeaderPIDFDId— encodes the Linux pidfd inode ID of the leader process of the machine.Supervisor— 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. So it can dip and the machine's still fine 🙈.)SupervisorPIDFDId— encodes the Linux pidfd inode ID of the supervisor process of the machine.Class— the class of the machine, and it's either the string"vm"(for real VMs based on virtualized hardware) or"container"(for lightweight userspace virtualization sharing the same kernel as the host). Two options, both iconic 💅.RootDirectory— 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 ofCreateMachineWithNetwork()above.VSockCID— the VSOCK CID of the VM if it is known, orVMADDR_CID_ANYotherwise.SSHAddress— the address of the VM in a formatsshcan understand, if it is known, or the empty string.SSHPrivateKeyPath— the path to the SSH private key of the VM if it is known, or the empty string.State— the state of the machine, and it's 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. So don't you dare hardcode a dependency on it, fr fr 😭.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.
also, quick reminder since it's written right there in the node block: every single one of those properties exceptStateis tagged@org.freedesktop.DBus.Property.EmitsChangedSignal("const"), andStateis tagged@org.freedesktop.DBus.Property.EmitsChangedSignal("false"). The vibes are: most of these never change, andStatedoesn't announce itself. ✨
🌸 EXAMPLES 🌸
here's how you actually peek at all of this with your own eyeballs, no cap:
💖 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🦋 VERSIONING 🦋
These D-Bus interfaces follow the usual interface versioning guidelines[2]. (Yes the footnote, it's down at the bottom, go look 🫶.)
⭐ HISTORY ⭐
The Manager Object
CopyFromMachineWithFlags()andCopyToMachineWithFlags()were added in version 252.GetMachineSSHInfo()was added in version 256.
Machine Objects
CopyFromWithFlags()andCopyToWithFlags()were added in version 252.GetSSHInfo(),VSockCID,SSHAddress, andSSHPrivateKeyPathwere added in version 256.LeaderPIDFDId,Supervisor,SupervisorPIDFDId,Subgroup, andUIDwere added in version 258.CreateMachineEx(), andRegisterMachineEx()were added in version 259.
🌈 SEE ALSO 🌈
systemd(1), systemd-machined.service(8), machinectl(1)
🎀 NOTES 🎀
- New Control Group Interfaces —
https://systemd.io/CONTROL_GROUP_INTERFACE - the usual interface versioning guidelines —
https://0pointer.de/blog/projects/versioning-dbus.html
and that's the whole page bestie, you ate it 💅✨ this one ships as systemd 262.1, and it's the ORG.FREEDESKTOP.MACHINE1(5) page — go forth and introspect, the machines are literally waiting 🦋👑🫶
📦 where this page comes from
- arch rolling: systemd 262.1-1 · LGPL-2.1-or-later AND CC0-1.0 AND GPL-2.0-or-later AND MIT-0
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms