Re: [PATCH] doc: architecture view with drawio to svg generation

Alyssa Ross
2022-06-03T10:54:47Z

[-- Attachment #1: Type: text/plain, Size: 9799 bytes --]

Hi Ville,

On Tue, May 24, 2022 at 04:56:01PM +0300, Ville Ilvonen wrote:
> * Initial architecture document view a view to high level
> stack of Spectrum.
> * Stack view is generated to svg from drawio using Alyssa's
> drawio-headless in nixpkgs-upstream. Cherry-picked to
> nixpkgs-spectrum for testing.
> * An example to analyze the details of Spectrum dependencies
> interactively is also provided.
>
> Signed-off-by: Ville Ilvonen <ville.ilvonen@unikie.com>

Sorry it's taken me so long to review this. I've been having trouble
keeping up between reviewing incoming contributions, trying to sort out
Jonne's issues building on M1 (which require a lot of intense Nixpkgs
work), answering questions, my own priorities for Spectrum, and my
travel plans. It's a lot to get used to all at once. :)

> ---
> Documentation/architecture.adoc | 39 +++++++++++++++++++++++++++++
> Documentation/default.nix | 8 +++---
> Documentation/diagrams/stack.drawio | 1 +
> 3 files changed, 45 insertions(+), 3 deletions(-)
> create mode 100644 Documentation/architecture.adoc
> create mode 100644 Documentation/diagrams/stack.drawio
>
> diff --git a/Documentation/architecture.adoc b/Documentation/architecture.adoc
> new file mode 100644
> index 0000000..2f89e68
> --- /dev/null
> +++ b/Documentation/architecture.adoc
> @@ -0,0 +1,39 @@
> += Architecture

I recently organised the documentation into sections as suggested by the
Diátaxis framework[1]. This document would be a good fit for the
"Explanation" section, so it should be marked with

:page-parent: Explanation

Just under the title.

[1]: https://diataxis.fr/

> +// SPDX-FileCopyrightText: 2022 Ville Ilvonen <ville.ilvonen@unikie.com>

Just checking, do you own the copyright, as you've indicated here, or
does Unikie?

> +// 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.

Please wrap text in documentation at 70-80 characters — it makes it
easier to review, because it allows attaching feedback to smaller ranges
of text.

> +image::diagrams/stack.svg[]

Once again, I really love this diagram. I think it does a great job at
explaining the stack. There's one small error though: the reference VMs
are for catgirl and lynx, not irssi and elinks.

> +=== 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.

This is also a good explanation. :)

I think it would be clearer to say "kernel hardening will be
investigated" than "hardened kernel is to be enabled", because kernel
hardening isn't something you can just turn on!

It also needs some small grammar fixes, e.g. it should be "*The*
kernel-side hypervisor". But I'm happy doing a quick pass over myself
looking for spelling/grammar fixes when we have a version of the patch
that's otherwise ready to apply.

> +=== 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.

Optional, but it would be cool to link to something explaining these
security features of Musl.

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

This makes it sound like manual system administration is required, which
ideally it won't be. The main reason kmod, util-linux, and busybox are
there is for boot and service startup scripts. But I'm not sure what a
better phrasing would be.

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

When you say "wayland-console", do you mean virtio-console, or something
else?

You can use AsciiDoctor's xref: syntax for linking to other
documentation pages, which means the links will also work e.g. if the
documentation is built locally. There should be examples in other
documentation pages.

> +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]
> \ No newline at end of file

(Minor) Text files should end with a trailing newline, per POSIX.
But this is also in the class of things I wouldn't reject a patch for on
their own and would just fix up myself. :)

