deploy: 9d1a8fa

appendices/glossary.html

@@ -391,9 +391,13 @@ <h3 id="ghaf"><a class="header" href="#ghaf">Ghaf</a></h3>
 Source: <a href="https://connectwithnature.ae/knowledge-hub/ghaf-tree">https://connectwithnature.ae/knowledge-hub/ghaf-tree</a></p>
 <h3 id="cicd"><a class="header" href="#cicd">CI/CD</a></h3>
 <p><em>Continuous Integration and Continuous Delivery is a Ghaf software development lifecycle. Continuous Integration refers to regularly integrating code changes into a shared repository, where they are automatically tested and verified. Continuous Delivery—software is released in short iterations.</em></p>
-<blockquote>
+<div class="mdbook-alerts mdbook-alerts-note">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  note
+</p>
 <p>Currently, Continuous Deployment is not set up. Continuous Deployment—code is deployed to customers automatically.</p>
-</blockquote>
+</div>
 <h3 id="ssrc"><a class="header" href="#ssrc">SSRC</a></h3>
 <p><em>Secure Systems Research Center is a global center of excellence in the development of end-to-end security and resilience for cyber-physical and autonomous systems. SSRC is a part of TII.</em><br />
 Source: <a href="https://www.tii.ae/secure-systems">https://www.tii.ae/secure-systems</a></p>

architecture/adr/platform-bus-passthrough-support.html

@@ -354,9 +354,13 @@ <h2 id="status"><a class="header" href="#status">Status</a></h2>
 <p>Proposed, work in progress.</p>
 <h2 id="context"><a class="header" href="#context">Context</a></h2>
 <p>This ADR is a work-in-progress note for Ghaf bus passthrough implementation that will support rust-vmm-based hypervisors.</p>
-<blockquote>
+<div class="mdbook-alerts mdbook-alerts-note">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  note
+</p>
 <p><em>rust-vmm</em> is an open-source project that empowers the community to build custom Virtual Machine Monitors (VMMs) and hypervisors. For more information, see <a href="https://github.com/rust-vmm/community">https://github.com/rust-vmm/community</a>.</p>
-</blockquote>
+</div>
 <p>It is crucial to have bus devices passthrough support for ARM-based hardware as the bus is mainly used to connect the peripherals. Nowadays, the only hypervisor with some support for Platform bus is QEMU but the code is dated 2013 and not frequently used.</p>
 <p>On the other hand, one of the target hardware devices for Ghaf is NVIDIA Orin with an ARM core. To achieve Ghaf's security and hardware isolation goals, devices should support passthrough mode. Production-ready rust-vmm-based hypervisors (<a href="https://github.com/google/crosvm">crosvm</a>, <a href="https://github.com/firecracker-microvm/firecracker">Firecracker</a>, <a href="https://www.cloudhypervisor.org/">Cloud Hypervisor</a>) do not have support for Platform bus.</p>
 <h2 id="decision"><a class="header" href="#decision">Decision</a></h2>

architecture/architecture.html

@@ -366,6 +366,8 @@ <h2 id="in-this-chapter"><a class="header" href="#in-this-chapter">In This Chapt
 <li><a href="./adr/platform-bus-passthrough-support.html">Platform Bus for Rust VMM</a></li>
 </ul>
 </li>
+<li><a href="./hardening.html">Hardening</a></li>
+<li><a href="./secureboot.html">Secure Boot</a></li>
 <li><a href="./stack.html">Stack</a></li>
 </ul>
 </div>

ref_impl/build_and_run.html

@@ -352,9 +352,13 @@ <h1 class="menu-title">Ghaf Framework</h1>
 <h1 id="build-and-run"><a class="header" href="#build-and-run">Build and Run</a></h1>
 <p>This tutorial assumes that you already have basic <a href="https://git-scm.com/">git</a> experience.</p>
 <p>The canonical URL for the upstream Ghaf git repository is <a href="https://github.com/tiiuae/ghaf">https://github.com/tiiuae/ghaf</a>. To try Ghaf, you can build it from the source.</p>
-<blockquote>
+<div class="mdbook-alerts mdbook-alerts-warning">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  warning
+</p>
 <p><a href="../ref_impl/cross_compilation.html">Cross-compilation</a> support is currently under development and not available for the building process.</p>
