Deployment Steps

Create the Host Network

The sample applications must listen on a network interface. A host-only network that is hidden behind Network Address Translation (NAT) rules is created. The application will run on the host-only network and will connect to Ginger Cybersecurity's network to monitor the virtual machine.

The shell script ginger/setup.sh must be modified to use the correct network interface for the NAT rules. Find your system's configuration by running ip addr, and find the device that starts with enX0. Modify the eth_internet="enX0" line so that it matches your system's configuration. For example, if your device was ens5, change the code to look like:

eth_internet="ens5"

Execute the shell script setup.sh with the commands below.

cd ginger
sudo sh -e setup.sh

Edit the Network Settings

These examples use a static networking configuration. The networking configuration requires a DNS resolver. The DNS resolver for the host will be used. Edit the init.yaml file so the DNS component of the networking points to a valid DNS resolver. If this is not set the virtual machine will run but Ginger Cybersecurity will be unable to monitor the health of the virtual machine.

networking:
  source: config
  ipv4:
    ip: 192.168.42.100
    netmask: 255.255.255.0
    broadcast: 192.168.42.255
    gateway: 192.168.42.1
    dns:
    - 192.168.42.1

For example, if you're on AWS and your DNS resolver is 10.0.0.2, you can change the configuration to look like this:

networking:
  source: config
  ipv4:
    ip: 192.168.42.100
    netmask: 255.255.255.0
    broadcast: 192.168.42.255
    gateway: 192.168.42.1
    dns:
    - 10.0.0.2

Build the Virtual Machine

The next step is to build the virtual machine disk images. Use the gingervm command line interface to do so. The commands to issue are shown below and run from the ginger directory inside the project.

# First, set these variables:
ID_REGEX='([0-9a-zA-Z]{24})'
ginger_image_name=..type new image name here..
ginger_image_version_name=0.0.1
ginger_server_name=..type new server name here..

# List all organizations. Get your organization's ID and set ginger_org to it.
gingervm organization list
ginger_org=..paste ID here..

# Create a new image.
IMAGE_CREATE_OUTPUT=$(gingervm image create --org "${ginger_org}" --name "${ginger_image_name}") && echo $IMAGE_CREATE_OUTPUT

# Save off the new image ID
ginger_image=$(echo $IMAGE_CREATE_OUTPUT | grep -oEi $ID_REGEX)

# Create a new version of the image.
IMAGE_VERSION_CREATE_OUTPUT=$(sudo -E gingervm image version create --org "${ginger_org}" --image "${ginger_image}" --config image.yaml --name "${ginger_image_version_name}" --vars vars.json) && echo $IMAGE_VERSION_CREATE_OUTPUT

# Save off the new image version ID
ginger_image_version=$(echo $IMAGE_VERSION_CREATE_OUTPUT | grep -oEi $ID_REGEX)

# Create a new server.
SERVER_CREATE_OUTPUT=$(gingervm server create --org "${ginger_org}" --name "$ginger_server_name") && echo $SERVER_CREATE_OUTPUT

# Save off the new server ID
ginger_server=$(echo $SERVER_CREATE_OUTPUT | grep -oEi $ID_REGEX)

# Create a new server deployment. The deployment must link back to the image version.
sudo -E gingervm server deployment create --org "${ginger_org}" --server "${ginger_server}" --config deployment.yaml --version "${ginger_image_version}"

# Create a new data disk. This only needs to be done once.
sudo -E gingervm data-disk create --config data.yaml

Launch the Virtual Machine

The final step is to launch the virtual machine containing the application. The application will start automatically when the virtual machine is started. Run the shell script launch.sh to launch the virtual machine. The terminal will display lots of normal Linux kernel output and then pause after the first measurement.

sudo chown ubuntu:ubuntu ../target/disk_*
mkdir -p ./logs
sh launch.sh 2>&1 | tee "./logs/$(date +"%FT%T").txt"

This opens a QEMU terminal where you will see the output from the virtual machine and your application running. When you are done viewing this output and want to stop the virtual machine, run Ctrl + A, then x.

Bonus: Editing a Virtual Machine

If you find you need to adjust the configuration for the virtual machine, here are some easy steps to pick up where you left off.

# First, set these generally useful variables:
ID_REGEX='([0-9a-zA-Z]{24})'

# Make sure `ginger_org` is set.
gingervm organization list
ginger_org=..paste ID here..

# Find the ID of the image you want and save off to `ginger_image`
gingervm image list --org "${ginger_org}"
ginger_image=..paste ID here..

# Figure out a new image ID that makes sense by listing the image IDs:
gingervm image version list --org "${ginger_org}" --image "${ginger_image}"
ginger_image_version_name=..type new ID name here..

# Now create a new version of the image:
IMAGE_VERSION_CREATE_OUTPUT=$(sudo -E gingervm image version create --org "${ginger_org}" --image "${ginger_image}" --config image.yaml --name "${ginger_image_version_name}")
echo $IMAGE_VERSION_CREATE_OUTPUT
ginger_image_version=$(echo $IMAGE_VERSION_CREATE_OUTPUT | grep -oEi $ID_REGEX)

# Check if there's a server you want to use with this command, save ID to a variable
gingervm server list --org "${ginger_org}"
ginger_server=..paste ID here..

# Create a new server deployment and data disk
sudo -E gingervm server deployment create --org "${ginger_org}" --server "${ginger_server}" --config deployment.yaml --version "${ginger_image_version}"
sudo -E gingervm data-disk create --config data.yaml

Now you may follow the same steps as in the section above for launching your new virtual machine!