> diff --git a/Documentation/default.nix b/Documentation/default.nix
> index 02b3c31..8b969d4 100644
> --- a/Documentation/default.nix
> +++ b/Documentation/default.nix
> @@ -3,7 +3,7 @@
>
> { pkgs ? import <nixpkgs> {} }: pkgs.callPackage (
>
> -{ lib, runCommand, jekyll }:
> +{ lib, runCommand, jekyll, drawio-headless }:
>
> runCommand "spectrum-docs" {
> src = with lib; cleanSourceWith {
> @@ -14,11 +14,13 @@ runCommand "spectrum-docs" {
> !(hasSuffix ".nix" name);
> };
>
> - nativeBuildInputs = [ jekyll ];
> + nativeBuildInputs = [ jekyll drawio-headless ];
>
> passthru = { inherit jekyll; };
> -} ''
> +}
> + ''
> jekyll build --disable-disk-cache -b /doc -s $src -d $out
> + drawio --recursive $out/diagrams/ --export -f svg $out/assets/images/
> ''
> ) {
> jekyll = import ./jekyll.nix { inherit pkgs; };
> diff --git a/Documentation/diagrams/stack.drawio b/Documentation/diagrams/stack.drawio
> new file mode 100644
> index 0000000..23feae7
> --- /dev/null
> +++ b/Documentation/diagrams/stack.drawio
> @@ -0,0 +1 @@
> +<mxfile host="Electron" modified="2022-05-24T12:19:30.186Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/15.7.3 Chrome/91.0.4472.164 Electron/13.6.1 Safari/537.36" etag="8D9FBMK4C5lWSHGzQpql" version="15.7.3" type="device"><diagram id="C5RBs43oDa-KdzZeNtuy" name="Page-1">7VrbcuI4EP0aqiYPTPkOPBIyJJtkdneSnUnmaUtggVWRLUeSueTrV7JljC8ZHArjhZoXbLdal+5z1FJLdMyRv7qmIPS+EhfijqG5q4551TEMXdcM8ZCStZJohp1I5hS5SpYJHtEbTBWVNEIuZDlFTgjmKMwLpyQI4JTnZIBSssyrzQjO9xqCOSwJHqcAl6VPyOVeIu0bvUx+A9HcS3vWnUFS4oNUWVnCPOCS5ZbI/NIxR5QQnrz5qxHE0nupX57+WD/h+xfn+vYbewXfL+/++fNHN2ls/JEqGxMoDPjeTU+e7/r61e34/vvPt8Xz8hX2//qmqmgLgCPlr47hYNHJ5YyIvoS/wTQpcF4jaejlA5kQTrJv6Ri+xnklWbnLYi4MhYJhhKvtGs5cPm8AdZfCJqHwadV3LtKehQlJ54macv6mD4OSKHChtEoTxUsPcfgYJsNcChILmcd9LL70Te2drlMuXkDK4WqLOMqV15D4kNO1UFGlG36reeFY6nuZkcx2lMzbIlgqA4rX803TGXbiRcH3ASj1FqG8R0G0io0Xthva3Y+vJw2m3W8bTKNFMKeYRG7XW4eQLhAj9KSgNPt5KC2tDKWhHRNKswTlHaRBvMyy2D1FPwpLed5ZjFPyAkcECzDMq4AEUGKJMC6IAEbzQHxOhVOhkF9KvyGxFg5VgY9cV3ZTiU4ePwn1GPgIS0cqciVStcZLFJJvEtG4HY9zsagbtuSWLXwmf6QC+zwnZI4hCBH7PCV+XDBlsep4lvQhXrNeGiNHYZoP7BI39KppbjbFDavEjRvC5PSOmMDvN0FaJojVa5sgdovrgB8xMT4H+BL7YMLkoyu0R0XhuwtEIhYkDt4fhYI3Hsem4Y5hmlbMOGVMXixV499adjAOAlfsNX8x7GSI+WE372CMJhRIkpzQ+lraKhltb5V6FVOk4DkYuEOZSmaBcMtTtaPawaNYMVa6gHnxQD4OIHRzWXAZvm14KtBJZRRiwNEinztXQaZ6+JugeJak7HhnH522wGIfqkrbuWqhHX2woyEO6BzyUkMxgTZW1+LUM354ewrGV7fL4XDQ5Xr47+T+IGnxR4LgzhDmdOl0R7xqIHyUwkJdQtYOH5ZTDh+DhqJHJdLl3Xm7SC/BGovl6hywtmukYrp+TLDL2+12wZ5EbD0hq3MA29F2T2y9d0ywD7F1PiTYM3lQHO9x48YmNC34JFIx/+IsSDDYPeP7x+SA8z/jwItPziK0m3Vmu3VMpAcHQHpfVCOOcBcnR+Clye2jAPkAX5SLTgpxy6qBeFN5XyXiepsXHkwkILy78E8Kw9Lmu2pDdtQ1Wm/zniOAPANwa8ayNVv4pz5fi1hvMvxtrKsyLd1uDOyqXOtsTmoKJzD7A3ikkxo7Rw9zMMi3UP+kZkdDDZ/U6IfI6faNIIgyhioiCAjD048gllYjglStFg1GkDavQ6DY4b2wc0Xb7u1Gu/LevEG0y9nbA5xBYaa8E9UWiPII4LLffTD1UABZydG/702bYk/h3tTUayYHe9ybis/sL3fJKpL9c9H88h8=</diagram></mxfile>
> \ No newline at end of file
> --
> 2.33.3
>
>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]