Check and operate local containers with systemd-machined

By the end of this guide you will be able to confirm that systemd-machined is available, list the host and registered local machines, inspect one machine, and choose a safe next operation with machinectl. The examples use the systemd 255 interface shipped here as systemd-container version 255.4-1ubuntu8.17.

Allow about 10 minutes if you are only inspecting machines. Starting, stopping, logging into, or copying data to a container needs an identified machine owner and a little more care.

Before you start

You need a Linux host using systemd, the systemd-container package, and a shell account that can read the system manager. Some machinectl operations require root or other policy authorisation. The read-only checks below are ordinary commands; put sudo in front of a command only when its policy or error message requires it.

This service tracks OS containers and full virtual machines. It is not a registry for an application sandbox. A container in this guide has its own operating-system userspace and normally its own init system, while a VM has virtualised hardware and may use another kernel.

1. Confirm the installed version

Check both the package and the systemd build. Keeping the version beside your notes matters because command details and available operations can differ between systemd releases.

$ dpkg-query -W -f='${Package} ${Version}\n' systemd-container
systemd-container 255.4-1ubuntu8.17
$ systemd --version | head -1
systemd 255 (255.4-1ubuntu8.17)

If the package is missing, stop here and use the distribution's approved package process. Do not copy a binary from another host: the service also depends on the local system bus, kernel features, and systemd unit files.

2. Check the registration manager

Ask systemd for the service status without changing it:

$ systemctl status systemd-machined.service --no-pager

A healthy result contains Loaded: loaded and Active: active (running). On this installation the unit is static, so it is not enabled in the usual boot-target sense. It is normally available through its D-Bus service name, org.freedesktop.machine1, and may also be started when needed.

The unit is deliberately restricted: its local file shows NoNewPrivileges=yes, a system-call filter, and no network address access. Those settings protect the manager; they do not turn an untrusted container into a security boundary. Treat the guest image and every account inside it as separate security concerns.

$ journalctl -u systemd-machined.service -b --no-pager -n 50

Do not use systemctl restart as a first troubleshooting step on a host running containers. A restart can interrupt registration and active management operations. Fix the reported cause, then schedule any service disruption deliberately.

3. List the machines machined knows about

Use machinectl list for a human-friendly list of running containers and VMs:

$ machinectl list --no-legend --no-pager

An empty result means that no guest machine is currently listed by machinectl; it does not mean the host is absent. The command hides the special host entry by default. Add --all when you need that entry:

$ machinectl list --all --no-pager
MACHINE CLASS     SERVICE        OS     VERSION ADDRESSES
.host  host       -              Ubuntu 24.04 -

The exact OS and version columns depend on the host. A running guest normally has a machine name, a class such as container or vm, and the manager that owns it. A name is not necessarily an image name: an image is something that can be started, while a machine is a running instance.

You can obtain the same broad view from systemctl:

$ systemctl list-machines --no-pager
MACHINE          CLASS     SERVICE        OS     VERSION ADDRESSES
server.dixon.cx  host      -              Ubuntu 24.04 -

systemctl list-machines includes the host and local running containers. It is useful when you are already inspecting systemd units. machinectl list is the better starting point for machine operations.

4. Inspect one machine without changing it

Set a real name from the list, then ask for status. Replace the example value; do not leave the placeholder in a production command.

$ MACHINE_NAME=demo-container
$ machinectl status "$MACHINE_NAME" --no-pager

status is formatted for people and may include recent log data supplied by the container or VM manager. For scripts, use show, which returns properties and does not include the control-group tree or journal text:

$ machinectl show "$MACHINE_NAME" --no-pager
$ machinectl show "$MACHINE_NAME" --property=Name,Class,State,Leader

If the name is wrong, the command fails rather than selecting a similarly named machine. That is useful protection. Check spelling with machinectl list --all and quote the variable so shell expansion cannot alter it.

5. Choose an operation and understand its boundary

For a systemd-nspawn container with a matching image, machinectl start NAME starts an instantiated [email protected]. It is a state-changing, usually privileged operation. Confirm the image and maintenance window first:

$ machinectl list-images --no-pager
$ sudo machinectl start demo-container
$ machinectl list

To stop a systemd-compatible container cleanly, use machinectl poweroff NAME (also available as stop). This asks the container's init process to shut down. machinectl terminate NAME is different: it immediately kills the machine's processes and releases its resources. Treat it as a last resort because work in the guest can be lost.

For an interactive login, machinectl login NAME opens a login prompt and requires a getty from a systemd-based container. machinectl shell NAME invokes a process directly, but it does not propagate that process's exit status. For scripts that need an exit code, prefer systemd-run --machine=NAME --wait after checking its privilege requirements.

Do not confuse machinectl shell with systemctl -M NAME. The former runs a shell or command in a machine. The latter tells many systemd tools to operate on the machine's system manager. For example, this lists services inside a guest rather than on the host:

$ systemctl -M "$MACHINE_NAME" list-units --type=service --no-pager

6. Know what to do when a guest is missing

If a container is running but absent from the list, identify which container or VM manager launched it. Machined is an interface used by several managers, not just systemd-nspawn. A manager that has not registered its guest cannot be repaired by inventing a machinectl name.

If an image exists but no machine is running, use machinectl list-images to distinguish an available image from a running machine. Starting an image can create mounts, processes, networking, and persistent guest changes. Read the image manager's documentation and confirm the image path before using start.

For user-namespaced containers, machined can synthesise user and group records for the UIDs and GIDs in use. The host may therefore resolve a guest identity through the user database even when that identity is not a normal host account. Check the identity source before changing ownership or access controls.