Site Coordinator Virtual Appliance

Introduction

This document provides the step-by-step procedure to download, set up, install, and activate a Site Coordinator Virtual Appliance.

Download and Setup

Network Prerequisites

The Site Coordinator (SC) Virtual Appliance can work in a limited network connectivity environment. Only the following outbound connections are required:

• From the virtual appliance to the respective SAFE instance over secure port 443

Download Virtual Appliance

To download the latest release of the Virtual Appliance (in an OVA format):

1. Login to SAFE.
2. Navigate to Administration > AssetManagement > Agent& SiteManagement.
3. Click the Install Site Coordinator button.
4. On the Install Site Coordinator pop-up, click the download link. The system starts the download (approx file size 8GB).

Import the Virtual Appliance into a VM hosting setup

Follow the below steps to import the Virtual Appliance into a VM hosting setup:

1. On your Hypervisor, Create a New Virtual Machine and select the option to Import/Deploy a VM from an OVA template.
   
2. Upload or select the downloaded virtual appliance and type in an appropriate name for the Virtual Machine.
   
3. Select the storage disk and network adapters as per the environment.
4. Ensure not to "Power On" the Virtual Appliance right away. If the machine was powered on, shut it down to modify the settings.
5. Once the import is successful and a new Virtual Machine is created. Right-click the Virtual Machine and go to Edit Settings.
6. Modify the VM Settings as per the Site Coordinator Hardware Pre-Requisites.
7. Save and now Power On the Virtual Machine.
   
8. Once the machine boots up and the login screen shows up, log in with the default account having the following details. These are credentials to log into the virtual appliance console. These will be needed only for the initial setup of the Site Coordinator or for troubleshooting purposes.
   1. Username: safe
   2. Password: safe
9. You will be prompted to modify the password. It is mandatory to change the default username/password. Refer to the below password policies to set a new password.
   Note: On changing the password, it might prompt with a message, “Password has already been used; choose another”. This has been identified as a known issue in the underlying Operating System being used but is completely safe to ignore since the password does get changed.
10. Ensure the new credentials are saved in a secure manner to prevent any account lockouts.

Install and Activate the Site Coordinator

The Virtual Appliance comes pre-loaded with all the necessary software requirements, including the Site Coordinator packages. Follow the steps below to establish a connection and activate the Site Coordinator with the SAFE Instance."

1. Login to SAFE in a new tab and navigate to Administration > Asset Management > Agent & Site Management.
2. Click the Install Site Coordinator button. The system displays the installation command on the install site coordinator pop-up.
3. Copy the Installation command.
   
4. Sign in to the Virtual Appliance.
5. Execute the command copied in step 3 on the Virtual Appliance console. Make sure to use the default "safe" user for login and not any other user. If prompted to enter a password for elevated privileges, provide the password assigned to this user.
6. The installation of the Site Coordinator will swiftly finalize and establish a connection with the SAFE Instance. This process typically takes only a few seconds.

OS Updates

The Virtual Appliance is designed to perform routine patching activities autonomously and install required operating system patches at predetermined intervals. There is no requirement for additional configuration or network access, as this entire process is managed by SAFE.

OS Hardening

The Virtual Appliance is pre-hardened as per industry standards, i.e. CIS Benchmark Level 1 for Ubuntu OS.

Proxy Setup on Virtual Appliance Machine

To setup the proxy on the virtual appliance machine, follow the below steps:

• Edit /env/environment configurations

sudo nano /etc/environment

• Add these lines in the file below the path parameter; IP/PORT values here can be replaced with your Proxy IP/PORT.

export http_proxy="http://proxy_ip:port/"
export https_proxy="http://proxy_ip:port/"

#For Curl command
export HTTP_PROXY="http://proxy_ip:port/"
export HTTPS_PROXY="http://proxy_ip:port/"

• To set up a proxy in case of authentication needs to pass a username and password like this in the proxy URL, e.g. UserName: test and Password: Test@123.

export http_proxy="http://test:Test%40123@proxy_ip:port/"
export https_proxy="http://test:Test%40123@proxy_ip:port/"
#here '%40' is the URL-encoded value for the @ character,

• If you want to ignore some internal URLs or IPs for which the proxy shouldn’t get applied, add those URLs or IPs like this just below your http_proxy configurations in /etc/environment file.

export no_proxy="127.0.0.1,localhost"

• Apply these changes by

sudo netplan apply

• Verify Proxy setup is complete by running the below command

env | grep PROXY

• You should receive output like the below screenshot.
  
• If you don’t get any output, try logging out and logging in again to the Virtual Machine.
• Now install Site Coordinator with the --configure:proxy option and follow the steps mentioned here to configure the proxy for Site Coordinator.

Appendix

Validate Download  (Optional)

Once the Site Coordinator is downloaded, you can validate the download using the GPG signature using the below steps:

1. Download the Public GPG from this link (Fingerprint: E3C290E02D806C475F5FE4AED824C1F1CE8A3EB0)
2. Download the signature file of the Virtual Appliance from the link on the Install Site Coordinator pop-up (available next to the download link.
   
3. Verify the fingerprint by running gpg --show-keys <public_key_here>. Verify the output with the above signature (the screenshot shows an example, the actual value must be used for comparison)
   
4. In case the fingerprint doesn’t match, reach out to support
5. Once the fingerprint matches, import this public key into the system store using gpg --import <public_key_file_here>
   
6. You can use gpg --list-keys to confirm the import. The list of the keys should show the newly imported key.
7. Now verify the signature of the Virtual Appliance using the command: gpg --verify <signature_file>.sig <virtual_appliance_file>.ova. The output should contain the text “Good Signature” signifying the authenticity of the Virtual Appliance file.
   

Change Docker Subnet

1. Inspect endpoints connected to docker_gwbridge:
   docker network inspect docker_gwbridge
2. Disconnect the connected endpoints:
   docker network disconnect -f docker_gwbridge <endpointName>
   Where <endpointName> is “Container” → “Name”. There are usually 4 endpoints that are listed as per the docker network inspect command for docker_gwbridge; hence all these need to be removed individually.
3. Remove docker_gwbridge network:
   docker network rm docker_gwbridge
4. Recreate docker_gwbridge with the non-conflicting subnet. You can replace ’x' below for the non-conflicting subnet:
   docker network create --subnet=172.x.0.1/16 -o com.docker.network.bridge.enable_icc=false -o com.docker.network.bridge.name=docker_gwbridge docker_gwbridge
5. Restart the docker service:
   systemctl restart docker
6. Confirm that the subnet has changed for docker_gwbridge:
   ip addr
7. Confirm that the 4 previously disconnected endpoints are back:
   docker network inspect docker_gwbridge

This helps to change the IP without reinstalling the SC. The assessments have been confirmed to happen successfully after this change.

Using Older VA SC Images with New SAFE Versions

If the versions of Virtual Appliance and SAFE Service are not the same, the Virtual Appliance will download the latest versions of the Site Coordinator (SC) images from the SAFE version. This will cause an ~2GB SC download to happen as the up-to-date SC images are downloaded and deployed. Following this, the SC will be upgraded to the release matching the SAFE Service.

If the Virtual Appliance requires a patch update, patch management will automatically run and apply any new updates.