Getting Started

This page is a how-to guide on getting started using the VSEC platform to install and run Breakwater on the VCI.

Hardware

See page “Hardware Requirements” to see what hardware is supported by Breakwater

VSEC Garage

To get started, navigate to https://vsec.blockharbor.io/, where all the “Blocks” implemented in VSEC live. If you are greeted by a login page, authenticate with your Gmail account. Once authenticated, navigate to the block labeled “Garage”, pictured below:

Generating ISO Image

Once inside the “VSEC Garage”, click the button in the top right corner that reads “CREATE BENCH”:

After clicking on create bench we are greeted with the following prompt:

This is where we will configure the iso, the main details we should be concerned with are the wifi credentials and the hostname of the device. The WiFi credentials are important so that the device can check in with the VSEC backend and finish provisioning. The hostname is imporant because that will be the main identifier for the VCI in the VSEC Garage. After configuring the iso we are ready to download the image; click “Download ISO.”

Flashing VCI

After the .iso image has finished downloading we are ready to flash an SD card and install the SD card into the VCI. The recommended way to do this is by using the offical Raspberry Pi Imager (https://www.raspberrypi.com/software/) directly from raspberrypi. Once installed, run the raspberry pi imager.

Click on “Choose OS”

Choose “Use Custom” and select the .iso image downloaded from VSEC Garage

If the Rapsberry Pi imager asks if you want to add “Custom OS Settings”, choose “NO” and move onto the next step.

After we have chosen the custom iso, we want to select the appropriate storage device. After inserting the SD card into your workstation, click “Choose Storage” and select the SD card. Once selected, we are ready to write to the SD card.
Click “WRITE”

Connecting VCI to VSEC

Once the SD card has been flashed and the raspberry pi imager states that it is safe to remove, remove the SD card and insert it into the raspberry Pi. To connect the VCI to VSEC, simply plug the VCI into a power source and wait 1 to 2 minutes. After the waiting period is over, refresh the page and your new VCI will show up in the list of “Test Benches”

Creating Test Specifications

To create a test specification to execute on our target through our newly created VCI, navigate to the VSEC block labeled “Test”. There will be two page options, “TEST RUNS” and “TEST SPECS”. To create a “Test Run” we will need to specify what interfaces and tests we want ran against the target. Navigate to “TEST SPECS”

Once inside “Test Specs” click the large red button labeled “ADD NEW TEST SPECS”

Here we can name the test run and optionally give the test run a description. After our test specification has been created, we will see it populate in the left hand side of the screen. We can click on our newly created “Test Specification” and begin adding test cases by clicking on the large red button in the middle of the page labeled “ADD NEW TEST CASES”

Inside we will see:

Here we will configure the interfaces and select the test cases we want to execute:

Once finished selecting the tests we want to execute, click save.

Running Tests

To run a test against a target through our newly created VCI, navigate to the VSEC block labeled “Test”

To create a test, click on the large red button in the top right corner labeled “Create Test Run”

We will be greeted with the following prompt:

Inside of this prompt, we will select the bench we just created from the dropdown menu labeled “Select Bench”, we will also select the “Test Plan” to run against the target. We can optionally set the description for the test. After these details have been filled out, to run the test, click “RUN TEST.”

Accessing Breakwater CLI

To access the devices CLI interface, navigate to https://vsec.blockharbor.io/

In Garage select the bench you would like to connect to. Once inside, select “Open Terminal”:

After selecting “Open Terminal” a new window will be spawned, inside of this window is a terminal environment where you can execute commands on the VCI directly. To run Breakwater via the CLI, start with the following command:

$ breakwater