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.

2 files changed, 59 insertions, 13 deletions

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