Check and Operate Local Containers with systemd-machined

The wrong verb in machinectl can end a guest's work with no way back, so know what systemd-machined manages first. 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 systemd host with the systemd-container package installed and a shell account that can read the system manager.
• Some machinectl operations need 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, not an application sandbox registry. A container here 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 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 on demand.

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 a separate security concern.

$ 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 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, a machine is a running instance.

You can get the same broad view from systemctl:

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

systemctl list-machines includes the host and local running containers, and 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, which 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

• machinectl poweroff NAME (also stop) shuts down cleanly. It asks the container's init process to shut down.
• machinectl terminate NAME kills immediately. It releases the machine's resources right away; treat it as a last resort because work in the guest can be lost.
• machinectl login NAME opens an interactive login prompt and requires a getty from a systemd-based container.
• machinectl shell NAME invokes a process directly but 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, so 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.