system/systemd
system/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd synced 2024-07-08 20:15:55 +00:00
Code Issues Projects Releases Wiki Activity

docs: add a new document describing the VM interface of systemd

Browse Source 
This mirrors the existing CONTAINER_INTERFACE.md document, but describes
extension points of systemd running in a VM with a machine manager
supervising it.
This commit is contained in:
Lennart Poettering 2024-03-13 10:33:26 +01:00
parent 83797ece91
commit 34c6b7d9de
2 changed files with 59 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
docs/VM_INTERFACE.md Normal file
View File

@ -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.

18
docs/WRITING_VM_AND_CONTAINER_MANAGERS.md
View File

@ -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).