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=-3.9 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, MAILING_LIST_MULTI,RCVD_IN_DNSWL_NONE,SPF_HELO_NONE, 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 5A25B4AAF1; Tue, 24 May 2022 13:56:16 +0000 (UTC) Received: by atuin.qyliss.net (Postfix, from userid 496) id CEEEB4AB53; Tue, 24 May 2022 13:56:14 +0000 (UTC) Received: from mail-ej1-x62d.google.com (mail-ej1-x62d.google.com [IPv6:2a00:1450:4864:20::62d]) by atuin.qyliss.net (Postfix) with ESMTPS id BA2194AAE5 for ; Tue, 24 May 2022 13:56:10 +0000 (UTC) Received: by mail-ej1-x62d.google.com with SMTP id wh22so35382512ejb.7 for ; Tue, 24 May 2022 06:56:10 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=unikie.com; s=google; h=from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=gZLA5eBy4XhXhoRX12xOO/FIL11R5riXWmZLuD6Igt0=; b=i6tcGjhoore2zsKteIASVYV0oPxze4jkwlJQfCA+oqwVhTLO5a2L1j4hymMaHmjVdg UTi60OG+zA8O4Vwb2n0zr/6VJA0wKbMB3PB+XxM0TWIhcd+bxfahAxAZVO+PbWk8fnwj SEHL9IuAgIxDRiGxhCscFK0jfrpJnM+5SGlibIRgrdsuNgSw6yUWp++lRy34Zg5cXZap Dgy7ndierZJ2j/b/zVjF/LGYvRgmfcZ0yLiHJEn0KREJGC1XFsM9iqPHVxvzFM6J3opK 4eXEA2cpOD6l99X28QvBOEMBR0pUSxVLPWVSiwUEFFL6xy2Yxv0BriKIGjSwh+IJRYd+ IZfQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=gZLA5eBy4XhXhoRX12xOO/FIL11R5riXWmZLuD6Igt0=; b=bti2+S/vt/JJKoKUuDvwJmaY7jWSQu1FmKMnoHutObSKHkweWFOLBOtbNC0HJZdFfN AhtXOqcAZDEeOO/gI/v22op539mjtDf8Nnf6t5yAwQ0/7klgWmny8VnhKQiEi33uWnGp w3kC+dy2Sf3y704czNJPoLEC1LLJzuf5aUp3iXb1D2pQuWjSa06+pv4U/ScdHbdoU9T7 6EGont+gFMl9YyIBzJugAV6cyaAHhr+DF6YWNxLPHu4MmOfATFA2vJT0HTuOfYxBfCZe zLjITKgDTnlJjxQ0RimHAc7f59ghtr3glMYusYf9A+2sazY9vc1lP3HT/ac7ESx2k3SY FAcg== X-Gm-Message-State: AOAM531O1AHt0nFx5lOQhh6NiNz8wO+UChjGga3RziXjtCMArbBuLKKb HxunSMRQcl3N7QRjnThFmw5U5idhqnQwXA== X-Google-Smtp-Source: ABdhPJzNvA020j5243OWE1QdsAq5ZflmOFQvbvOcO4or2AFkI57kQitTIUcJebFoxBsJ8p8hjfZzEg== X-Received: by 2002:a17:907:3f15:b0:6fc:30f0:6561 with SMTP id hq21-20020a1709073f1500b006fc30f06561mr23765220ejc.691.1653400568424; Tue, 24 May 2022 06:56:08 -0700 (PDT) Received: from blop.ssrc.fi ([109.204.204.138]) by smtp.gmail.com with ESMTPSA id zm17-20020a170906995100b006fef0c7072esm1761718ejb.144.2022.05.24.06.56.07 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 24 May 2022 06:56:08 -0700 (PDT) From: Ville Ilvonen To: devel@spectrum-os.org Subject: [PATCH] doc: architecture view with drawio to svg generation Date: Tue, 24 May 2022 16:56:01 +0300 Message-Id: <20220524135601.399868-1-ville.ilvonen@unikie.com> X-Mailer: git-send-email 2.33.3 MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Message-ID-Hash: 2PRKZUC6HHB7SPMX6QZHEUAJ2IQXDHCC X-Message-ID-Hash: 2PRKZUC6HHB7SPMX6QZHEUAJ2IQXDHCC X-MailFrom: ville.ilvonen@unikie.com 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: Ville Ilvonen 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: * 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 --- 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.a= doc new file mode 100644 index 0000000..2f89e68 --- /dev/null +++ b/Documentation/architecture.adoc @@ -0,0 +1,39 @@ +=3D Architecture +// SPDX-FileCopyrightText: 2022 Ville Ilvonen +// 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 c= ompartmentalization. The high level system stack is illustrated in the foll= owing diagram. + +image::diagrams/stack.svg[] + +=3D=3D=3D Kernel space + +In the stack, kernel space security by compartmentalization is supported w= ith linux kernel that includes kernel-based virtual machine (KVM) module en= abling the kernel to work as virtual-machine manager, hypervisor. Kernel si= de 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 x8= 6_64 but ARM64 is under works. In addition, hardened kernel is to be enable= d. + +=3D=3D=3D Host user space + +This section provides high level overview of host user space tools and lib= raries. + +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 stron= g focus on security. + +Wayland refers to whole display stack providing communication with composi= tor (weston) for desktop services, including libraries and drivers for dire= ct rendering and event devices. Clients are implemented as application virt= ual machines (see next section). Minimal host provides only Wayland termina= l 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 ar= chitecture] is well documented here. + +=3D=3D=3D Application and system virtual machines + +Security by compartmentalization in Spectrum is implemented with virtual m= achines. 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 appl= ication VMs, appvm-catgirl and appvm-elinks. Please refer to https://spectr= um-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 d= etailed, interactive view to dependencies please use `nix-tree` under the s= pectrum repository: + +`nix-build img/live -I nixpkgs=3Dhttps://spectrum-os.org/git/nixpkgs/snaps= hot/nixpkgs-rootfs.tar.gz --no-out-link | xargs -o nix-tree` + +https://diode.zone/w/8DBDQ6HQUe5UUdLkpDuL35[See video of Spectrum live ima= ge 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 @@ =20 { pkgs ? import {} }: pkgs.callPackage ( =20 -{ lib, runCommand, jekyll }: +{ lib, runCommand, jekyll, drawio-headless }: =20 runCommand "spectrum-docs" { src =3D with lib; cleanSourceWith { @@ -14,11 +14,13 @@ runCommand "spectrum-docs" { !(hasSuffix ".nix" name); }; =20 - nativeBuildInputs =3D [ jekyll ]; + nativeBuildInputs =3D [ jekyll drawio-headless ]; =20 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/s= tack.drawio new file mode 100644 index 0000000..23feae7 --- /dev/null +++ b/Documentation/diagrams/stack.drawio @@ -0,0 +1 @@ +7VrbcuI4EP0aqiYPTPkOPBIyJJtkdneSnUnmaUtggVWRLUeSueTrV= 7JljC8ZHArjhZoXbLdal+5z1FJLdMyRv7qmIPS+EhfijqG5q4551TEMXdcM8ZCStZJohp1I5hS5= SpYJHtEbTBWVNEIuZDlFTgjmKMwLpyQI4JTnZIBSssyrzQjO9xqCOSwJHqcAl6VPyOVeIu0bvUx= +A9HcS3vWnUFS4oNUWVnCPOCS5ZbI/NIxR5QQnrz5qxHE0nupX57+WD/h+xfn+vYbewXfL+/++f= NHN2ls/JEqGxMoDPjeTU+e7/r61e34/vvPt8Xz8hX2//qmqmgLgCPlr47hYNHJ5YyIvoS/wTQpc= F4jaejlA5kQTrJv6Ri+xnklWbnLYi4MhYJhhKvtGs5cPm8AdZfCJqHwadV3LtKehQlJ54macv6m= D4OSKHChtEoTxUsPcfgYJsNcChILmcd9LL70Te2drlMuXkDK4WqLOMqV15D4kNO1UFGlG36reeF= Y6nuZkcx2lMzbIlgqA4rX803TGXbiRcH3ASj1FqG8R0G0io0Xthva3Y+vJw2m3W8bTKNFMKeYRG= 7XW4eQLhAj9KSgNPt5KC2tDKWhHRNKswTlHaRBvMyy2D1FPwpLed5ZjFPyAkcECzDMq4AEUGKJM= C6IAEbzQHxOhVOhkF9KvyGxFg5VgY9cV3ZTiU4ePwn1GPgIS0cqciVStcZLFJJvEtG4HY9zsagb= tuSWLXwmf6QC+zwnZI4hCBH7PCV+XDBlsep4lvQhXrNeGiNHYZoP7BI39KppbjbFDavEjRvC5PS= OmMDvN0FaJojVa5sgdovrgB8xMT4H+BL7YMLkoyu0R0XhuwtEIhYkDt4fhYI3Hsem4Y5hmlbMOG= VMXixV499adjAOAlfsNX8x7GSI+WE372CMJhRIkpzQ+lraKhltb5V6FVOk4DkYuEOZSmaBcMtTt= aPawaNYMVa6gHnxQD4OIHRzWXAZvm14KtBJZRRiwNEinztXQaZ6+JugeJak7HhnH522wGIfqkrb= uWqhHX2woyEO6BzyUkMxgTZW1+LUM354ewrGV7fL4XDQ5Xr47+T+IGnxR4LgzhDmdOl0R7xqIHy= UwkJdQtYOH5ZTDh+DhqJHJdLl3Xm7SC/BGovl6hywtmukYrp+TLDL2+12wZ5EbD0hq3MA29F2T2= y9d0ywD7F1PiTYM3lQHO9x48YmNC34JFIx/+IsSDDYPeP7x+SA8z/jwItPziK0m3Vmu3VMpAcHQ= HpfVCOOcBcnR+Clye2jAPkAX5SLTgpxy6qBeFN5XyXiepsXHkwkILy78E8Kw9Lmu2pDdtQ1Wm/z= niOAPANwa8ayNVv4pz5fi1hvMvxtrKsyLd1uDOyqXOtsTmoKJzD7A3ikkxo7Rw9zMMi3UP+kZkd= DDZ/U6IfI6faNIIgyhioiCAjD048gllYjglStFg1GkDavQ6DY4b2wc0Xb7u1Gu/LevEG0y9nbA5= xBYaa8E9UWiPII4LLffTD1UABZydG/702bYk/h3tTUayYHe9ybis/sL3fJKpL9c9H88h8=3D \ No newline at end of file --=20 2.33.3