= Creating VMs
:page-parent: Using Spectrum
:page-nav_order: 1

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

== Configuration

Each VM is configured using a directory under svc/data/ on the
xref:../development/user-partition.adoc[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*.

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