# VMmark 3 Web Interface
- Table of Content
[ToC]
## What is VMmark 3?

Vmmark 3 is a virtual machine used to benchmark cloud servers. The benchmark creates a score grading based on various jobs. Results are stored comprehensively. The deployment and running of the benchmark is currently done via command line and the modification of the lengthy VMmark3.properties file. The web interface is trying to create a new interface for using the benchmark.

## Purpose of the Web Interface

The purpose of the web interface is to make the process of running the benchmark easier to understand and to avoid user error. Various dropdowns and validations try to ensure that input actually being used on the benchmark is valid. The view results page additionally allows users to view the results in a more quantifiable, user-friendly way as a table

## Web Interface Features

The web interface will start with the properties wizard, if no properties file exists, but start with the control panel otherwise

### Properties wizard
The properties wizard will get the user data (username, password and vcserver) to get a session ID from the vCenter REST API. The API can then be used to create dropdown menus for different properties. For the datastores, the VI Java API is used to get the datastores by hosts of a cluster to ensure the datastore is available on all hosts of the cluster, for all other dropdown menus, the REST API is used.
#### Configuration pages of the properties wizard:
- Login
- User input for username, password and vcserver
- Form validation: checks if a session ID can be obtained and if fields are empty
- Optional information: email, email SMTP and email from
- Form validation: validates email addresses and SMTP as IP address or domain, fields can't be empty if email notification option is checked
- Hosts
- Only datacenters with at least one cluster containing hosts are shown
- Only clusters containing hosts are shown
- Javascript code dynamically displays only clusters of the selected datacenter
- Client cluster and SUT cluster can be the same
- Validation: if calls to VI Java API are unsuccessful and no datastores working on all hosts are shown, an error message is displayed and the user is redirected to the start page
- Datastores
- The dropdowns show all valid datastores for the SUT cluster
- Validation has been done in hosts section
- Deployment Datastores
- The "Client" option shows all valid datastores for the client cluster
- All other dropdowns show all valid datastores for the SUT cluster
- Validation has been done in hosts section
- Network Info:
- The data for the network label is obtained from the REST API
- An error message is displayed if no network labels are shown
- The start IP is validated to be an IP address
- Edit Config:
- After submitting the Network Info page, the user is redirected to editConfig.php
- editConfig.php copies `VMmark3.properties` from the VMmark3 folder, and creates a modified version called `VMmark3.properties.gui` inside the project folder, in order to prevent the original from being corrupted.
- The user is then automatically redirected to the control panel.

### Control Panel

The control panel shows 4 options:
- Edit Configurations:
- This will run through the properties wizard with values pre-filled with the existing properties file values.
- Deploy Tile:
- This will launch the Deployment menu.
- Run Benchmark:
- This will launch a benchmark run.
- View Results:
- This will open the results page.

### Deploy Benchmark
- When ticking the "Deploy Tile0" checkbox the "# Tiles to Deploy" field should be disabled, the following "ProvisioningSource" variable will be set to the template
- The # tiles to deploy will set 2 variables
- "ProvisioningSource = tile0"
- "ProvisioningNumTiles = " will be set to the user input of # Tiles to deploy.
- The user input for Deploy Jobname will set:
- "RunName = " will be set to the user input
- Clicking deploy wil run the command:
`java -jar /root/VMmark3/tools/VMmark3Service.jar -c VMmark3.properties.gui`
- The deployment will redirect the user to the "running" page and go back to the control panel after the deployment has finished.

### Run Benchmark
Some properties need to be acquired from the user befor running the benchmark:
- The # of tiles user input will change the "Tiles = " variable in the properties file
- The Run Name will be the input for the `VMmark3-STAX-Console.sh` script,
* `VMmark3-STAX-Console.sh <RunName>`

### View Results
The results page has four main columns of information about the results of each test it discovers:
* Test name
* Number of tiles
* Validity of test
* Link to Graphs page with more detailed information
#### Manual Directory Bar
In order to make testing and development easier, the results page has an included textbox where the directory to search for test results may be entered manually.
For example: if the test results are located in `/root/results/Results_2020...`, the user could enter `/root/results`, and as long as /root and /root/results have execute permissions for "other" users enabled, the results should be displayed correctly.

## Setup
### Location in Filesystem
The Web Interface must be located in a subfolder of `/var/www/html` in order to be served by the Apache HTTPd server.

The project currently relies on symbolic links into `/root/VMmark3/results` and `/root/VMmark3`.
These links are used by `results.php` and `editConfig.php`, respectively.

### Apache Server
In order to activate the Apache HTTPd server and begin serving the Web Interface, the following commands must be run:
* `systemctl enable httpd`
* `systemctl start httpd`

### Permissions Requirements
This project uses the file I/O capabilities of both PHP and AWK in order to interact with various files relevant to VMmark:
* Results folders and the included Score files.
* `VMmark3.properties`
* `VIJavaCaller.java`
* `/root/VMmark3/tools/VMmark3Service.jar`
* `/root/VMmark3/tools/VMmark3-STAX-console.sh`

In order for the Web Interface to interact with these files correctly, there are several permissions fixes which must currently be implemented:
* In the file `/etc/selinux/config`, the entry for SELINUX must be set to disabled. Ex: `SELINUX=disabled`
* In order for these changes to take effect, the primeclient must be rebooted.
* `getResults.awk` must have execute permissions for "other" enabled.
* The folder containing all results folders and all of its parent folders must have execute permissions for "other" enabled.
* `VIJavaCaller.java` needs write permission for "other" in the folder containing the Java file in order to compile and create the file `VIJavaCaller.class`. The command to be run in the directory itself is: `chmod o+w .`

## Tools Used
### Frontend
#### Clarity
The Clarity design framework was used to build the front end design of the pages.

### Backend
#### AWK
The page `results.php` uses a small AWK script named `getResults.awk` to pull data about every successful test from the Scores files.

#### Java
Java was used for obtaining the datastores by cluster using the VI Java API. The script `VIJavaCaller.java` obtains all the hosts of a cluster and all the datastores of the hosts and filters them, so that only datastores available for all hosts are shown.

#### JavaScript
JavaScript was used for dynamically displaying the clusters by datacenter in the dropdown menus. The file `app.js` does the display changing process, using JSON encoded input from PHP. Some javascript code is also used to disable the ""# tiles to deploy" field if the "Deploy tile0" option is selected in `deployment.php`.

#### PHP
The majority of backend code is written in PHP. This includes calls to the REST API, session storage of the variables needed for configuring the VMmark3.properties file, modifying the VMmark3.properties file with the input from the properties wizard, deployment and running of the benchmark, displaying the results, form validation and executing local files using shell_exec.

## Known Issues

### Issues with Deployment/Running (As of May 8, 2020)
When testing the deployment and running features, we have not been able to have a successful run for either of them. While some bugs were fixed by modifying the editConfig.php file, we can't say for sure if the issues are caused by the environment or by any of our code. Since the execution of deployment and running works, there are chances that the issues are environmental, but for bug fixing, we can recommend the following as of now:
* Make sure the clusters contain the correct VMs. For deploying tile0, no VMs for the options shown in the deployment datastores page (Client, AuctionMSQ etc.) as well as a vmmark template.
* Check whether the information in VMmark3.properties.gui is correct. If any of the information is incorrect, check the file editConfig.php for errors.
* If a successful deployment is redirected to the errors page, check deployment-handler.php for the deployment error route and running-handler.php for the running error route.

## Authors

### Julia Werner
[e-mail]
### William Sampson
[e-mail]
### Herendira Camarillo
[e-mail]
### Andrew Marmolejo
[e-mail]