From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on atuin.qyliss.net X-Spam-Level: X-Spam-Status: No, score=-4.6 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, MAILING_LIST_MULTI,RCVD_IN_DNSWL_LOW,SPF_HELO_PASS, T_SCC_BODY_TEXT_LINE autolearn=unavailable autolearn_force=no version=3.4.6 Received: from atuin.qyliss.net (localhost [IPv6:::1]) by atuin.qyliss.net (Postfix) with ESMTP id 35D854177B; Fri, 3 Jun 2022 10:54:47 +0000 (UTC) Received: by atuin.qyliss.net (Postfix, from userid 496) id 89BAA41782; Fri, 3 Jun 2022 10:54:44 +0000 (UTC) Received: from wout3-smtp.messagingengine.com (wout3-smtp.messagingengine.com [64.147.123.19]) by atuin.qyliss.net (Postfix) with ESMTPS id F096041762 for ; Fri, 3 Jun 2022 10:54:39 +0000 (UTC) Received: from compute4.internal (compute4.nyi.internal [10.202.2.44]) by mailout.west.internal (Postfix) with ESMTP id 79B34320091F; Fri, 3 Jun 2022 06:54:34 -0400 (EDT) Received: from mailfrontend2 ([10.202.2.163]) by compute4.internal (MEProxy); Fri, 03 Jun 2022 06:54:34 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=alyssa.is; h=cc :cc:content-type:date:date:from:from:in-reply-to:in-reply-to :message-id:mime-version:references:reply-to:sender:subject :subject:to:to; s=fm3; t=1654253673; x=1654340073; bh=9SbH5KxV97 hYm+kgZS82MSZqrOiXftcQ+9LmC8EV8nE=; b=IraeBK5XMhovrWz/p3tmL+fMml SGb0K/hm6jg/ldC7ouCewPrI/HdgEEWh910Kxf9VIo8yz9gMxcPEP79h544MAV5f 0jgr09q8jJmYotiUv05RnuDoAxoK7Q7JU0kN4SY2S+I6xwF/s/wojQCWfMoWKt1Y 5tjTimOJ0YzjtWrRs8v367aobLwDemvCorQ23cFg/Ka7A4Xpvz86B8NW418ZZ4bx LDKnNUneX1ze+DDjngUxCzoAtxnp8zR/WMmYDKHWGgGpoaW21kP+5l/PkqYpy5Y1 gzIV6/1czvG1gVO94PVNURn9o/wHQbdAvOpd5qz4iBPqyGqd1klzGFM0+Plw== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:cc:content-type:date:date:feedback-id :feedback-id:from:from:in-reply-to:in-reply-to:message-id :mime-version:references:reply-to:sender:subject:subject:to:to :x-me-proxy:x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s= fm1; t=1654253673; x=1654340073; bh=9SbH5KxV97hYm+kgZS82MSZqrOiX ftcQ+9LmC8EV8nE=; b=PsgdWqow8st3h9423z+rvIi05YKIXDLJ8HtSlwLZebHD CrtUEWbXdYUKgBbsg3nJwXl/z+AkTKtVoXZhDxEnwpwwafELKDauhFruo3cu3YOP khOVNlfLkhk69XsH0fcBNDw5q56y06ugTbl+cgoWrtSlxSNTYIczA0jkxfEjzH+S nxMOdEiWFKe54AuuBq9ec4ioNPbJmB87n7+y4nus1m1tLBrHKXyPs3z7xuEkqZq5 4wPX0jOlBhSH/B1NeFZrCUvJRq/54rEdyuQrZZ/aRWB+foS9IId/S/EQ6iQdjKKG srHib94AJXTW+SrXc/76deruLsAtCJGbVuW+hgKn1g== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedvfedrleeigdefvdcutefuodetggdotefrodftvf curfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfghnecu uegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmdenuc fjughrpeffhffvvefukfhfgggtuggjsehgtderredttdejnecuhfhrohhmpeetlhihshhs rgcutfhoshhsuceohhhisegrlhihshhsrgdrihhsqeenucggtffrrghtthgvrhhnpedule ehkedthfehgeekteeugfdtleevgeeitdejteehgfdthfektddtgeevuefhteenucffohhm rghinhepughirghtrgigihhsrdhfrhdpshhkrghrnhgvthdrohhrghdpghhithhhuhgsrd gtohhmpdhfrhgvvgguvghskhhtohhprdhorhhgpdhsphgvtghtrhhumhdqohhsrdhorhhg pdguihhouggvrdiiohhnvgdpughrrgifrdhiohenucevlhhushhtvghrufhiiigvpedtne curfgrrhgrmhepmhgrihhlfhhrohhmpehqhihlihhsshesvghvvgdrqhihlhhishhsrdhn vght X-ME-Proxy: Feedback-ID: i12284293:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Fri, 3 Jun 2022 06:54:33 -0400 (EDT) Received: by eve.qyliss.net (Postfix, from userid 1000) id A47FF618; Fri, 3 Jun 2022 10:54:31 +0000 (UTC) Date: Fri, 3 Jun 2022 10:54:31 +0000 From: Alyssa Ross To: Ville Ilvonen Subject: Re: [PATCH] doc: architecture view with drawio to svg generation Message-ID: <20220603105431.vlqusi3qqfrttf7g@eve> References: <20220524135601.399868-1-ville.ilvonen@unikie.com> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="phb5sgucqqzubpfe" Content-Disposition: inline In-Reply-To: <20220524135601.399868-1-ville.ilvonen@unikie.com> Message-ID-Hash: YOF5DEH57NTNGCIETDVAYINY2URDET64 X-Message-ID-Hash: YOF5DEH57NTNGCIETDVAYINY2URDET64 X-MailFrom: qyliss@eve.qyliss.net X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-config-1; header-match-devel.spectrum-os.org-0; header-match-devel.spectrum-os.org-1; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header CC: devel@spectrum-os.org X-Mailman-Version: 3.3.5 Precedence: list List-Id: Patches and low-level development discussion Archived-At: List-Archive: List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: --phb5sgucqqzubpfe Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable 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 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= =2Eadoc > new file mode 100644 > index 0000000..2f89e68 > --- /dev/null > +++ b/Documentation/architecture.adoc > @@ -0,0 +1,39 @@ > +=3D Architecture I recently organised the documentation into sections as suggested by the Di=C3=A1taxis 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 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 > + > +=3D=3D Introduction > + > +Spectrum operating system stack is based on the principle of security by= compartmentalization. The high level system stack is illustrated in the fo= llowing diagram. Please wrap text in documentation at 70-80 characters =E2=80=94 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. > +=3D=3D=3D 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 - computation= al cores, memory and devices - securely. Userspace virtual machine guests a= re 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 enab= led. 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. > +=3D=3D=3D Host user space > + > +This section provides high level overview of host user space tools and l= ibraries. > + > +User space stack is build on musl standard C library with added safety o= n 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 essenti= al 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] i= s a host tooling for virtual machine management, written in Rust with a str= ong focus on security. > + > +Wayland refers to whole display stack providing communication with compo= sitor (weston) for desktop services, including libraries and drivers for di= rect rendering and event devices. Clients are implemented as application vi= rtual machines (see next section). Minimal host provides only Wayland termi= nal client, foot. Wayland, a simpler and more secure, protocol for composit= or could provide support for legacy X applications as well but as of now no= ne are provided. https://wayland.freedesktop.org/architecture.html[Wayland = architecture] is well documented here. > + > +=3D=3D=3D Application and system virtual machines > + > +Security by compartmentalization in Spectrum is implemented with virtual= machines. Virtual machines currently launch using terminal and support onl= y wayland-console. Wayland graphics support for appvms is under work. Pleas= e refer to https://spectrum-os.org/doc/running-vms.html[running VMs] for mo= re 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 ap= plication VMs, appvm-catgirl and appvm-elinks. Please refer to https://spec= trum-os.org/doc/creating-vms.html[creating VMs] for more information. > + > +=3D=3D 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=3Dhttps://spectrum-os.org/git/nixpkgs/sna= pshot/nixpkgs-rootfs.tar.gz --no-out-link | xargs -o nix-tree` > + > +https://diode.zone/w/8DBDQ6HQUe5UUdLkpDuL35[See video of Spectrum live i= mage 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 {} }: pkgs.callPackage ( > > -{ lib, runCommand, jekyll }: > +{ lib, runCommand, jekyll, drawio-headless }: > > runCommand "spectrum-docs" { > src =3D with lib; cleanSourceWith { > @@ -14,11 +14,13 @@ runCommand "spectrum-docs" { > !(hasSuffix ".nix" name); > }; > > - nativeBuildInputs =3D [ jekyll ]; > + nativeBuildInputs =3D [ jekyll drawio-headless ]; > > passthru =3D { inherit jekyll; }; > -} '' > +} > + '' > jekyll build --disable-disk-cache -b /doc -s $src -d $out > + drawio --recursive $out/diagrams/ --export -f svg $out/assets/images/ > '' > ) { > jekyll =3D 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 @@ > +7VrbcuI4EP0aqiYPTPkOPBIyJJtkdneSnUnmaUtggVWRLUeSueT= rV7JljC8ZHArjhZoXbLdal+5z1FJLdMyRv7qmIPS+EhfijqG5q4551TEMXdcM8ZCStZJohp1I5h= S5SpYJHtEbTBWVNEIuZDlFTgjmKMwLpyQI4JTnZIBSssyrzQjO9xqCOSwJHqcAl6VPyOVeIu0bv= Ux+A9HcS3vWnUFS4oNUWVnCPOCS5ZbI/NIxR5QQnrz5qxHE0nupX57+WD/h+xfn+vYbewXfL+/+= +fNHN2ls/JEqGxMoDPjeTU+e7/r61e34/vvPt8Xz8hX2//qmqmgLgCPlr47hYNHJ5YyIvoS/wTQ= pcF4jaejlA5kQTrJv6Ri+xnklWbnLYi4MhYJhhKvtGs5cPm8AdZfCJqHwadV3LtKehQlJ54macv= 6mD4OSKHChtEoTxUsPcfgYJsNcChILmcd9LL70Te2drlMuXkDK4WqLOMqV15D4kNO1UFGlG36re= eFY6nuZkcx2lMzbIlgqA4rX803TGXbiRcH3ASj1FqG8R0G0io0Xthva3Y+vJw2m3W8bTKNFMKeY= RG7XW4eQLhAj9KSgNPt5KC2tDKWhHRNKswTlHaRBvMyy2D1FPwpLed5ZjFPyAkcECzDMq4AEUGK= JMC6IAEbzQHxOhVOhkF9KvyGxFg5VgY9cV3ZTiU4ePwn1GPgIS0cqciVStcZLFJJvEtG4HY9zsa= gbtuSWLXwmf6QC+zwnZI4hCBH7PCV+XDBlsep4lvQhXrNeGiNHYZoP7BI39KppbjbFDavEjRvC5= PSOmMDvN0FaJojVa5sgdovrgB8xMT4H+BL7YMLkoyu0R0XhuwtEIhYkDt4fhYI3Hsem4Y5hmlbM= OGVMXixV499adjAOAlfsNX8x7GSI+WE372CMJhRIkpzQ+lraKhltb5V6FVOk4DkYuEOZSmaBcMt= TtaPawaNYMVa6gHnxQD4OIHRzWXAZvm14KtBJZRRiwNEinztXQaZ6+JugeJak7HhnH522wGIfqk= rbuWqhHX2woyEO6BzyUkMxgTZW1+LUM354ewrGV7fL4XDQ5Xr47+T+IGnxR4LgzhDmdOl0R7xqI= HyUwkJdQtYOH5ZTDh+DhqJHJdLl3Xm7SC/BGovl6hywtmukYrp+TLDL2+12wZ5EbD0hq3MA29F2= T2y9d0ywD7F1PiTYM3lQHO9x48YmNC34JFIx/+IsSDDYPeP7x+SA8z/jwItPziK0m3Vmu3VMpAc= HQHpfVCOOcBcnR+Clye2jAPkAX5SLTgpxy6qBeFN5XyXiepsXHkwkILy78E8Kw9Lmu2pDdtQ1Wm= /zniOAPANwa8ayNVv4pz5fi1hvMvxtrKsyLd1uDOyqXOtsTmoKJzD7A3ikkxo7Rw9zMMi3UP+kZ= kdDDZ/U6IfI6faNIIgyhioiCAjD048gllYjglStFg1GkDavQ6DY4b2wc0Xb7u1Gu/LevEG0y9nb= A5xBYaa8E9UWiPII4LLffTD1UABZydG/702bYk/h3tTUayYHe9ybis/sL3fJKpL9c9H88h8=3D<= /diagram> > \ No newline at end of file > -- > 2.33.3 > > --phb5sgucqqzubpfe Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAABCAAdFiEEH9wgcxqlHM/ARR3h+dvtSFmyccAFAmKZ6E8ACgkQ+dvtSFmy ccA+CA/8DfaXd+cyFXZm0kAhN+XwOVzAfBp/soyJoVCKzIgKUzQbMI0KuFMc/vzE 4NMcyCImKSf1IjAgOFCdWpx+rFWVK3UqNG2wfUsQqGqLArpjXuR3dhwS/hNWdig3 yoBFuSWAphGf0eIjCw/mHWfYWX+trvPZifP56lYWx3ML8gtfVlugxi/Bn8fIocXg e4uD/lQiY1OcGoZP/oX/Th3EniC/sMby8OiBTvQNG4qkkltWn7A2kS2QCTdVAPdn gxIpmZmqXOOtgpcTBNRCZq95N/GXihQKecvMjcTFa12CsVyCD+pi1r0LSJNHT86E 3ykfsgJR685DVxWDNyE8WAOsPB1kMeAeYIBJmHc/p+KyEBNdWA/rsC9DCtFRuE11 oX8c4DxyKBLjxRNRNJL/OSrYN/2if9s77/kvvHjGVMa3puIl6CW2MhwIG+J2Zthx bugMtq19QfU4QTnEw+k9b5Ha3mCHFPkePcWO25v+AWFVhhxpd+J0yBdLYUHq3cV9 na9zDrRVAPsROyLFINWiyfwNxTHFwtCcXdPzVLqf5ILnTwHlORkD9Lkc3XcGANdj ZHwRfZcc9pq7u2/fxjwdW0+FoESkZ94AhWb4bx518hROxCA8aiUYErIznFqpSdGA EwoHRdgya4DLB4K72CtNRxIvLPVJKw74go18BpA7fnXkH2LoTx0= =vfe1 -----END PGP SIGNATURE----- --phb5sgucqqzubpfe--