Creating VMs
Configuration
Each VM is configured using a directory under svc/data/ on the user partition. The name of the directory determines the name of the VM.
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.
- shared-dirs
-
A directory whose subdirectories each describe a directory to be shared with a VM. The name of each subdirectory is used as the virtiofs tag, and the contents are as follows:
- dir
-
A symbolic link pointing to the directory to be shared with the VM. The directory must be on the user data partition. 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.
- wayland
-
An empty file, whose presence indicates that the host should set up a virtio-gpu device supporting the cross-domain context type, for the VM to send Wayland messages over.
Example
A configuration directory for a VM called "appvm-lynx" dedicated to the 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-console device to use to interact with the user of the Spectrum system.
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 the OUI 0A:B3:EC.
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 0A:B3:EC: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).