From: Alyssa Ross <hi@alyssa.is>
To: Ville Ilvonen <ville.ilvonen@unikie.com>
Cc: devel@spectrum-os.org
Subject: Re: [PATCH] doc: architecture view with drawio to svg generation
Date: Fri, 3 Jun 2022 10:54:31 +0000 [thread overview]
Message-ID: <20220603105431.vlqusi3qqfrttf7g@eve> (raw)
In-Reply-To: <20220524135601.399868-1-ville.ilvonen@unikie.com>
[-- 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 --]
next prev parent reply other threads:[~2022-06-03 10:54 UTC|newest]
Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-05-24 13:56 Ville Ilvonen
2022-06-03 7:15 ` Ville Ilvonen
2022-06-03 10:54 ` Alyssa Ross [this message]
2022-06-07 6:42 ` [PATCH] doc: addressing architecture.adoc review changes Ville Ilvonen
2022-06-07 6:52 ` Ville Ilvonen
2022-06-12 22:11 ` Alyssa Ross
2022-06-14 9:37 ` Ville Ilvonen
2022-06-15 10:50 ` Alyssa Ross
2022-06-15 10:56 ` Alyssa Ross
[not found] <20220524125252.389606-1-ville.ilvonen@unikie.com>
2022-05-24 13:57 ` [PATCH] doc: architecture view with drawio to svg generation Ville Ilvonen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20220603105431.vlqusi3qqfrttf7g@eve \
--to=hi@alyssa.is \
--cc=devel@spectrum-os.org \
--cc=ville.ilvonen@unikie.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://spectrum-os.org/git/crosvm
https://spectrum-os.org/git/doc
https://spectrum-os.org/git/mktuntap
https://spectrum-os.org/git/nixpkgs
https://spectrum-os.org/git/spectrum
https://spectrum-os.org/git/ucspi-vsock
https://spectrum-os.org/git/www
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).