= Creating Custom VMs :page-parent: Using Spectrum // SPDX-FileCopyrightText: 2022, 2024 Alyssa Ross // 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])