From 063d7f34821f39cede1e9a2ab86ad872b981189a Mon Sep 17 00:00:00 2001
From: Markus Pettersson <markus.pettersson@mullvad.net>
Date: Mon, 16 Oct 2023 17:04:31 +0200
Subject: [PATCH] Update instructions on build a new test image

---
 test/BUILD_OS_IMAGE.md | 94 +++++++++++++++++++++++++++++++++++++++---
 test/README.md         |  2 +-
 2 files changed, 90 insertions(+), 6 deletions(-)

diff --git a/test/BUILD_OS_IMAGE.md b/test/BUILD_OS_IMAGE.md
index 5ab0f2e04f59..fbe249e656eb 100644
--- a/test/BUILD_OS_IMAGE.md
+++ b/test/BUILD_OS_IMAGE.md
@@ -2,6 +2,13 @@ This document explains how to create base OS images and run test runners on them
 
 For macOS, the host machine must be macOS. All other platforms assume that the host is Linux.
 
+# Configuring a user in the image
+
+`test-manager` assumes that a dedicated user named `test` (with password `test`) is configured in any guest system which it should control.
+Also, it is strongly recommended that a new image should have passwordless `sudo` set up and `sshd`  running on boot,
+since this will greatly simplify the bootstrapping of `test-runner` and all needed binary artifacts (MullvadVPN App, GUI tests ..).
+The legacy method of pre-building a test-runner image is detailed [further down in this document](#).
+
 # Creating a base Linux image
 
 These instructions use Debian, but the process is pretty much the same for any other distribution.
@@ -15,12 +22,22 @@ qemu-img create -f qcow2 ./os-images/debian.qcow2 5G
 qemu-system-x86_64 -cpu host -accel kvm -m 4096 -smp 2 -cdrom debian-11.5.0-amd64-netinst.iso -drive file=./os-images/debian.qcow2
 ```
 
-`xvfb` must be installed on the guest system. On Fedora, this package is called `xorg-x11-server-Xvfb`.
-On Debian/Ubuntu, the package is called `xvfb`. You will also need `wireguard-tools` and some
-additional libraries. They are likely already installed if gnome is installed. On Debian:
+## Dependencies to install in the image
+
+`xvfb` must be installed on the guest system. You will also need
+`wireguard-tools` and some additional libraries. They are likely already
+installed if gnome is installed.
+
+### Debian/Ubuntu
+
+```bash
+apt install libnss3 libgbm1 libasound2 libatk1.0-0 libatk-bridge2.0-0 libcups2 libgtk-3-0 wireguard-tools xvfb
+```
+
+### Fedora
 
 ```bash
-apt install libnss3 libgbm1 libasound2 libatk1.0-0 libatk-bridge2.0-0 libcups2 libgtk-3-0 wireguard-tools
+dnf install libnss3 libgbm1 libasound2 libatk1.0-0 libatk-bridge2.0-0 libcups2 libgtk-3-0 wireguard-tools xorg-x11-server-Xvfb
 ```
 
 # Creating a base Windows image
@@ -93,7 +110,74 @@ do the following:
 1. Press shift-F10 to open a command prompt.
 1. Type `oobe\BypassNRO` and press enter.
 
-## Bootstrapping test runner
+# Creating a testrunner image (Legacy method)
+
+The [build-runner-image.sh](./scripts/build-runner-image.sh) script produces a
+virtual disk containing the test runner binaries, which must be mounted when
+starting the guest OS. They are used `build-runner-image.sh` assumes that an environment
+variable `$TARGET` is set to one of the following values:
+`x86_64-unknown-linux-gnu`, `x86_64-pc-windows-gnu` depending on which platform
+you want to build a testrunner-image for.
+
+## Bootstrapping test runner (Legacy method)
+
+### Linux
+
+The testing image needs to be mounted to `/opt/testing`, and the test runner needs to be started on
+boot.
+
+* In the guest, create a mount point for the runner: `mkdir -p /opt/testing`.
+
+* Add an entry to `/etc/fstab`:
+
+    ```
+    # Mount testing image
+    /dev/sdb /opt/testing ext4 defaults 0 1
+    ```
+
+* Create a systemd service that starts the test runner, `/etc/systemd/system/testrunner.service`:
+
+    ```
+    [Unit]
+    Description=Mullvad Test Runner
+
+    [Service]
+    ExecStart=/opt/testing/test-runner /dev/ttyS0 serve
+
+    [Install]
+    WantedBy=multi-user.target
+    ```
+
+* Enable the service: `systemctl enable testrunner.service`.
+
+### Note about SELinux (Fedora)
+
+SELinux prevents services from executing files that do not have the `bin_t` attribute set. Building
+the test runner image stripts extended file attributes, and `e2tools` does not yet support setting
+these. As a workaround, we currently need to reapply these on each boot.
+
+First, set `bin_t` for all files in `/opt/testing`:
+
+```
+semanage fcontext -a -t bin_t "/opt/testing/.*"
+```
+
+Secondly, update the systemd unit file to run `restorecon` before the `test-runner`, using the
+`ExecStartPre` option:
+
+```
+[Unit]
+Description=Mullvad Test Runner
+
+[Service]
+ExecStartPre=restorecon -v "/opt/testing/*"
+ExecStart=/opt/testing/test-runner /dev/ttyS0 serve
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### Windows
 
 The test runner needs to be started on boot, with the test runner image mounted at `E:`.
 This can be achieved as follows:
diff --git a/test/README.md b/test/README.md
index 8e03baf31032..c39785e9a9c5 100644
--- a/test/README.md
+++ b/test/README.md
@@ -114,7 +114,7 @@ cargo run --bin test-manager set debian11 qemu ./os-images/debian11.qcow2 linux
     --disks ./testrunner-images/linux-test-runner.img
 
 # Try it out to see if it works
-#cargo run --bin test-manager run-vm debian11
+cargo run --bin test-manager run-vm debian11
 
 # Run all tests
 cargo run --bin test-manager run-tests debian11 \