Docs: add new VM, HW and profile configuration

Signed-off-by: Jenni Nikolaenko <[email protected]>
tiiuae · Jul 18, 2024 · fda620d · fda620d
1 parent 8943b19
commit fda620d
Show file tree

Hide file tree

Showing 6 changed files with 125 additions and 45 deletions.
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -30,6 +30,8 @@
     - [Installer](ref_impl/installer.md)
     - [Cross-Compilation](ref_impl/cross_compilation.md)
     - [Creating Application VM](ref_impl/creating_appvm.md)
+    - [Hardware Configuration](ref_impl/hw-config.md)
+    - [Profiles Configuration](ref_impl/profiles-config.md)
     - [labwc Desktop Environment](ref_impl/labwc.md)
     - [IDS VM Further Development](ref_impl/idsvm-development.md)
     - [systemd Service Hardening](ref_impl/systemd-service-config.md)

diff --git a/docs/src/ref_impl/creating_appvm.md b/docs/src/ref_impl/creating_appvm.md
@@ -9,60 +9,55 @@ Application VM (App VM) is a VM that improves trust in system components by isol
 
 As a result, both highly trusted applications and untrusted applications can be hosted in the same secure system when the concerns are separated in their own App VM.
 
-To create an App VM:
-1. Add the VM description.
-2. Add an application launcher in GUI VM.
+To create an App VM, do the following:
 
