| title | category | layout | SPDX-License-Identifier |
|---|---|---|---|
Writing VM and Container Managers |
Documentation for Developers |
default |
LGPL-2.1-or-later |
Or: How to hook up your favorite VM or container manager with systemd
Nomenclature: a Virtual Machine shall refer to a system running on virtualized hardware consisting of a full OS with its own kernel. A Container shall refer to a system running on the same shared kernel of the host, but running a mostly complete OS with its own init system. Both kinds of virtualized systems shall collectively be called "machines".
systemd provides a number of integration points with virtual machine and container managers, such as libvirt, LXC or systemd-nspawn. On one hand there are integration points of the VM/container manager towards the host OS it is running on, and on the other there integration points for container managers towards the guest OS it is managing.
Note that this document does not cover lightweight containers for the purpose of application sandboxes, i.e. containers that do not run a init system of their own.
All virtual machines and containers should be registered with the systemd-machined(8) mini service that is part of systemd. This provides integration into the core OS at various points. For example, tools like ps, cgls, gnome-system-manager use this registration information to show machine information for running processes, as each of the VM's/container's processes can reliably attributed to a registered machine. The various systemd tools (like systemctl, journalctl, loginctl, systemd-run, ...) all support a -M switch that operates on machines registered with machined. "machinectl" may be used to execute operations on any such machine. When a machine is registered via machined its processes will automatically be placed in a systemd scope unit (that is located in the machines.slice slice) and thus appear in "systemctl" and similar commands. The scope unit name is based on the machine meta information passed to machined at registration.
For more details on the APIs provided by machine consult the bus API interface documentation.
A number of interfaces are defined that permit a machine or container manager to set provide integration points with the payload/guest system. These interfaces are documented in Container Interface of systemd and VM Interface of systemd.