Inspect Containers and Virtual Machines through systemd-machined

You will use the installed org.freedesktop.machine1 D-Bus interface to discover machines registered with systemd-machined, inspect one machine object, and read guest metadata without changing its state. Allow about fifteen minutes. You need a Linux host running systemd, the gdbus utility, and access to the system bus. The commands are read-only unless a step says otherwise.

1. Check the installed contract

This guide follows the local org.freedesktop.machine1(5) page from systemd 255.4. The page documents the D-Bus interface, rather than a configuration file or a standalone command. Its manager object is 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 package version and path may differ. Keep the version beside any diagnostic record: the two flag-aware copy methods were added in systemd 252, and interface details can vary between releases.

2. Confirm that the service and bus are reachable

Check the service state first. This is an ordinary status query and normally needs no elevated privileges:

$ systemctl is-active systemd-machined.service
active

Now ask D-Bus to describe the manager object:

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

Successful output includes the org.freedesktop.machine1.Manager interface and methods such as ListMachines, GetMachine and GetMachineOSRelease. It also lists the manager properties PoolPath, PoolUsage and PoolLimit. If you see a bus connection error, stop here. Check that you are on the host whose machines you intend to inspect and that the system D-Bus is running. Do not switch to a private session bus by changing --system; that would inspect a different service context.

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 return value is an array of records. Each record contains a machine name, its class, the registering service, and the machine object path. An empty array means that machined currently knows about no registered machines; it does not prove that no process, VM or container exists by another management method.

Checkpoint: record the exact machine name and object path from this call before continuing. Do not guess a path from a hostname. A path usually looks like /org/freedesktop/machine1/machine/NAME, but the returned path is authoritative.

4. Read one machine object's properties

Replace MACHINE_OBJECT_PATH with the path returned above. The standard D-Bus Properties interface lets you read all properties 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. The class is container for userspace virtualisation sharing the host kernel, or vm for a virtual machine. The state is currently described as opening, running or closing, but the manpage explicitly treats those state names as non-stable API.

A blank RootDirectory can be correct for a VM or for a machine whose container root was not supplied when it was registered. Likewise, Leader is a host PID, not a PID that should be assumed to have the same meaning inside the guest.

5. Query guest operating-system data

For a container, ask machined for the key-value data read 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. If the name is wrong, or the object is not a supported container, D-Bus returns an error instead of useful metadata. Copy the machine name exactly as returned by ListMachines.

You can retrieve addresses in 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 is supported for containers using network namespaces. An empty result or an error is not a reason to invent an address: inspect the container's network setup separately.

6. Keep state-changing methods out of read-only diagnostics

The same manager interface exposes TerminateMachine, KillMachine, image removal, image renaming and other mutating operations. Terminating or killing a machine can stop workloads and lose unsaved data. Removing or changing an image can destroy or alter the basis for a guest. Do not paste those method names into a diagnostic command unless you have separately confirmed the target, impact and recovery plan.

Several registration and PTY operations are marked privileged in the interface. A failed call that reports an authorisation error is a boundary, not an invitation to run the entire investigation as root. Re-run only the specific operation that genuinely requires privilege, after checking its arguments. The discovery and property calls above should remain unprivileged.

7. Recover from the common errors

• Could not connect: confirm systemctl is-active systemd-machined.service and the system bus. The --system option is required for this service.
• Unknown object path: run ListMachines again. Machines can disappear between calls, so use a fresh path rather than editing one by hand.
• Unknown machine: copy the name exactly, including case and punctuation. Machine names follow hostname-style restrictions when registered.
• Unexpected fields: inspect the local manpage and the introspection output for the installed systemd version. Do not parse the human-readable order of a dictionary as an API guarantee.

No undo command is needed for this workflow: the calls only inspect machined's current state. If another operator has already started or stopped a guest, repeat ListMachines and the property query rather than relying on an earlier capture.