-</blockquote>
+</div>
 <h2 id="prerequisites"><a class="header" href="#prerequisites">Prerequisites</a></h2>
 <p>First, follow the basic device-independent steps:</p>
 <ul>
@@ -436,7 +440,8 @@ <h4 id="flashing-nvidia-jetson-orin-agx"><a class="header" href="#flashing-nvidi
 <li>Connect the Linux laptop to the board with a Micro-USB cable to use <a href="https://developer.ridgerun.com/wiki/index.php/NVIDIA_Jetson_Orin/In_Board/Getting_in_Board/Serial_Console">serial interface</a>.</li>
 </ol>
 <blockquote>
-<p>For more information on the board's connections details, see the <a href="https://developer.nvidia.com/embedded/learn/jetson-agx-orin-devkit-user-guide/developer_kit_layout.html">Hardware Layout</a> section of the Jetson AGX Orin Developer Kit User Guide.</p>
+<p>[!NOTE]
+For more information on the board's connections details, see the <a href="https://developer.nvidia.com/embedded/learn/jetson-agx-orin-devkit-user-guide/developer_kit_layout.html">Hardware Layout</a> section of the Jetson AGX Orin Developer Kit User Guide.</p>
 </blockquote>
 </li>
 <li>

ref_impl/creating_appvm.html

@@ -359,11 +359,11 @@ <h1 id="creating-application-vm"><a class="header" href="#creating-application-v
 You can use an already existing VM file as a reference, for example: <code>modules/reference/appvms/business.nix</code>.</p>
 <p>Each VM has the following properties:</p>
 <div class="table-wrapper"><table><thead><tr><th><strong>Property</strong></th><th><strong>Type</strong></th><th><strong>Unique</strong></th><th><strong>Description</strong></th><th><strong>Example</strong></th></tr></thead><tbody>
-<tr><td>name</td><td>str</td><td>yes</td><td>This name is postfixed with <code>-vm</code> and will be shown in microvm list. The name, for example, <code>business-vm</code> will be also the VM hostname. The length of the name must be 8 characters or less.</td><td>“business”</td></tr>
-<tr><td>packages</td><td>list of types.package</td><td>no</td><td>Packages to include in a VM. It is possible to make it empty or add several packages.</td><td>[business top]</td></tr>
-<tr><td>macAddress</td><td>str</td><td>yes</td><td>Needed for network configuration.</td><td>"02:00:00:03:10:01"</td></tr>
+<tr><td>name</td><td>str</td><td>yes</td><td>This name is postfixed with <code>-vm</code> and will be shown in microvm list. The name, for example, <code>chromium-vm</code> will be also the VM hostname. The length of the name must be 8 characters or less.</td><td>“chromium”</td></tr>
+<tr><td>packages</td><td>list of types.package</td><td>no</td><td>Packages to include in a VM. It is possible to make it empty or add several packages.</td><td>[chromium top]</td></tr>
+<tr><td>macAddress</td><td>str</td><td>yes</td><td>Needed for network configuration.</td><td>"02:00:00:03:03:05"</td></tr>
 <tr><td>ramMb</td><td>int, [1, …, host memory]</td><td>no</td><td>Memory in MB.</td><td>3072</td></tr>
-<tr><td>cores</td><td>int,  [1, …, host cores]</td><td>no</td><td>Virtual CPU cores.</td><td>4</td></tr>
+<tr><td>cores</td><td>int,  [1, …, host cores]</td><td>no</td><td>Virtual CPU cores.</td><td></td></tr>
 </tbody></table>
 </div></li>
 <li>
@@ -382,9 +382,13 @@ <h1 id="creating-application-vm"><a class="header" href="#creating-application-v
 <pre><code>          business-vm = true;
           new-vm = true; # your new vm here
 </code></pre>
-<blockquote>
+<div class="mdbook-alerts mdbook-alerts-note">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  note
+</p>
 <p>For more information on creating new profiles, see <a href="./profiles-config.html">Profiles Configuration</a>.</p>
-</blockquote>
+</div>
 <ol start="4">
 <li>Add an IP and the VM name in <a href="https://github.com/tiiuae/ghaf/blob/main/modules/common/networking/hosts.nix">modules/common/networking/hosts.nix</a>. For example:</li>
 </ol>

ref_impl/cross_compilation.html

