[PATCH] doc: architecture view with drawio to svg generation
* 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> --- 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 +// 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] \ No newline at end of file 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
Any comments on this? We had some people joining the project and asking for "Are there any user guides / architecture description of SpectrumOS?" so I linked to this. Best, -Ville
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
* page-parent set * updated copyright sloppiness * hard wrapped to 80 characters * updated reference app vm names in the diagram * used proposed emphasis on kernel hardening (a topic which would warrant a doc of its' own) * added the missing definite article mentioned as an example (don't mind a native English speaker to spell/grammar check, though) * Linked to comparison of C/POSIX standard library implementations for Linux on musl arguments * updated wayland-console to virtio-console * used AsciiDoctor's xref * added missing newline in adoc Signed-off-by: Ville Ilvonen <ville.ilvonen@unikie.com> --- Documentation/architecture.adoc | 63 +++++++++++++++++++++++------ Documentation/diagrams/stack.drawio | 2 +- 2 files changed, 51 insertions(+), 14 deletions(-) diff --git a/Documentation/architecture.adoc b/Documentation/architecture.adoc index 2f89e68..60b3baf 100644 --- a/Documentation/architecture.adoc +++ b/Documentation/architecture.adoc @@ -1,39 +1,76 @@ = Architecture -// SPDX-FileCopyrightText: 2022 Ville Ilvonen <ville.ilvonen@unikie.com> +:page-parent: Explanation + +// SPDX-FileCopyrightText: 2022 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. +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. +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. The kernel-side +hypervisor supports virtualization of hardware resources - computational cores, +memory and devices - securely. User space 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 work. In addition, hardened kernel will be investigated. === Host user space -This section provides high level overview of host user space tools and libraries. +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. +User space stack is build on musl standard C library with +https://www.etalabs.net/compare_libcs.html[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://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. +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. +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. +Security by compartmentalization in Spectrum is implemented with virtual +machines. Virtual machines currently launch using terminal and support only +virtio-console. Wayland graphics support for appvms is under work. Please refer +to xref: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. +Reference set of virtual machines includes system machine, netvm, and +application VMs, appvm-catgirl and appvm-elinks. Please refer to +xref: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: +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` +`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 +https://diode.zone/w/8DBDQ6HQUe5UUdLkpDuL35[See video of Spectrum live image +interactive analysis with nix-tree] diff --git a/Documentation/diagrams/stack.drawio b/Documentation/diagrams/stack.drawio index 23feae7..bb42c1b 100644 --- a/Documentation/diagrams/stack.drawio +++ b/Documentation/diagrams/stack.drawio @@ -1 +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 +<mxfile host="Electron" modified="2022-06-07T05:42:17.682Z" 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="_9gN0vdoL1l32oJlLSGM" version="15.7.3" type="device"><diagram id="C5RBs43oDa-KdzZeNtuy" name="Page-1">7Vpbc5s6EP41nmke3OFu+9Fx6uQk6WmbnDY5Tx0ZZNBEICIJX/LrjwTCGEOOnYwxtScvBlaLpN3v25UWuWOOwsUlBXHwlXgQdwzNW3TMi45h6LpmiIuULJVEM+xM4lPkKVkhuEcvMFdU0gR5kJUUOSGYo7gsdEkUQZeXZIBSMi+rTQkujxoDH1YE9y7AVekD8niQSftGr5BfQeQH+ci6M8haQpArK0tYADwyXxOZXzrmiBLCs7twMYJYei/3y8Nfywd8++RcXv9gz+Dn+c0/f//qZp2N3/LKygQKI/7uriePN3394np8+/Pfl9nj/Bn2v/1Qr2gzgBPlr47hYDHI+ZSIsYS/gZs1OM+JNPT8jkwIJ8WzdAxf4rKSfLnLUi4MhYJhxIv1NxxfXq8A9ebCJqHwadF3zvKRhQnZ4Jmacv5qDIOSJPKgtEoTzfMAcXgfZ9OcCxILWcBDLJ701dtbXadcPIOUw8UacZQrLyEJIadLoaJaV/xWceFY6nlekMx2lCxYI1guA4rX/qrrAjtxo+B7A5R6i1DeoihZpMYL2w3t5tfXowbT7rcNptEimC4midcNljGkM8QIPSoozX4ZSkurQmloh4TSrEB5A2mULrMsdc+mH4WlvOwsxil5giOCBRjmRUQiKLFEGG+IAEZ+JB5d4VQo5OfSb0ishUPVECLPk8PUolPGT0I9BiHC0pGKXJlUrfESheyZJDTtJ+BcLOqGLbllC5/JH6nAPvuE+BiCGLHPLgnTBpelquNpNoa4LUZpjBwbYT6wK9zQ68LcbIobVoUbV4TJ8E6YwO+DIC0TxOq1TRC7xXUgTJiYnwNCiX00YfLSFdqjTeGrC0QmFiSOXp+Fgjedx6rjjmGaVso4ZUxZLFXT353sYBxEnthr/s+0symWp928gzGaUCBJckTra2WrZLS9VerVhMiG52DkDWUpWSTCNU/tnNX2nsU2c6UHWJBO5O0AQq9UBVfhW4enBp1cRiEGHM3KtXMdZGqE7wSlUZKz45V9dN4DS32oXlqvVTf60QdbOuKA+pBXOkoJtLJ6J0494ruXh2h8cT0fDgddrse/J7d7KYvfkgS3pjCnS90t+eoo04flVNPHoKHsUYt0dXfeLtJzsMRiuToFrO0dSjFdPyTY1e12u2BPErackMUpgO1o2wNb7x0S7H1snfcJ9lR+KE73uGlnE5o3fBKlWHh2EiQYbI/4/iE54PxhHHgKyUmkdnOXaLcOifRgD0i/F9WEI9zF2SfwSnCHKEIhwGfVpqNC3LJ2QLypuq8Wcb3NAw8mChDenYVHhWFl8123ITvoGq23ec4RQV4AuBaxbMlm4bHH6ybWqwp/Heu6Sku3GwO7rtb6+FLT0pcau0QPczAo97D7l5otHTX8pUbfR0337pNSwH1EcU0OAXF8/DnE0nbIIXXrRYM5pM0DEbyM6nZ4J4G13duOde25eYNYV6u3OziFwnJ5JqrNEOUJqAm+ELgBiiCrOPrj3LQp9mycm5r6jsXBO85NxWPxl7tsFSn+uWh++Q8=</diagram></mxfile> \ No newline at end of file -- 2.33.3
Hi, Thanks for the review comments and no worries with delay. People have their schedules. I was just following up on this contrib :-) I was quite not sure how you would have preferred the changes implemented - amended to the original patch or additional patch. I used additional patch. As hard line wrap destroys the diff in respect to the earlier patch I addressed your review comments in the patch comments and used git-send to add the patch. I don't mind amending the changes to the original patch either, just let me know. If there's different preferences, we could complement the contribution guidelines and include style guide. Thanks, -Ville
On Tue, Jun 07, 2022 at 06:52:00AM -0000, Ville Ilvonen wrote:
Hi,
Thanks for the review comments and no worries with delay. People have their schedules. I was just following up on this contrib :-)
Thanks! I'm ready to apply this patch. One small thing that needs to be addressed first: the diagram file is missing a license notice, so my `reuse lint` check fails. Is the same license as used for the documentation file itself (GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0) okay? No need to send a new patch just to add the license notice — I can add it when I apply the patch.
I was quite not sure how you would have preferred the changes implemented - amended to the original patch or additional patch. I used additional patch. As hard line wrap destroys the diff in respect to the earlier patch I addressed your review comments in the patch comments and used git-send to add the patch. I don't mind amending the changes to the original patch either, just let me know.
If there's different preferences, we could complement the contribution guidelines and include style guide.
Good idea. I'll write it up when I get the chance, but in short, the preferred way to do this is to send a new version of the whole patch, with "[PATCH v2]" at the start of the subject line (the -v2 argument to git format-patch or git send-email will do this), and to explain the changes from the previous version after the "---" line, just before the diffstat. (This is called the "timely commentary" section because it's stripped when the final version of the patch is applied by git.)
On Mon, Jun 13, 2022 at 1:11 AM Alyssa Ross <hi@alyssa.is> wrote:
Is the same license as used for the documentation file itself (GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0) okay?
Same is okay. Best, -Ville
This patch has been committed as 8f1702fde31cdb08edea8349b00641ef6b886fa6, which can be viewed online at https://spectrum-os.org/git/spectrum/commit/?id=8f1702fde31cdb08edea8349b006.... This is an automated message. Send comments/questions/requests to: Alyssa Ross <hi@alyssa.is>
On Tue, Jun 07, 2022 at 09:42:59AM +0300, Ville Ilvonen wrote:
* page-parent set * updated copyright sloppiness * hard wrapped to 80 characters * updated reference app vm names in the diagram * used proposed emphasis on kernel hardening (a topic which would warrant a doc of its' own) * added the missing definite article mentioned as an example (don't mind a native English speaker to spell/grammar check, though) * Linked to comparison of C/POSIX standard library implementations for Linux on musl arguments * updated wayland-console to virtio-console * used AsciiDoctor's xref * added missing newline in adoc
Signed-off-by: Ville Ilvonen <ville.ilvonen@unikie.com>
Thanks a lot Ville! It's great to have an overview like this in the documentation, and it was something that would have been really difficult for me to do because I'd have had trouble selecting the information that would be most important for somebody new to the system. I've just committed it, and I also made some changes that I think will help make the overview more understandable — really just moving some things around and rewording them a bit, the content is still the same. I've also linked it from the main documentation page so it'll be easy for people to find, since I think this will be one of the most important starting points for people in the documentation.
participants (3)
-
Alyssa Ross -
Alyssa Ross -
Ville Ilvonen