From 34c6b7d9de64e357071005ec49e88d2354cc4e8a Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 13 Mar 2024 10:33:26 +0100 Subject: [PATCH] docs: add a new document describing the VM interface of systemd This mirrors the existing CONTAINER_INTERFACE.md document, but describes extension points of systemd running in a VM with a machine manager supervising it. --- docs/VM_INTERFACE.md | 54 +++++++++++++++++++++++ docs/WRITING_VM_AND_CONTAINER_MANAGERS.md | 18 +++----- 2 files changed, 59 insertions(+), 13 deletions(-) create mode 100644 docs/VM_INTERFACE.md diff --git a/docs/VM_INTERFACE.md b/docs/VM_INTERFACE.md new file mode 100644 index 0000000000..45a4c44075 --- /dev/null +++ b/docs/VM_INTERFACE.md @@ -0,0 +1,54 @@ +--- +title: VM Interface +category: Interfaces +layout: default +SPDX-License-Identifier: LGPL-2.1-or-later +--- + +# The VM Interface + +Also consult [Writing Virtual Machine or Container +Managers](https://systemd.io/WRITING_VM_AND_CONTAINER_MANAGERS). + +systemd has a number of interfaces for interacting with virtual machine +managers, when systemd is used inside of a VM. If you work on a VM manager, +please consider supporting the following interfaces. + +1. systemd supports passing immutable binary data blobs with limited size and + restricted access to services via the `ImportCredential=`, `LoadCredential=` + and `SetCredential=` settings. These credentials may be passed into a system + via SMBIOS Type 11 vendor strings, see + [systemd(1)](https://www.freedesktop.org/software/systemd/man/latest/systemd.html) + for details. This concept may be used to flexibily configure various facets + ot the guest system. See + [systemd.system-credentials(7)](https://www.freedesktop.org/software/systemd/man/latest/systemd.system-credentials.html) + for a list of system credentials implemented by various systemd components. + +2. Readiness, information about various system properties and functionality, as + well as progress of boot may be reported by systemd to a machine manager via + the `sd_notify()` protocol via `AF_VSOCK` sockets. The address of this + socket may be configured via the `vmm.notify_socket` system credential. See + [systemd(1)](https://www.freedesktop.org/software/systemd/man/latest/systemd.html). + +3. The + [systemd-ssh-generator(8)](https://www.freedesktop.org/software/systemd/man/latest/systemd-ssh-generator.html) + functionality will automatically bind SSH login functionality to `AF_VSOCK` + port 22, if the system runs in a VM. + +4. If not initialized yet the system's + [machine-id(5)](https://www.freedesktop.org/software/systemd/man/latest/machine-id.html) + is automatically set to the SMBIOS product UUID if available and invocation + in an VM environment is detected. + +5. The + [`systemd-boot(7)`](https://www.freedesktop.org/software/systemd/man/latest/systemd-boot.html) + and + [`systemd-stub(7)`](https://www.freedesktop.org/software/systemd/man/latest/systemd-stub.html) + components support two SMBIOS Type 11 vendor strings that may be used to + extend the kernel command line of booted Linux environments: + `io.systemd.stub.kernel-cmdline-extra=` and + `io.systemd.boot.kernel-cmdline-extra=`. + +Also see +[smbios-type-11(7)](https://www.freedesktop.org/software/systemd/man/latest/smbios-type-11.html) +for a list of supported SMBIOS Type 11 vendor strings. diff --git a/docs/WRITING_VM_AND_CONTAINER_MANAGERS.md b/docs/WRITING_VM_AND_CONTAINER_MANAGERS.md index e3cc2806f1..272261c573 100644 --- a/docs/WRITING_VM_AND_CONTAINER_MANAGERS.md +++ b/docs/WRITING_VM_AND_CONTAINER_MANAGERS.md @@ -47,16 +47,8 @@ documentation](https://www.freedesktop.org/software/systemd/man/latest/org.freed ## Guest OS Integration -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](https://systemd.io/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. +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](https://systemd.io/CONTAINER_INTERFACE) and [VM Interface of +systemd](https://systemd.io/VM_INTERFACE).