+1. Create the new configuration file for your VM in the [modules/reference/appvms](https://github.com/tiiuae/ghaf/tree/main/modules/reference/appvms) directory.  
+   You can use an already existing VM file as a reference, for example: `modules/reference/appvms/business.nix`.
 
-## Adding App VM Description
+    Each VM has the following properties:
 
-Add the VM description in the target configuration.  
-[lenovo-x1-carbon.nix](https://github.com/tiiuae/ghaf/blob/main/targets/lenovo-x1-carbon.nix) already has chromium-vm, gala-vm, and zathura-vm.
+    | **Property** | **Type** | **Unique** | **Description**  | **Example**  |
+    | ------------ | -------- | ---------- | ---------------- | ------------ |
+    | name         | str      | yes        | This name is postfixed with `-vm` and will be shown in microvm list. The name, for example, `business-vm` will be also the VM hostname. The length of the name must be 8 characters or less.    | “business”  |
+    | packages     | list of types.package    | no         | Packages to include in a VM. It is possible to make it empty or add several packages.   | [business top]  |
+    | macAddress   | str      | yes        | Needed for network configuration.     | "02:00:00:03:10:01" |
+    | ramMb        | int, [1, …, host memory] | no         | Memory in MB.         | 3072  |
+    | cores        | int,  [1, …, host cores] | no         | Virtual CPU cores.    | 4     |
+
+2. Create a new option for your VM in [modules/reference/appvms/default.nix](https://github.com/tiiuae/ghaf/blob/main/modules/reference/appvms/default.nix). For example:
 
 ```
-vms = with pkgs; [
-  {
-    name = "chromium";
-    packages = [chromium];
-    macAddress = "02:00:00:03:03:05";
-    ramMb = 3072;
-    cores = 4;
-  }
-  {
-    name = "gala";
-    packages = [(pkgs.callPackage ../packages/gala {})];
-    macAddress = "02:00:00:03:03:06";
-    ramMb = 1536;
-    cores = 2;
-  }
-  {
-    name = "zathura";
-    packages = [zathura];
-    macAddress = "02:00:00:03:03:07";
-    ramMb = 512;
-    cores = 1;
-  }
-];
+    business-vm = lib.mkEnableOption "Enable the Business appvm";
+    new-vm = lib.mkEnableOption "Enable the New appvm"; # your new vm here
 ```
 
-Each VM has the following properties:
-
-| **Property** | **Type**                  | **Unique** | **Description**                                                                                               | **Example**         |
-| -------------- | --------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------- | --------------------- |
-| name         | str                       | yes        | This name is postfixed with `-vm` and will be shown in microvm list. The name, for example, `chromium-vm` will be also the VM hostname. The length of the name must be 8 characters or less.                                     | “chromium”        |
-| packages     | list of types.package     | no         | Packages to include in a VM. It is possible to make it empty or add several packages.                          | [chromium top]    |
-| macAddress   | str                       | yes        | Needed for network configuration.                                                                              | "02:00:00:03:03:05" |
-| ramMb        | int, [1, …, host memory] | no         | Memory in MB.                                                                                                  | 3072                |
-| cores        | int,  [1, …, host cores] | no         | Virtual CPU cores.                                                                                             | 4                   |
+```
+        ++ (lib.optionals cfg.business-vm [(import ./business.nix {inherit pkgs lib config;})])
+        ++ (lib.optionals cfg.new-vm [(import ./new_vm_name.nix {inherit pkgs lib config;})]); # your new vm here
+```
 
+3. Add your new VM to the profile file, for example [mvp-user-trial.nix](https://github.com/tiiuae/ghaf/blob/main/modules/profiles/mvp-user-trial.nix):
 
-## Adding Application Launcher in GUI VM
+```
+          business-vm = true;
+          new-vm = true; # your new vm here
+```
 
-To add an application launcher, add an element in the [guivm.nix](https://github.com/tiiuae/ghaf/blob/main/modules/microvm/virtualization/microvm/guivm.nix) file to the **graphics.weston.launchers** list.
+> For more information on creating new profiles, see [Profiles Configuration](./profiles-config.md).
 
-A launcher element has two properties:
+4. Add an IP and the VM name in [modules/common/networking/hosts.nix](https://github.com/tiiuae/ghaf/blob/main/modules/common/networking/hosts.nix). For example:
+
+```
+    {
+      ip = 105;
+      name = "business-vm";
+    }
+```
 
-* **path**: path to the executable you want to run, like a graphical application;
-* **icon**: path to an icon to show.
+5. Add an application launcher in [modules/common/services/desktop.nix](https://github.com/tiiuae/ghaf/blob/main/modules/common/services/desktop.nix).  
+
+   A launcher element has the following properties:
 
-Check the example launchers at [guivm.nix](https://github.com/tiiuae/ghaf/blob/main/modules/microvm/virtualization/microvm/guivm.nix).
+   * **name**: the name of the launcher;
+   * **path**: path to the executable you want to run, like a graphical application;
+   * **icon**: path to an icon to show. If you have an icon package for your launcher, add it here as well: [packages/icon-pack/default.nix](https://github.com/tiiuae/ghaf/blob/main/packages/icon-pack/default.nix).
diff --git a/docs/src/ref_impl/development.md b/docs/src/ref_impl/development.md
@@ -14,8 +14,10 @@ The scope of target support is updated with development progress:
 * [Installer](./installer.md)
 * [Cross-Compilation](./cross_compilation.md)
 * [Creating Application VM](./creating_appvm.md)
+* [Hardware Configuration](ref_impl/hw-config.md)
+* [Profiles Configuration](ref_impl/profiles-config.md)
 * [labwc Desktop Environment](./labwc.md)
-* [idsvm Further Development](./idsvm-development.md)
+* [IDS VM Further Development](./idsvm-development.md)
 * [systemd Service Hardening](./systemd-service-config.md)
 
 Once you are up and running, you can participate in the collaborative development process by building a development build with additional options. For example, with the development username and password that are defined in [accounts.nix](https://github.com/tiiuae/ghaf/blob/main/modules/common/users/accounts.nix).
@@ -27,6 +29,7 @@ If you authorize your development SSH keys in the [ssh.nix](https://github.com/t
     nixos-rebuild --flake .#lenovo-x1-carbon-gen11-debug --target-host root@<ip_address_of_ghaf-host> --fast switch
     ...
 
+> [!TIP]
 > With the `-debug` targets, the debug ethernet is enabled on host. With Lenovo X1 Carbon, you can connect USB-Ethernet adapter for the debug and development access.
 
 Pull requests are the way for contributors to submit code to the Ghaf project. For more information, see [Contribution Guidelines](../appendices/contributing_general.md).
diff --git a/docs/src/ref_impl/hw-config.md b/docs/src/ref_impl/hw-config.md
@@ -0,0 +1,25 @@
+<!--
+    Copyright 2022-2024 TII (SSRC) and the Ghaf contributors
+    SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Hardware Configuration
+
+All configuration files for reference target devices are in [modules/hardware](https://github.com/tiiuae/ghaf/tree/main/modules/hardware).
+
+The ghaf-24.06 release supports the following target hardware:
+
+* NVIDIA Jetson AGX Orin
+* NVIDIA Jetson Orin NX
+* Generic x86 (PC)
+* Polarfire Icicle Kit
+* Lenovo ThinkPad X1 Carbon Gen 11
+* Lenovo ThinkPad X1 Carbon Gen 10
+* NXP i.MX 8M Plus
+
+To add a new hardware configuration file, do the following:
+
+1. Create a separate folder for the device in [modules/hardware](https://github.com/tiiuae/ghaf/tree/main/modules/hardware).
+2. Create the new configuration file with hardware-dependent parameters like host information, input and output device parameters, and others.
+
+   You can use an already existing file as a reference, for example [modules/hardware/lenovo-x1/definitions/x1-gen11.nix](https://github.com/tiiuae/ghaf/blob/main/modules/hardware/lenovo-x1/definitions/x1-gen11.nix). 
diff --git a/docs/src/ref_impl/profiles-config.md b/docs/src/ref_impl/profiles-config.md
@@ -0,0 +1,48 @@
+<!--
+    Copyright 2022-2024 TII (SSRC) and the Ghaf contributors
+    SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Profiles Configuration
+
+A profile is a set of software needed for a particular use case. All profiles configuration files are in [modules/profiles](https://github.com/tiiuae/ghaf/tree/main/modules/profiles).
+
+To add a new profile, do the following:
+
+1. Create your own configuration file using [modules/profiles/mvp-user-trial.nix](https://github.com/tiiuae/ghaf/blob/main/modules/profiles/mvp-user-trial.nix) as a reference.
+2. Depending on the location of your reference appvms, services, or programs change the includes to point to them.
+3. Create a new enable option to enable the profile, for example, `new-cool-profile`.
+4. In the lower section, under the correct area appvms, services, programs, make sure to describe additional definitions you need.
+
+
+For example, a `safe-and-unsave-browsing.nix` file with simple setup that includes business-vm and chrome-vm could look like this:
+
+```
+  config = lib.mkIf cfg.enable {
+    ghaf = {
+      reference = {
+        appvms = {
+          enable = true;
+          chromium-vm = true;
+          business-vm = true;
+        };
+
+        services = {
+          enable = true;
+        };
+
+        programs = {
+        };
+      };
+
+      profiles = {
+        laptop-x86 = {
+          enable = true;
+          netvmExtraModules = [../reference/services];
+          guivmExtraModules = [../reference/programs];
+          inherit (config.ghaf.reference.appvms) enabled-app-vms;
+        };
+      };
+    };
+  };
+```
diff --git a/docs/src/ref_impl/reference_implementations.md b/docs/src/ref_impl/reference_implementations.md
@@ -26,6 +26,7 @@ NixOS, a Linux OS distribution packaged with Nix, provides us with:
 
 Even when unmodified upstream is often preferred, even ideal, to ensure timely security updates from upstream—customizations are sometimes required.
 
+
 ### Example
 
 To support a reference board without a vendor board support package (BSP)—bootloader, kernel, device drivers—is often not feasible. With this approach, we can overlay the generic NixOS Linux kernel with the vendor kernel and add a vendor bootloader to build a target image.
@@ -39,9 +40,15 @@ The same goes with the architectural variants as headless devices or end-user de
 
 - [Development](./development.md)
    - [Build and Run](./build_and_run.md)
+   - [Running Remote Build on NixOS](./remote_build_setup.md)
    - [Installer](./installer.md)
    - [Cross-Compilation](./cross_compilation.md)
    - [Creating Application VM](./creating_appvm.md)
+   - [Hardware Configuration](ref_impl/hw-config.md)
+   - [Profiles Configuration](ref_impl/profiles-config.md)
+   - [labwc Desktop Environment](./labwc.md)
+   - [IDS VM Further Development](./idsvm-development.md)
+   - [systemd Service Hardening](./systemd-service-config.md)
 - [Ghaf as Library: Templates](./ghaf-based-project.md)
    - [Example Project](./example_project.md)
    - [Modules Options](./modules_options.md)