List and Inspect Machines via systemd-machined

Something spun up a container or VM on this host and you want to know what machined knows about it, without touching the guest. This guide uses the org.freedesktop.machine1 D-Bus interface to list registered machines, inspect one, and read its guest metadata, all read-only unless a step says otherwise. Allow about fifteen minutes.

You need a Linux host running systemd, the gdbus utility, and access to the system bus.

1. Check the installed contract

This follows the local org.freedesktop.machine1(5) page from systemd 255.4. It documents a D-Bus interface, not a config file or standalone command. The manager object lives at /org/freedesktop/machine1, served by the well-known name org.freedesktop.machine1.

$ dpkg-query -W -f='${Package} ${Version}\n' systemd
systemd 255.4-1ubuntu8.17
$ command -v gdbus
/usr/bin/gdbus

Your version and path may differ. Keep the version noted alongside any diagnostic record: the two flag-aware copy methods were added in systemd 252, and interface details vary between releases.

2. Confirm the service and bus are reachable

Check the service state first. This is an ordinary status query, no elevated privileges needed:

$ systemctl is-active systemd-machined.service
active

Then ask D-Bus to describe the manager object:

$ gdbus introspect --system \
    --dest org.freedesktop.machine1 \
    --object-path /org/freedesktop/machine1

You should see the org.freedesktop.machine1.Manager interface with methods such as ListMachines, GetMachine and GetMachineOSRelease, plus the manager properties PoolPath, PoolUsage and PoolLimit.

Checkpoint: if you get a bus connection error, stop here. Confirm you are on the host whose machines you want to inspect, and that the system D-Bus is running. Do not swap --system for a private session bus; that inspects a different service entirely.

3. List registered machines

Call the manager's read-only ListMachines method:

$ gdbus call --system \
    --dest org.freedesktop.machine1 \
    --object-path /org/freedesktop/machine1 \
    --method org.freedesktop.machine1.Manager.ListMachines

The result is an array of records: machine name, class, registering service, and object path. An empty array means machined currently knows about nothing registered; it does not prove no process, VM or container exists by some other management method.

Checkpoint: record the exact machine name and object path from this call before continuing. A path usually looks like /org/freedesktop/machine1/machine/NAME, but the returned path is the one to trust, not a guessed one.

4. Read one machine object's properties

Replace MACHINE_OBJECT_PATH with the path from step 3. The standard D-Bus Properties interface reads everything in one call:

$ gdbus call --system \
    --dest org.freedesktop.machine1 \
    --object-path MACHINE_OBJECT_PATH \
    --method org.freedesktop.DBus.Properties.GetAll \
    org.freedesktop.machine1.Machine

Look for Name, Class, Service, Unit, Leader, RootDirectory, NetworkInterfaces and State.

• Class is container for userspace virtualisation sharing the host kernel, or vm for a virtual machine.
• State is currently opening, running or closing, but the manpage explicitly treats those names as non-stable API. Do not build automation on the exact spelling.
• RootDirectory can be blank for a VM, or for a container registered without one. That is normal, not a fault.
• Leader is a host PID. Do not assume it means the same thing inside the guest.

5. Query guest operating-system data

For a container, ask machined for the key-value data from its os-release file. This call is read-only:

$ gdbus call --system \
    --dest org.freedesktop.machine1 \
    --object-path /org/freedesktop/machine1 \
    --method org.freedesktop.machine1.Manager.GetMachineOSRelease \
    MACHINE_NAME

The result is a string-to-string dictionary. Common keys include ID, NAME and VERSION_ID, but the contents belong to the guest and are not fixed by this interface. Copy the machine name exactly as ListMachines returned it: a wrong name, or an unsupported object, gets you a D-Bus error instead of metadata.

Addresses work the same way:

$ gdbus call --system \
    --dest org.freedesktop.machine1 \
    --object-path /org/freedesktop/machine1 \
    --method org.freedesktop.machine1.Manager.GetMachineAddresses \
    MACHINE_NAME

This returns address-family and byte-array pairs, and only works for containers using network namespaces. An empty result or an error is not licence to invent an address: go inspect the container's network setup separately instead.

6. Keep the mutating methods out of your diagnostics

Several registration and PTY operations are marked privileged in the interface. A failed call reporting an authorisation error is a boundary, not an invitation to rerun the whole investigation as root. Re-run only the operation that genuinely needs privilege, after checking its arguments; the discovery and property calls above should stay unprivileged throughout.

Common errors and how to read them

• Could not connect. Confirm systemctl is-active systemd-machined.service and the system bus. --system is required for this service.
• Unknown object path. Run ListMachines again. Machines can disappear between calls, so get a fresh path rather than editing an old one by hand.
• Unknown machine. Copy the name exactly, case and punctuation included. Registered machine names follow hostname-style restrictions.
• Unexpected fields. Check the local manpage and the introspection output for your installed version. The human-readable order of a dictionary is never an API guarantee.

No undo is needed for this workflow: every call so far only inspects machined's current state. If another operator has already started or stopped a guest, just repeat ListMachines and the property query rather than trusting an earlier capture.