dilim/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2026-08-12 12:16:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: fix misleading VM/machined documentation

Browse Source 
Fix two issues in WRITING_VM_AND_CONTAINER_MANAGERS.md:

1. The Host OS Integration section implied that -M switch and
   machinectl shell/login work for VMs, but they currently only
   work for containers. Add a note clarifying this limitation.

2. The Guest OS Integration section said "there's only one" VM
   integration API (SMBIOS Product UUID), but VM_INTERFACE.md
   documents five. Replace the outdated single-API description
   with a reference to VM_INTERFACE.md listing all five.

Fixes #40935

Co-developed-by: Claude Opus 4.6 <noreply@anthropic.com>
(cherry picked from commit adc4757b9e)
(cherry picked from commit 385dc8fb38)
This commit is contained in:
Kit Dallege
2026-03-27 00:18:52 +01:00
committed by Luca Boccassi
parent e84f389144
commit a256323c8e
1 changed files with 4 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/WRITING_VM_AND_CONTAINER_MANAGERS.md
View File

@@ -24,7 +24,8 @@ their own.
All virtual machines and containers should be registered with the [machined](https://www.freedesktop.org/software/systemd/man/latest/org.freedesktop.machine1) 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.
Note that the -M switch and interactive commands like "machinectl shell" and "machinectl login" currently only work for containers, not for VMs.
For VMs, registration with machined still provides process attribution, cgroup placement, and visibility in tools like ps and systemctl.
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.
@@ -34,7 +35,5 @@ For more details on the APIs provided by machine consult [the bus API interface
As container virtualization is much less comprehensive, and the guest is less isolated from the host, there are a number of interfaces defined how the container manager can set up the environment for systemd running inside a container. These Interfaces are documented in [Container Interface of systemd](/CONTAINER_INTERFACE).
VM virtualization is more comprehensive and fewer integration APIs are available.
In fact there's only one: a VM manager may initialize the SMBIOS DMI field "Product UUUID" to a UUID uniquely identifying this virtual machine instance.
This is read in the guest via `/sys/class/dmi/id/product_uuid`, and used as configuration source for `/etc/machine-id` if in the guest, if that file is not initialized yet.
Note that this is currently only supported for kvm hosts, but may be extended to other managers as well.
VM virtualization is more comprehensive and fewer integration APIs are available compared to containers.
See [The VM Interface](/VM_INTERFACE) for the full list of integration points, which includes system credentials via SMBIOS Type 11 vendor strings, readiness notification via `AF_VSOCK`, SSH access via `AF_VSOCK`, machine ID initialization from SMBIOS Product UUID, and kernel command line extension.