@@ -350,9 +350,13 @@ <h1 class="menu-title">Ghaf Framework</h1>
     SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 <h1 id="cross-compilation"><a class="header" href="#cross-compilation">Cross-Compilation</a></h1>
-<blockquote>
+<div class="mdbook-alerts mdbook-alerts-warning">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  warning
+</p>
 <p>Cross-compilation is currently under development and cannot be used properly on all the supported device configurations.</p>
-</blockquote>
+</div>
 <p>Ghaf is targeted at a range of devices and form factors that support different instruction set architectures (ISA). Many small form-factor edge devices are not powerful enough to compile the needed applications or OSs that run on them. As the most common ISA used in desktops and servers is <code>x_86</code>, this will generally require that the code is cross-compiled for target ISA e.g. <code>AArch64</code> or <code>RISC-V</code>.</p>
 <p>NixOS and Nixpkgs have good support for cross-compilation, however, there are still some that can not be compiled in this way.</p>
 <h2 id="cross-compilation-for-microchip-icicle-kit-riscv64"><a class="header" href="#cross-compilation-for-microchip-icicle-kit-riscv64">Cross-Compilation for Microchip Icicle Kit (RISCV64)</a></h2>

ref_impl/example_project.html

@@ -394,7 +394,8 @@ <h2 id="troubleshooting-for-lenovo-x1-laptop"><a class="header" href="#troublesh
 <li>
 <p>On the ghaf host, check the devices in <code>/dev/input/by-path</code> that contain “-event-” in the name. Use the command like <code>udevadm info -q all -a /dev/input/by-path/pci-0000:00:15.0-platform-i2c_designware.0-event-mouse | grep name</code> for the name of each of these devices.</p>
 <blockquote>
-<p>By name you can understand which devices belong to the touchpad. For example, on laptops in Finland they look like “SYNA8016:00 06CB:CEB3 Mouse” and “SYNA8016:00 06CB:CEB3 Touchpad”, and in the UAE they are “ELAN067C:00 04F3:31F9 Mouse” and “ELAN067C:00 04F3:31F9 Touchpad.”</p>
+<p>[!TIP]
+By name you can understand which devices belong to the touchpad. For example, on laptops in Finland they look like “SYNA8016:00 06CB:CEB3 Mouse” and “SYNA8016:00 06CB:CEB3 Touchpad”, and in the UAE they are “ELAN067C:00 04F3:31F9 Mouse” and “ELAN067C:00 04F3:31F9 Touchpad.”</p>
 </blockquote>
 </li>
 <li>

ref_impl/hw-config.html

@@ -368,7 +368,10 @@ <h1 id="hardware-configuration"><a class="header" href="#hardware-configuration"
 </li>
 <li>
 <p>Create the new configuration file with hardware-dependent parameters like host information, input and output device parameters, and others.</p>
-<p>You can use an already existing file as a reference, for example <a href="https://github.com/tiiuae/ghaf/blob/main/modules/hardware/lenovo-x1/definitions/x1-gen11.nix">modules/hardware/lenovo-x1/definitions/x1-gen11.nix</a>.</p>
+<blockquote>
+<p>[!TIP]
+You can use an already existing file as a reference, for example <a href="https://github.com/tiiuae/ghaf/blob/main/modules/hardware/lenovo-x1/definitions/x1-gen11.nix">modules/hardware/lenovo-x1/definitions/x1-gen11.nix</a>.</p>
+</blockquote>
 </li>
 </ol>
 </div>

ref_impl/installer.html

@@ -353,28 +353,31 @@ <h1 id="installer"><a class="header" href="#installer">Installer</a></h1>
 <h2 id="configuring-and-building-installer-for-ghaf"><a class="header" href="#configuring-and-building-installer-for-ghaf">Configuring and Building Installer for Ghaf</a></h2>
 <p>You can obtain the installation image for your Ghaf configuration.</p>
 <p>In addition to the live USB image that Ghaf provides it is also possible to install Ghaf. This can either be achieved by downloading the desired image or by building it as described below.</p>
