= Architecture
:page-parent: About Spectrum

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

Spectrum is based on the principle of security by compartmentalization.

The default set of virtual machines includes some application VMs,
(names prefixed with _appvm-_); and a system VM, _netvm_ (which
handles hardware network devices and provides network services to
application VMs).  Refer to
xref:../using-spectrum/running-vms.adoc[Running VMs] and
xref:../using-spectrum/creating-custom-vms.adoc[Creating Custom VMs]
for more information about using VMs in Spectrum.

== Architecture Decision Records (ADRs)

https://en.wikipedia.org/wiki/Architectural_decision[Architecturally significant
decisions] are xref:../decisions/index.adoc[recorded] as lightweight
https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions[ADRs].

== Spectrum Host System

Compartmentalization is implemented using
https://cloudhypervisor.org/[cloud-hypervisor] virtual machines.
cloud-hypervisor uses Linux's
https://en.wikipedia.org/wiki/Kernel-based_Virtual_Machine[Kernel-based Virtual
Machine] (KVM) to provide lightweight, hardware-accelerated VMs.

While Linux (including KVM) is portable between many hardware architectures,
cloud-hypervisor supports only x86_64 and aarch64.
Spectrum currently only works on x86_64, but aarch64 support is in development.

https://skarnet.org/software/s6-rc/overview.html[s6-rc] is used for service
management.  Utilities like kmod, util-linux and busybox are installed for boot
and service scripts.

https://wayland.freedesktop.org/[Wayland] is used for window management and
display.  The Wayland architecture is well documented
https://wayland.freedesktop.org/architecture.html[here].
The host provides onlya Wayland terminal client,
https://codeberg.org/dnkl/foot/[foot], which is used for interacting with VM
consoles.
It is possible for application VMs to display windows on the single Wayland
compositor on the host system, using Wayland virtio-gpu contexts.  X11
applications may be usable, but the host does not provide any special
accommodations for them, so the guest must bridge them to Wayland.
By default this is done with
https://github.com/talex5/wayland-proxy-virtwl[wayland-proxy-virtwl].

All host user space components are built with the https://musl.libc.org/[musl C
library].
In comparison to other libc implementations, musl has
https://www.etalabs.net/compare_libcs.html[added safety on resource exhaustion
and security hardening on memory allocation].
Kernel hardening will be investigated in future.

== Spectrum Dependency Tree

For a detailed, interactive view of dependencies, use
https://github.com/utdemir/nix-tree[nix-tree] in the Spectrum repository:

[source,shell]
[listing]
nix-build img/live --no-out-link | xargs -o nix-tree

See the https://diode.zone/w/8DBDQ6HQUe5UUdLkpDuL35[video] of Spectrum live
image interactive analysis with nix-tree.

== Networking

The net-vm's purpose is running the Linux drivers for any physical
interfaces on the spectrum system.

A net-vm (there could be multiple, one per IOMMU-group) will load the
xdp-forwarder XDP programs on the passed-through physical interfaces as well
as the downstream virtio interface going into the router (recognized by
its special MAC address) using mdev events.

The net-vm needs to multiplex between the physical interfaces, as there
might be several interfaces in the same IOMMU-group.

For this, the xdp-forwarder applies a
VLAN tag corresponding to the interface id, and redirects the packets to
the router interface (identified by the router_iface bpf map).
In the other direction the XDP program loaded on the router interface
removes one layer of VLAN tagging, and redirects the packets to the
interface read from the VLAN tag.