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 2DEEC3158C; Tue, 7 Jun 2022 06:43:36 +0000 (UTC) Received: by atuin.qyliss.net (Postfix, from userid 496) id D2FAC3152E; Tue, 7 Jun 2022 06:43:32 +0000 (UTC) Received: from mail-ej1-x629.google.com (mail-ej1-x629.google.com [IPv6:2a00:1450:4864:20::629]) by atuin.qyliss.net (Postfix) with ESMTPS id DE23731576 for ; Tue, 7 Jun 2022 06:43:28 +0000 (UTC) Received: by mail-ej1-x629.google.com with SMTP id q1so33169794ejz.9 for ; Mon, 06 Jun 2022 23:43:28 -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:in-reply-to:references :mime-version:content-transfer-encoding; bh=XUyk/j8nfeEt0Zu7pSOLaOzd2QuGy/mjAaBpfe32I70=; b=mUXJMcJc5Mq55RQDQkYBa4CAIlvrwp919qGAbikZDFUooXoTRtzVd/U+cYelyTjLG0 O4uVdm/0DlBYYuwwbyBtF1rPV3icJ80FcH7pOzsPB48bGzK8fvVJaBfbBScrm/WjD6HJ MNTsCnOX/uLmMNabWHkvGaK1A9H25wnrqeG1YxPmXQeaBrl0i034O6yy2xs8mgck11mB MjwubvI2XADqy0622Br5OcTFrcbkF3Qd/yB6efqRpoh6W5ZllV/rhA7v89N6JSW90exC PpN34iMZOuVa2VZXBtH96tCetat67zT4f0eX8zUFZtu5xZaEz8f/oUn/MAE6Q4YLZcUf 38Lg== 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:in-reply-to :references:mime-version:content-transfer-encoding; bh=XUyk/j8nfeEt0Zu7pSOLaOzd2QuGy/mjAaBpfe32I70=; b=c/ir2BZZ6xfS/Im1H+h8vvVX26Aozv42c7LtTaM7FOE3O8iOeZLw9mvgTpJRbE97FO oOFkBZU1hWtsYvke/jhQcZPnM06Td1a4zz3c13LlNzyTwIVVqbLHX/7iabHj+alrP3FO 8lXzNi/8y6PPqZmE6Ep8ZHBX7GWt4Mn+3egT/eBQ0CR/NrY3ZqMdiGBu/f4dDlMtR0+A HDGndG+AK14kycTg3SAHp2W4LLEy99APYeAYb3IYMWyw0c59Ql2Nb6f6C8qd71pPQkC9 n9+tS7wjKtT/U0SucTZacldF+sTULhvpO9wkxyRlUBqlCZGoABm4VcZeV6dfyuZXOo+s uVFQ== X-Gm-Message-State: AOAM5309bQTYN3HoloBBerwX0Htq7aKzg87PGToM0mTc/47Xb5wkEhdQ LSA8B1FDpH1Exv/OuhOR0Xd5EJVdHhDLAw== X-Google-Smtp-Source: ABdhPJyJA6G5xU3Z6kFaBdXkHdqNTD0Sg2eT5qYFEicbpRzPwEpBS+fWAb2UHZ8MUNEOR6kmSoingg== X-Received: by 2002:a17:907:6e25:b0:711:c6ce:b7bc with SMTP id sd37-20020a1709076e2500b00711c6ceb7bcmr10896806ejc.752.1654584206106; Mon, 06 Jun 2022 23:43:26 -0700 (PDT) Received: from blop.ssrc.fi ([109.204.204.138]) by smtp.gmail.com with ESMTPSA id e1-20020a17090618e100b006f3ef214dc3sm7135722ejf.41.2022.06.06.23.43.25 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 06 Jun 2022 23:43:25 -0700 (PDT) From: Ville Ilvonen To: hi@alyssa.is Subject: [PATCH] doc: addressing architecture.adoc review changes Date: Tue, 7 Jun 2022 09:42:59 +0300 Message-Id: <20220607064259.588734-1-ville.ilvonen@unikie.com> X-Mailer: git-send-email 2.33.3 In-Reply-To: <20220603105431.vlqusi3qqfrttf7g@eve> References: <20220603105431.vlqusi3qqfrttf7g@eve> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Message-ID-Hash: DDXZEFEHI6HRTEGCSXR5KBWJEF4L2IRP X-Message-ID-Hash: DDXZEFEHI6HRTEGCSXR5KBWJEF4L2IRP 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: devel@spectrum-os.org, ville.ilvonen@unikie.com 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: * 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 --- 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.a= doc index 2f89e68..60b3baf 100644 --- a/Documentation/architecture.adoc +++ b/Documentation/architecture.adoc @@ -1,39 +1,76 @@ =3D Architecture -// SPDX-FileCopyrightText: 2022 Ville Ilvonen +:page-parent: Explanation + +// SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 =20 =3D=3D Introduction =20 -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. +Spectrum operating system stack is based on the principle of security by +compartmentalization. The high level system stack is illustrated in the +following diagram. =20 image::diagrams/stack.svg[] =20 =3D=3D=3D Kernel space =20 -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. +In the stack, kernel space security by compartmentalization is supported w= ith +linux kernel that includes kernel-based virtual machine (KVM) module enabl= ing +the kernel to work as virtual-machine manager, hypervisor. The kernel-side +hypervisor supports virtualization of hardware resources - computational c= ores, +memory and devices - securely. User space virtual machine guests are manag= ed +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. =20 =3D=3D=3D Host user space =20 -This section provides high level overview of host user space tools and lib= raries. +This section provides high level overview of host user space tools and +libraries. =20 -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 exhaus= tion +and security hardening on memory allocation]. =20 -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 syst= em +administration. =20 -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. +https://github.com/cloud-hypervisor/cloud-hypervisor[cloud-hypervisor] is = a host +tooling for virtual machine management, written in Rust with a strong focu= s on +security. =20 -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. +Wayland refers to whole display stack providing communication with composi= tor +(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 c= lient, +foot. Wayland, a simpler and more secure, protocol for compositor could pr= ovide +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. =20 =3D=3D=3D Application and system virtual machines =20 -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. +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. =20 -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. +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. =20 =3D=3D Details of Spectrum dependency tree =20 -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: +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: =20 -`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` +`nix-build img/live -I +nixpkgs=3Dhttps://spectrum-os.org/git/nixpkgs/snapshot/nixpkgs-rootfs.tar.= gz +--no-out-link | xargs -o nix-tree` =20 -https://diode.zone/w/8DBDQ6HQUe5UUdLkpDuL35[See video of Spectrum live ima= ge interactive analysis with nix-tree] \ No newline at end of file +https://diode.zone/w/8DBDQ6HQUe5UUdLkpDuL35[See video of Spectrum live ima= ge +interactive analysis with nix-tree] diff --git a/Documentation/diagrams/stack.drawio b/Documentation/diagrams/s= tack.drawio index 23feae7..bb42c1b 100644 --- a/Documentation/diagrams/stack.drawio +++ b/Documentation/diagrams/stack.drawio @@ -1 +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 +7Vpbc5s6EP41nmke3OFu+9Fx6uQk6WmbnDY5Tx0ZZNBEICIJX/Lrj= wTCGEOOnYwxtScvBlaLpN3v25UWuWOOwsUlBXHwlXgQdwzNW3TMi45h6LpmiIuULJVEM+xM4lPk= KVkhuEcvMFdU0gR5kJUUOSGYo7gsdEkUQZeXZIBSMi+rTQkujxoDH1YE9y7AVekD8niQSftGr5B= fQeQH+ci6M8haQpArK0tYADwyXxOZXzrmiBLCs7twMYJYei/3y8Nfywd8++RcXv9gz+Dn+c0/f/= /qZp2N3/LKygQKI/7uriePN3394np8+/Pfl9nj/Bn2v/1Qr2gzgBPlr47hYDHI+ZSIsYS/gZs1O= M+JNPT8jkwIJ8WzdAxf4rKSfLnLUi4MhYJhxIv1NxxfXq8A9ebCJqHwadF3zvKRhQnZ4Jmacv5q= DIOSJPKgtEoTzfMAcXgfZ9OcCxILWcBDLJ701dtbXadcPIOUw8UacZQrLyEJIadLoaJaV/xWceF= Y6nlekMx2lCxYI1guA4rX/qrrAjtxo+B7A5R6i1DeoihZpMYL2w3t5tfXowbT7rcNptEimC4mid= cNljGkM8QIPSoozX4ZSkurQmloh4TSrEB5A2mULrMsdc+mH4WlvOwsxil5giOCBRjmRUQiKLFEG= G+IAEZ+JB5d4VQo5OfSb0ishUPVECLPk8PUolPGT0I9BiHC0pGKXJlUrfESheyZJDTtJ+BcLOqG= LbllC5/JH6nAPvuE+BiCGLHPLgnTBpelquNpNoa4LUZpjBwbYT6wK9zQ68LcbIobVoUbV4TJ8E6= YwO+DIC0TxOq1TRC7xXUgTJiYnwNCiX00YfLSFdqjTeGrC0QmFiSOXp+Fgjedx6rjjmGaVso4ZU= xZLFXT353sYBxEnthr/s+0symWp928gzGaUCBJckTra2WrZLS9VerVhMiG52DkDWUpWSTCNU/tn= NX2nsU2c6UHWJBO5O0AQq9UBVfhW4enBp1cRiEGHM3KtXMdZGqE7wSlUZKz45V9dN4DS32oXlqv= VTf60QdbOuKA+pBXOkoJtLJ6J0494ruXh2h8cT0fDgddrse/J7d7KYvfkgS3pjCnS90t+eoo04f= lVNPHoKHsUYt0dXfeLtJzsMRiuToFrO0dSjFdPyTY1e12u2BPErackMUpgO1o2wNb7x0S7H1snf= cJ9lR+KE73uGlnE5o3fBKlWHh2EiQYbI/4/iE54PxhHHgKyUmkdnOXaLcOifRgD0i/F9WEI9zF2= SfwSnCHKEIhwGfVpqNC3LJ2QLypuq8Wcb3NAw8mChDenYVHhWFl8123ITvoGq23ec4RQV4AuBax= bMlm4bHH6ybWqwp/Heu6Sku3GwO7rtb6+FLT0pcau0QPczAo97D7l5otHTX8pUbfR0337pNSwH1= EcU0OAXF8/DnE0nbIIXXrRYM5pM0DEbyM6nZ4J4G13duOde25eYNYV6u3OziFwnJ5JqrNEOUJqA= m+ELgBiiCrOPrj3LQp9mycm5r6jsXBO85NxWPxl7tsFSn+uWh++Q8=3D \ No newline at end of file --=20 2.33.3