= Architecture
// SPDX-FileCopyrightText: 2022 Ville Ilvonen <ville.ilvonen@unikie.com>
// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0

== Introduction

Spectrum operating system stack is based on the principle of security by compartmentalization. The high level system stack is illustrated in the following diagram.

image::diagrams/stack.svg[]

=== Kernel space

In the stack, kernel space security by compartmentalization is supported with linux kernel that includes kernel-based virtual machine (KVM) module enabling the kernel to work as virtual-machine manager, hypervisor. Kernel side hypervisor supports virtualization of hardware resources - computational cores, memory and devices - securely. Userspace virtual machine guests are managed with cloud-hypervisor. Linux with KVM also supports portability to several hardware architectures. Currently Spectrum is supported only on x86_64 but ARM64 is under works. In addition, hardened kernel is to be enabled.

=== Host user space

This section provides high level overview of host user space tools and libraries.

User space stack is build on musl standard C library with added safety on resource exhaustion and security hardening on memory allocation.

https://skarnet.org/software/s6-rc/overview.html[s6-rc] service manager is used for services. kmod, util-linux and busybox are provided for essential system administration.

https://github.com/cloud-hypervisor/cloud-hypervisor[cloud-hypervisor] is a host tooling for virtual machine management, written in Rust with a strong focus on security.

Wayland refers to whole display stack providing communication with compositor (weston) for desktop services, including libraries and drivers for direct rendering and event devices. Clients are implemented as application virtual machines (see next section). Minimal host provides only Wayland terminal client, foot. Wayland, a simpler and more secure, protocol for compositor could provide support for legacy X applications as well but as of now none are provided. https://wayland.freedesktop.org/architecture.html[Wayland architecture] is well documented here.

=== Application and system virtual machines

Security by compartmentalization in Spectrum is implemented with virtual machines. Virtual machines currently launch using terminal and support only wayland-console. Wayland graphics support for appvms is under work. Please refer to https://spectrum-os.org/doc/running-vms.html[running VMs] for more information.

Reference set of virtual machines includes system machine, netvm, and application VMs, appvm-catgirl and appvm-elinks. Please refer to https://spectrum-os.org/doc/creating-vms.html[creating VMs] for more information.

== Details of Spectrum dependency tree

High level overview of Spectrum stack is limited view to the system. For detailed, interactive view to dependencies please use `nix-tree` under the spectrum repository:

`nix-build img/live -I nixpkgs=https://spectrum-os.org/git/nixpkgs/snapshot/nixpkgs-rootfs.tar.gz --no-out-link | xargs -o nix-tree`

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