pssid-gui2

Version 2.0 of the pSSID-GUI Web Application

Installation

Ansible

Follow the steps in this repository.

Installing Docker

Following this guide, run the following:

1. cd ~
2. for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt-get remove $pkg; done

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

4. sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
5. sudo systemctl enable --now docker
6. sudo usermod -aG docker ${USER} && newgrp docker
7. Verify Docker was installed successfully by running: sudo docker run hello-world

Source Code

Clone this repository

Setting up certificates (temporarily)

Follow the steps in this repository to get mkcert installed on your local machine (not the VM!).

In your local machine, run

mkcert <VM_name>

** The certs will be saved in the same directory that you ran this command in.

You should have <VM_name>.pem and <VM_name>-key.pem generated. ** For now these names are hardcoded, but they should eventually be updated to reflect the virtual machine's name.

Finally, copy over the certs to the VM, placing them in /pssid-gui2/certs/ folder. If the certs/ folder does not exist, please create one.

scp <vm_name_here>*.pem <vm_name_here>:~/pssid-gui2/certs

Configuring the OIDC client

If the application is being ran on a virtual machine is NOT named pssid-web-dev.miserver.it.umich.edu, follow these steps:

1. Run ./scripts/generate-oidc-env.sh and it will be located in /services/server/.env
2. Navigate to the OIDC client page and set up a new OIDC client.
3. Add this as the Redirect URI: https://<VM_name>:8000/callback and save.
4. Copy the OIDC Client ID and OIDC Secret into the .env file that was created before.

** There may be an OIDC Client already avaliable with the correct redirect URI, please contact for more information.

Now, run

docker-compose -f docker-compose.yml up -d

in the same directory. You may need sudo access to run docker compose.

---

Important README Links in this Repository

Steps to add fields to config file

Ideas for future improvement

Backend

About Test Template Files

About the Backend Folders

About Each Service File - In Server

Frontend

About each Frontend Directory

About each Client Component

---

pSSID GUI Web Application

System Overview

The core application consists of three Docker containers, client, server, and MongoDB. Users directly interact with the client container, which will in turn communicate with the backend server and database containers. Test templates are files on disk that define the rules for each test, i.e., what configuration fields should be provided for each test type. Dynamics forms are then geneated on the frontend based on the rules defined in the templates.

The web application outputs two files, hosts.ini and pssid_conf.json. The latter is the pSSID daemon config file described below, which essentially contains the batches to be scheduled. The former, hosts.ini, is an Ansible inventory containing the list of hosts and groups defined on the GUI. They provide information about what to do (pssid_conf.json) on which probes (hosts.ini). The provisioning scripts will use Ansible to copy the daemon config file onto the probes defined in hosts.ini, and pSSID daemon on each probe will run accordingly.

Output pSSID Daemon Config File

The output configuration file is broken up into 7 components: hosts, host groups, schedules, SSID profiles, tests, jobs, and batches, each corresponding to a page on the GUI dashboard. See the breakdown below:

At a high level, we use template files on disk to define a test. We then use tests to define a job. Eventually, we use SSID profiles, schedules, and jobs to define a batch and run batches, not raw tests, on the probes.

Graphical User Interface

The web application has seven separate tabs, one for each component of the configuration file.

Each tab has the ability to create, read, update, and delete its own data. Each tab has the following:

• List of current objects in the MongoDB collection
  • inclduing a regex search bar to search through objects
• Add object form
• Edit/delete object form that appears after clicking on the name of an object

Troubleshooting

In case the service is not available, a quick way to restart it is to directly run the up.sh script on the VM.

First check if there are any lingering Docker containers still up and running

docker ps

When the service runs correctly, there should be three containers associated with it.

pssid-gui2_server_1
pssid-gui2_mongo_1
pssid-gui2_client_1

If the service is down, some of them might be missing from the list and some of them might still be running. Stop all lingering containers.

docker stop <container ID/name>

Then free up used resources to prepare for a restart

sudo docker system prune -af

Finally run the script to start the service

sh ~/up.sh