-<p>Currently, only x86_64-linux systems are supported by the standalone installer. So to build e.g. the debug image
-for the Lenovo x1 follow the following steps</p>
+<p>Currently, only x86_64-linux systems are supported by the standalone installer.</p>
+<p>To build, for example, the debug image for the Lenovo x1, use the following command:</p>
 <pre><code class="language-sh">nix build .#lenovo-x1-carbon-gen11-debug-installer
 </code></pre>
 <h2 id="flashing-installer"><a class="header" href="#flashing-installer">Flashing Installer</a></h2>
 <p>Once built you must transfer it to the desired installation media. It requires at least a 4GB SSD, at the time of writing.</p>
 <pre><code class="language-nix">sudo dd if=./result/iso/ghaf-&lt;version&gt;-x86_64-linux.iso of=/dev/&lt;SSD_NAME&gt; bs=32M status=progress; sync
 </code></pre>
 <h2 id="installing-image"><a class="header" href="#installing-image">Installing Image</a></h2>
-<blockquote>
-<p><strong>WARNING</strong>: This operation is destructive and will overwrite your system.</p>
-</blockquote>
+<div class="mdbook-alerts mdbook-alerts-caution">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  caution
+</p>
+<p>This operation is destructive and will overwrite your system.</p>
+</div>
 <p>Insert the SSD into the laptop, boot, and select the option to install.</p>
-<p>When presented with the terminal run:</p>
+<p>Then use the following command:</p>
 <pre><code class="language-nix">sudo ghaf-install.sh
 </code></pre>
-<p>Check the available options shown in the prompt for the install target
-remember that the <code>/dev/sdX</code> is likely the install medium.</p>
-<p>Once entered, remembering to include <code>/dev</code>, press ENTER to complete the process.</p>
+<p>Check the available options shown in the prompt for the install target. Mind that the <code>/dev/sdX</code> is likely the install medium.</p>
+<p>Once entered, include <code>/dev</code> and press [Enter] on the keyboard to complete the process.</p>
 <pre><code class="language-nix">sudo reboot
 </code></pre>
-<p>Mind remove the installer drive.</p>
+<p>Remove the installer drive.</p>
 </div>
               <div class="sidetoc">
                 <nav class="pagetoc"></nav>

ref_impl/labwc.html

@@ -361,9 +361,13 @@ <h1 id="labwc-desktop-environment"><a class="header" href="#labwc-desktop-enviro
 <h2 id="window-border-coloring"><a class="header" href="#window-border-coloring">Window Border Coloring</a></h2>
 <p>The border color concept illustrates the application trustworthiness in a user-friendly manner. The color shows the application's security level and allows avoiding user's mistakes. The same approach can be found in other projects, for example, <a href="https://www.qubes-os.org/doc/getting-started/#color--security">QubeOS</a>.</p>
 <p>Ghaf uses patched labwc which makes it possible to change the border color for the chosen application. The implementation is based on window rules by substituting the server decoration colors (<code>serverDecoration</code> = <code>yes</code>). The <code>borderColor</code> property is responsible for the frame color.</p>
-<blockquote>
-<p><strong>TIP:</strong> According to the labwc specification, the <strong>identifier</strong> parameter is case-sensitive and relates to app_id for native Wayland windows and WM_CLASS for XWayland clients.</p>
-</blockquote>
+<div class="mdbook-alerts mdbook-alerts-important">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  important
+</p>
+<p>According to the labwc specification, the <strong>identifier</strong> parameter is case-sensitive and relates to app_id for native Wayland windows and WM_CLASS for XWayland clients.</p>
+</div>
 <p>For example, the foot terminal with Aqua colored frame:</p>
 <pre><code>&lt;windowRules&gt;
   &lt;windowRule identifier="Foot" borderColor="#00FFFF" serverDecoration="yes" skipTaskbar="yes"  /&gt;

ref_impl/profiles-config.html

@@ -358,7 +358,7 @@ <h1 id="profiles-configuration"><a class="header" href="#profiles-configuration"
 <li>Create a new enable option to enable the profile, for example, <code>new-cool-profile</code>.</li>
 <li>In the lower section, under the correct area appvms, services, programs, make sure to describe additional definitions you need.</li>
 </ol>
