= Creating Custom VMs

// SPDX-FileCopyrightText: 2022, 2024 Alyssa Ross <hi@alyssa.is>
// SPDX-FileCopyrightText: 2022 Unikie
// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0

== Configuration

Custom VMs can be configured on
xref:../development/persistent-storage.adoc[persistent storage].  VMs
configurations are directories under a dedicated parent directory, and
the name of each configuration directory determines the name of
the VM.  After mounting the persistent storage partition, the
configured VMs can be made available by running `vm-import user
/media/4e43cdc2-82b2-4d94-8a90-b6c6189312d2/vms
/media/4e43cdc2-82b2-4d94-8a90-b6c6189312d2/Spectrum/data/spectrum/storage`,
replacing /media/4e43cdc2-82b2-4d94-8a90-b6c6189312d2/vms with the
directory containing the VM definitions, and
/media/4e43cdc2-82b2-4d94-8a90-b6c6189312d2/Spectrum/data/spectrum/storage
with the directory where disk-backed directories for the VMs should be
created.

The directory can contain the following files:

vmlinux:: An uncompressed Linux kernel image for the VM to boot.
*Required.*

blk:: A directory containing disk images (with file names ending in
".img") that will be provided to the guest as a virtio-blk device.
Order is not guaranteed.  At least one image is *required*.

providers/net:: A directory containing a file named for each VM that
should provide networking to this VM.  The contents of these files are
ignored.

=== Example

A configuration directory for a VM called "appvm-lynx" dedicated to
the https://lynx.invisible-island.net[Lynx] web browser, set up to
have networking provided by a VM named "netvm" would look like this:

----
appvm-lynx
├── providers/
│   └── net/
│       └── netvm
├── blk/
│   └── root.img
└── vmlinux*
----

== Devices

The virtual devices described here are always created for Spectrum
VMs.  It's important for guests to recognize these devices and use
them in the intended way so that they integrate into the rest of the
system.

=== Logging

Every VM has a serial console that is connected to the host system's
logging infrastructure.  The console is write-only -- there will never
be any input to read from the console.

=== User interface

Every VM has a virtio-gpu device that provides only the cross-domain
context with a Wayland channel (no GPU acceleration).  This can be
used by the VM to display Wayland windows on the host.

A virtio-console device is also provided.  Typically this is used to
provide the user with a shell inside the guest.

=== Networking

The Spectrum host system can create network connections between VMs.
These take the form of virtio-net devices.  Guests must support the
VIRTIO_NET_F_MAC feature.

A guest can distinguish between virtual inter-guest network
connections and hardware network connections through the MAC address
of the corresponding network interface: guest network interfaces for
inter-guest networking have locally administered addresses (LAAs).

Connections to *network provider VMs* have the IP address to use
encoded in the client interface's MAC address.  The client guest
should configure an IPv4 address in `100.64.0.0/16`, where the final
two octets of the IP address are the final two octets of the
interface's MAC address.  For example, an application VM where a
network interface named `eth0` has the MAC address `02:00:00:00:A5:46`
should configure `eth0` with the IPv4 address `100.64.165.70` (because
`A5` in hexadecimal is `165` in decimal, and `46` in hexadecimal is
`70` in decimal).

=== Filesystem

Every VM has a virtio-fs device that exposes the /run/fs/_VM ID_
directory on the host, with the tag "host".  The VM cannot write
directly into that directory, but it's possible to create a
subdirectory on the host and bind mount a directory from a writeable
filesystem into it to provide the VM with access to shared storage.

=== VSOCK

Every VM has a virtio-vsock device for communication with host
services.

== XDG Desktop Portals

Spectrum provides an implementation of the XDG File chooser portal,
allowing the user to selectively grant the VM access to host files.
To use it, install
https://spectrum-os.org/git/spectrum/tree/tools/xdg-desktop-portal-spectrum[xdg-desktop-portal-spectrum]
and set the org.freedesktop.impl.portal.FileChooser interface to be
provided by the "spectrum" portal in
https://flatpak.github.io/xdg-desktop-portal/docs/portals.conf.html[portals.conf].
(https://spectrum-os.org/git/spectrum/tree/img/app/etc/xdg/xdg-desktop-portal/portals.conf[Example])
