diff options
Diffstat (limited to 'Documentation/getting-started/creating-vms.adoc')
| -rw-r--r-- | Documentation/getting-started/creating-vms.adoc | 78 |
1 files changed, 78 insertions, 0 deletions
diff --git a/Documentation/getting-started/creating-vms.adoc b/Documentation/getting-started/creating-vms.adoc new file mode 100644 index 0000000..725316c --- /dev/null +++ b/Documentation/getting-started/creating-vms.adoc @@ -0,0 +1,78 @@ += Creating VMs +:page-parent: Getting Started +: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: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.* + +rootfs.ext4:: A disk image that will be provided to the guest as a +virtio-blk device. *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 +├── rootfs.ext4 +└── 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). |