-<p>For example, a <code>safe-and-unsave-browsing.nix</code> file with simple setup that includes business-vm and chrome-vm could look like this:</p>
+<p>For example, a <code>safe-and-unsave-browsing.nix</code> file with a simple setup that includes business-vm and chrome-vm could look like this:</p>
 <pre><code>  config = lib.mkIf cfg.enable {
     ghaf = {
       reference = {

ref_impl/remote_build_setup.html

@@ -357,9 +357,13 @@ <h1 id="running-remote-build-on-nixos"><a class="header" href="#running-remote-b
 </ol>
 <p>If you hit an issue, check <a href="./remote_build_setup.html#troubleshooting">Troubleshooting</a>.</p>
 <h3 id="1-configuring-ssh-keys"><a class="header" href="#1-configuring-ssh-keys">1. Configuring SSH Keys</a></h3>
-<blockquote>
+<div class="mdbook-alerts mdbook-alerts-important">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  important
+</p>
 <p>This step assumes that public SSH keys were generated and copied (<em>ssh-copy-id</em>) both for normal and root users. For more information, see <a href="https://www.ssh.com/academy/ssh/copy-id#setting-up-public-key-authentication">Setting up public key authentication</a>.</p>
-</blockquote>
+</div>
 <p>Before you begin, make sure an SSH connection is established to the remote host for both normal and root users:</p>
 <pre><code>ssh USER@IP_ADDRESS_OF_REMOTE_MACHINE
 nix store ping --store ssh://USER@REMOTE_IP_ADDRESS
@@ -395,7 +399,8 @@ <h4 id="11-local-machine-configuring-ssh-keys"><a class="header" href="#11-local
 <pre><code>cd .ssh
 </code></pre>
 <blockquote>
-<p><strong>TIP</strong>:<code>.ssh</code> is a user-level access and <code>/etc/ssh</code> is system-wide.</p>
+<p>[!TIP]
+<code>.ssh</code> is a user-level access and <code>/etc/ssh</code> is system-wide.</p>
 </blockquote>
 </li>
 </ol>

ref_impl/systemd-service-config.html

@@ -668,9 +668,13 @@ <h3 id="63-nonewprivileges"><a class="header" href="#63-nonewprivileges">6.3. No
 <li><strong><code>true</code></strong>: Prevents the service and its children processes from gaining new privileges.</li>
 <li><strong><code>false</code></strong>: Allows the service and its children processes to gain new privileges.</li>
 </ul>
-<blockquote>
+<div class="mdbook-alerts mdbook-alerts-important">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  important
+</p>
 <p>Some configurations may override this setting and ignore its value.</p>
-</blockquote>
+</div>
 <h3 id="64-umask"><a class="header" href="#64-umask">6.4. UMask</a></h3>
 <p><a href="https://www.freedesktop.org/software/systemd/man/systemd.exec.html#UMask=">UMask</a>
 sets the file mode creation mask (umask) for the service, controlling the default permissions applied to newly created files and directories.</p>
@@ -852,9 +856,13 @@ <h3 id="81-systemcallfilter"><a class="header" href="#81-systemcallfilter">8.1.
 <ul>
 <li><em>List of system calls</em>: Specifies the allowed system calls for processes within the service. If the list begins with "~", the effect is inverted, meaning only the listed system calls will result in termination.</li>
 </ul>
-<blockquote>
+<div class="mdbook-alerts mdbook-alerts-tip">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  tip
+</p>
 <p>Predefined sets of system calls are available, starting with "@" followed by the name of the set.</p>
-</blockquote>
+</div>
 <div class="table-wrapper"><table><thead><tr><th><strong>Filter Set</strong></th><th><strong>Description</strong></th></tr></thead><tbody>
 <tr><td><strong>@clock</strong></td><td>Allows clock and timer-related system calls, such as clock_gettime, nanosleep, etc. This is essential for time-related operations.</td></tr>
 <tr><td><strong>@cpu-emulation</strong></td><td>Allows CPU emulation-related system calls, typically used by virtualization software.</td></tr>

release_notes/ghaf-23.05.html

@@ -368,9 +368,13 @@ <h2 id="what-is-new-in-ghaf-2305"><a class="header" href="#what-is-new-in-ghaf-2
 <li>Element, a Matrix-based chat client (on the host)</li>
 <li>the Google Android look-alike (GALA) application</li>
 </ul>
-<blockquote>
+<div class="mdbook-alerts mdbook-alerts-warning">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  warning
+</p>
 <p>Ghaf Framework is under active development, some of the features may not be stable.</p>
-</blockquote>
+</div>
 <h2 id="known-issues-and-limitations"><a class="header" href="#known-issues-and-limitations">Known Issues and Limitations</a></h2>
 <ul>
 <li>Build time is used as the current time on NVIDIA Jetson AGX Orin.