..
 # Copyright (c) 2025, Arm Limited.
 #
 # SPDX-License-Identifier: MIT

#######################
Setup & Configure a SUT
#######################

The System Under Test (SUT) is the system on which benchmarks are executed.
Fastpath communicates with the SUT over SSH to configure it (e.g. install the
kernel to be benchmarked, reboot, configure kernel command line and sysctls,
etc). Then it invokes benchmarks by pulling and running Docker containers on the
SUT.

Fastpath's requirements for the SUT are as follows:

- Must use grub to boot the kernel and kernel must be stored at /boot
- A minimal set of shell utilities must be available
- Docker must be installed
- A user account must be available which is a member of the "docker" and "sudo"
  groups
- The user account must have its public key setup such that it can SSH into the
  SUT without the need for a password
- The user account must be configured for passwordless sudo usage

Ubuntu is well tested with Fastpath and is known to meet the first 2
requirements out of the box: Using Ubuntu as the SUT's operating system is
recommended for this reason.

**************
Install Docker
**************

This example assumes Ubuntu is installed on the SUT. Refer to distribution
documentation if using a different distro. The apt version of Docker is
preferred as issues have been observed with the snap version:

.. code-block:: shell

  sudo apt-get install docker.io
  sudo groupadd docker
  sudo usermod -aG docker $USER

*******************
Create User Account
*******************

This example assumes Ubuntu is installed on the SUT. Refer to distribution
documentation if using a different distro. This shows how to create a dedicated
user account on the SUT that can be used by fastpath. You are free to use an
existing account as long as it meets the stated requirements.

First, on the SUT, create a group and user account, which is a member of the
docker and sudo groups. Then configure the user for passwordless sudo. Finally
set a password for the user:

.. code-block:: shell

  sudo groupadd fpuser
  sudo useradd -g fpuser -m fpuser
  sudo usermod --shell /bin/bash fpuser
  sudo usermod -a -G docker fpuser
  sudo usermod -a -G sudo fpuser
  echo "fpuser ALL=(ALL) NOPASSWD: ALL" | sudo tee /etc/sudoers.d/fpuser
  sudo passwd fpuser
  <enter desired password>

Next, on the system that will run Fastpath, create a public/private key pair for
the user and install the public key on the SUT. This can be performed with a
combination of ``ssh-keygen`` and ``ssh-copy-id``.

.. warning::

  The private key must be kept secure as it can be used to access the SUT with
  root privileges.

You can validate the setup by running the Fastpath ``fingerprint`` command. If
it successfully outputs all the HW and SW details, you have succeeded:

.. code-block:: shell

  fastpath sut fingerprint --user fpuser [--port <id>] [--keyfile <filename>] <SUT hostname or IP>