Docs: troubleshooting proofread

Signed-off-by: Jenni Nikolaenko <[email protected]>

docs/src/SUMMARY.md

@@ -35,6 +35,12 @@
     - [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)
+  - [Troubleshooting](troubleshooting/troubleshooting.md)
+    - [Analyzing System Logs](troubleshooting/systemd/systemd-analyzer.md)
+    - [Debugging systemd Using systemctl](troubleshooting/systemd/systemctl.md)
+    - [Inspecting Services with systemd-analyze](troubleshooting/systemd/systemd-analyzer.md)
+    - [Using strace for Debugging Initialization Sequence](troubleshooting/systemd/strace.md)
+    - [Early Shell Access](troubleshooting/systemd/early-shell.md)
   - [Ghaf as Library: Templates](ref_impl/ghaf-based-project.md)
     - [Example Project](ref_impl/example_project.md)
     - [Modules Options](ref_impl/modules_options.md)

docs/src/ref_impl/build_and_run.md

@@ -103,7 +103,6 @@ Before you begin:
    2. Connect a Linux laptop to the board with the USB-C cable.
    3. Connect the Linux laptop to the board with a Micro-USB cable to use [serial interface](https://developer.ridgerun.com/wiki/index.php/NVIDIA_Jetson_Orin/In_Board/Getting_in_Board/Serial_Console).
 
-   > [!NOTE]
    > For more information on the board's connections details, see the [Hardware Layout](https://developer.nvidia.com/embedded/learn/jetson-agx-orin-devkit-user-guide/developer_kit_layout.html) section of the Jetson AGX Orin Developer Kit User Guide.
 
 3. After the build is completed, put the board in recovery mode. For more information, see the [Force Recovery](https://developer.nvidia.com/embedded/learn/jetson-agx-orin-devkit-user-guide/howto.html#force-recovery-mode) Mode section in the Jetson AGX Orin Developer Kit User Guide.

docs/src/ref_impl/example_project.md

@@ -56,7 +56,6 @@ In case when GUI VM did not start with the error message that the device /dev/mo
 
 1. On the ghaf host, check the devices in `/dev/input/by-path` that contain “-event-” in the name. Use the command like `udevadm info -q all -a /dev/input/by-path/pci-0000:00:15.0-platform-i2c_designware.0-event-mouse | grep name` for the name of each of these devices.
 
-    > [!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.”
 
 2. If there are no such devices in `/dev/input/by-path`, then you can check the devices /dev/input/event* with a similar command.

docs/src/ref_impl/hw-config.md

@@ -22,5 +22,4 @@ 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.
 
-    > [!TIP]
     > 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). 

docs/src/ref_impl/reference_implementations.md

@@ -49,6 +49,8 @@ The same goes with the architectural variants as headless devices or end-user de
    - [labwc Desktop Environment](./labwc.md)
    - [IDS VM Further Development](./idsvm-development.md)
    - [systemd Service Hardening](./systemd-service-config.md)
+- [Troubleshooting](../troubleshooting/troubleshooting.md)
+  - [Troubleshooting with systemd](../troubleshooting/systemd/systemd_trblsh.md)
 - [Ghaf as Library: Templates](./ghaf-based-project.md)
    - [Example Project](./example_project.md)
    - [Modules Options](./modules_options.md)

docs/src/ref_impl/remote_build_setup.md

@@ -58,7 +58,6 @@ Do the following on a local machine:
    ```
    cd .ssh
    ```
-    > [!TIP]
     > `.ssh` is a user-level access and `/etc/ssh` is system-wide.
 
 

docs/src/ref_impl/systemd-service-config.md

@@ -5,7 +5,12 @@
 
 # systemd Service Hardening
 
-This document outlines systemd service configurations that significantly impact a service's exposure. The following configurations can be utilized to enhance the security of a systemd service:
+This document outlines systemd service configurations that significantly impact a service's exposure.
+
+> [!TIP]
+> For more information on troubleshooting common issues with systemd services, see [Troubleshooting with systemd](/docs/src/troubleshooting/systemd/systemd_trblsh.md).
+
+The following configurations can be utilized to enhance the security of a systemd service:
 
 <table>
 <tr>
@@ -235,7 +240,8 @@ Additionally, when enabled, all temporary files created by a service in these di
 
 ## 3. User Separation
 
-> **IMPORTANT:** Not applicable for the service runs as root.
+> [!IMPORTANT]
+> Not applicable for the service runs as root.
 
 
 ### 3.1. PrivateUsers

docs/src/release_notes/ghaf-23.12.md

@@ -84,8 +84,8 @@ Download the required image and use the following instructions:
 |-------------------------|--------------------|
 | ghaf-23.12_Generic_x86.tar.xz | [Running Ghaf Image for x86 Computer](../ref_impl/build_and_run.md#running-ghaf-image-for-x86-computer) |
 | ghaf-23.12_Lenovo_X1_Carbon_Gen11.tar.xz  | [Running Ghaf Image for Lenovo X1](../ref_impl/build_and_run.md#running-ghaf-image-for-lenovo-x1) |
-| ghaf-23.12_Nvidia_Orin_AGX_cross-compiled-no-demoapps.tar.xz[^note], ghaf-23.12_Nvidia_Orin_AGX_cross-compiled.tar.xz, ghaf-23.12_Nvidia_Orin_AGX_native-build.tar.xz | [Ghaf Image for NVIDIA Jetson Orin AGX](../ref_impl/build_and_run.md#ghaf-image-for-nvidia-jetson-orin-agx) |
-| ghaf-23.12_Nvidia_Orin_NX_cross-compiled-no-demoapps[^note].tar.xz, ghaf-23.12_Nvidia_Orin_NX_cross-compiled.tar.xz, ghaf-23.12_Nvidia_Orin_NX_native-build.tar.xz | [Ghaf Image for NVIDIA Jetson Orin AGX](../ref_impl/build_and_run.md#ghaf-image-for-nvidia-jetson-orin-agx) |
+| ghaf-23.12_Nvidia_Orin_AGX_cross-compiled-no-demoapps.tar.xz[^note1], ghaf-23.12_Nvidia_Orin_AGX_cross-compiled.tar.xz, ghaf-23.12_Nvidia_Orin_AGX_native-build.tar.xz | [Ghaf Image for NVIDIA Jetson Orin AGX](../ref_impl/build_and_run.md#ghaf-image-for-nvidia-jetson-orin-agx) |
+| ghaf-23.12_Nvidia_Orin_NX_cross-compiled-no-demoapps[^note1].tar.xz, ghaf-23.12_Nvidia_Orin_NX_cross-compiled.tar.xz, ghaf-23.12_Nvidia_Orin_NX_native-build.tar.xz | [Ghaf Image for NVIDIA Jetson Orin AGX](../ref_impl/build_and_run.md#ghaf-image-for-nvidia-jetson-orin-agx) |
 | ghaf-23.12_PolarFire_RISC-V.tar.xz | [Building Ghaf Image for Microchip Icicle Kit](../ref_impl/build_and_run.md#building-ghaf-image-for-microchip-icicle-kit) |
 
-[^note] no-demoapps images do not include Chromium, Zathura, and GALA applications.
+[^note1] no-demoapps images do not include Chromium, Zathura, and GALA applications.

docs/src/release_notes/ghaf-24.03.md

@@ -78,7 +78,7 @@ Download the required image and use the following instructions:
 |-------------------------|--------------------|
 | ghaf-24.03_Generic_x86.tar.xz | [Running Ghaf Image for x86 Computer](../ref_impl/build_and_run.md#running-ghaf-image-for-x86-computer) |
 | ghaf-24.03_Lenovo_X1_Carbon_Gen11.tar.xz  | [Running Ghaf Image for Lenovo X1](../ref_impl/build_and_run.md#running-ghaf-image-for-lenovo-x1) |
-| ghaf-24.03_Nvidia_Orin_AGX_cross-compiled-no-demoapps.tar.xz[^note], ghaf-24.03_Nvidia_Orin_AGX_cross-compiled.tar.xz, ghaf-24.03_Nvidia_Orin_AGX_native-build.tar.xz | [Ghaf Image for NVIDIA Jetson Orin AGX](../ref_impl/build_and_run.md#ghaf-image-for-nvidia-jetson-orin-agx) |
+| ghaf-24.03_Nvidia_Orin_AGX_cross-compiled-no-demoapps.tar.xz[^note1], ghaf-24.03_Nvidia_Orin_AGX_cross-compiled.tar.xz, ghaf-24.03_Nvidia_Orin_AGX_native-build.tar.xz | [Ghaf Image for NVIDIA Jetson Orin AGX](../ref_impl/build_and_run.md#ghaf-image-for-nvidia-jetson-orin-agx) |
 | ghaf-24.03_Nvidia_Orin_NX_cross-compiled-no-demoapps[^note1].tar.xz, ghaf-24.03_Nvidia_Orin_NX_cross-compiled.tar.xz, ghaf-24.03_Nvidia_Orin_NX_native-build.tar.xz | [Ghaf Image for NVIDIA Jetson Orin AGX](../ref_impl/build_and_run.md#ghaf-image-for-nvidia-jetson-orin-agx) |
 | ghaf-24.03_PolarFire_RISC-V.tar.xz | [Building Ghaf Image for Microchip Icicle Kit](../ref_impl/build_and_run.md#building-ghaf-image-for-microchip-icicle-kit) |
 

docs/src/scenarios/run_cuttlefish.md

@@ -17,7 +17,6 @@ You can run Android as a VM on Ghaf for testing and development purposes using N
     * For NVIDIA Jetson Orin AGX (ARM64): [cvd-host_package.tar.gz](https://ci.android.com/builds/submitted/9970479/aosp_cf_arm64_phone-userdebug/latest/cvd-host_package.tar.gz) and [aosp_cf_arm64_phone-img-9970479.zip](https://ci.android.com/builds/submitted/9970479/aosp_cf_arm64_phone-userdebug/latest/aosp_cf_arm64_phone-img-9970479.zip)
     * For Generic x86: [cvd-host_package.tar.gz](https://ci.android.com/builds/submitted/9970479/aosp_cf_x86_64_phone-userdebug/latest/cvd-host_package.tar.gz) and [aosp_cf_x86_64_phone-img-9970479.zip](https://ci.android.com/builds/submitted/9970479/aosp_cf_x86_64_phone-userdebug/latest/aosp_cf_x86_64_phone-img-9970479.zip)
 
-    > [!NOTE]
     > Download a host package from the same build as the image.
 
 2. Make sure Internet connection is working in Ghaf. If the system gets an IP address but the DNS server is not responding, set the correct date and time.

docs/src/scenarios/run_win_vm.md

@@ -22,7 +22,6 @@ You can run Windows 11 in a VM on Ghaf with NVIDIA Jetson Orin AGX (ARM64) or Ge
     sudo mkdir /mnt
     sudo mount /dev/sda /mnt
     ```
-    > [!WARNING]
     > [For NVIDIA Jetson Orin AGX] Make sure to use a fresh VHDX image file that was not booted in another environment before.
 
 
@@ -39,7 +38,6 @@ You can run Windows 11 in a VM on Ghaf with NVIDIA Jetson Orin AGX (ARM64) or Ge
 
 2. Windows 11 requires Internet access to finish the setup. To boot the VM without an Internet connection, open cmd with Shift+F10 and type `OOBE\BYPASSNRO`. After the configuration restart click “I don’t have internet“ to skip the Internet connection step and continue the installation.
 
-    > [!TIP]
     > If after pressing Shift+F10 the command window is not displayed, try to switch between opened windows by using Alt+Tab.
 
 
@@ -65,7 +63,6 @@ Do the following:
    * Name: `BypassTPMCheck`, value `1`.
    * Name: `BypassSecureBootCheck`, value `1`.
 
-    > [!TIP]
     > [For Ghaf running on a laptop] If after pressing Shift+F10 the command window is not displayed, try again with the Fn key (Shift+Fn+F10) or switch between opened windows by using Alt+Tab.
 
 4. Install Windows 11 in the VM.

docs/src/technologies/nvidia_virtualization_bpmp.md

@@ -35,7 +35,6 @@ The current implementation includes a host configuration for the UARTA passthrou
     };
     ```
 
-    > [!IMPORTANT]
     > These options are integrated to [NVIDIA Jetson Orin targets](https://github.com/tiiuae/ghaf/blob/main/targets/nvidia-jetson-orin/default.nix) but disabled by default until the implementation is finished.
 
 2. Build the target and boot the image. You can write the image to an SSD for testing with a recent NVIDIA UEFI FW.
@@ -68,8 +67,7 @@ The current implementation includes a host configuration for the UARTA passthrou
 
 1. Build a guest kernel according to [UARTA passthrough instructions](https://github.com/jpruiz84/bpmp-virt)[^note1] and use the following script to start the VM:
 
-    > [!IMPORTANT]
-    > IMG is the kernel image and FS the rootfs.
+    > IMG is the kernel image, and FS is the rootfs.
 
     ```
     IMG=$1

docs/src/troubleshooting/systemd/early-shell.md

@@ -3,18 +3,20 @@
     SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
-# Early shell access
+# Early Shell Access
 
 In some cases, the system may fail to boot due to the failure of a critical service. If this happens, you can follow these steps to diagnose the issue with systemd services:
 
-1. Increase the systemd log level using the previously mentioned option, and load the image.
+1. [Increase the systemd log level](./system-log.md) using the previously mentioned option, and load the image.
+
 2. Reboot the system. As expected, you will encounter a boot failure.
+
 3. Force reboot the machine. When the machine starts again, interrupt the bootloader and add the following to the bootloader command line:
 
    ```
    rescue systemd.setenv=SYSTEMD_SULOGIN_FORCE=1
    ```
 
-   To modify the bootloader command, select the boot option and then press the 'e' key.
+   To modify the bootloader command, select the boot option and then press the `e` key.
 
 4. You will now enter an early shell environment. Here, you can access the logs from the previous boot using `journalctl`. The logs will help you identify any service failures.

docs/src/troubleshooting/systemd/strace.md

@@ -3,24 +3,28 @@
     SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
-# Use `strace` to debug initialization sequence
+# Using strace for Debugging Initialization Sequence
 
-`strace` can give detailed insight about system calls made by a service. This is very helpfull in debugging restrictions applied on system calls and capability of any service. Though we can attach `strace` with PID of  a running process, but some time we may need to debug service initialization sequence also.
+`strace` can give detailed information about system calls made by a service. This is helpful in debugging restrictions applied to system calls and the capability of any service. Though we can attach `strace` with the PID of a running process, sometimes we may need to debug the service initialization sequence.
 
-To debug initialization sequence we need to attach `strace` with the service binary in `ExecStart` . To attach strace find out existing `ExecStart` of the service using command:
+To debug the initialization sequence: 
 
-```bash
-$> systemctl cat <service-name>.service | grep ExecStart
-```
+1. Attach `strace` with the service binary in `ExecStart`. For that, find out the existing `ExecStart` of the service by using the command:
 
-It will give  command line options used with service binary. Now we need to override `ExecStart` of the service, in order to attach `strace`. We'll use same options with `strace`too to replicate same scenario. For example to attach `strace` with `auditd` service we'll use following configuration at a suitable location:
+    ```bash
+    $> systemctl cat <service-name>.service | grep ExecStart
+    ```
 
-```Nix
-systemd.services."auditd".serviceConfig.ExecStart = lib.mkForce "${pkgs.strace}/bin/strace -o /etc/auditd_trace.log ${pkgs.audit}/bin/auditd -l -n -s nochange";
-```
+    It will give command line options used with service binary.
+    
+2. Override `ExecStart` of the service to attach `strace`. We will use the same options with `strace` to replicate the same scenario. For example, to attach `strace` with `auditd` service we will use the following configuration at a suitable location:
 
-Command`${pkgs.audit}/bin/auditd -l -n -s nochange`is used in regular `ExecStart`of `auditd`service. In above command we have attached `strace` with the command, which will generate system call traces in file `/etc/auditd_trace.log`
+    ```Nix
+    systemd.services."auditd".serviceConfig.ExecStart = lib.mkForce "${pkgs.strace}/bin/strace -o /etc/auditd_trace.log ${pkgs.audit}/bin/auditd -l -n -s nochange";
+    ```
 
-After modifying above configuration you need to rebuild and load Ghaf image. 
+    The `${pkgs.audit}/bin/auditd -l -n -s nochange` command is used in the regular `ExecStart` of `auditd` service. In the above command, we attached `strace` with the command, which will generate system call traces in `/etc/auditd_trace.log` file.
 
-The log may give you information about the system call restriction which caused the service failure. You can tune your service config accordingly.
+3. After modifying above configuration, rebuild and load a Ghaf image. 
+
+    The log may give you information about the system call restriction that caused the service failure. You can tune your service config accordingly.