How to Set Up the Virtual Appliance

The virtual appliance is a virtual machine containing a pre-built ThousandEyes Enterprise Agent, which can be quickly imported into virtualization software, configured and made available for use in testing. This article describes the requirements and steps required to install and use the ThousandEyes virtual appliance.

System Requirements

Working network to the virtual machine
At least 2 gigabytes of memory for the virtual machine

Overview

The installation process for a Virtual Appliance consists of two parts:

Import the virtual appliance into your virtualization software (hypervisor) Installation instructions fall into one of two groups, depending on the type of hypervisor:
- Virtualization software that supports Open Virtualization Format (OVA/OVF): Oracle VirtualBox, VMWare products, Microsoft Hyper-V for Windows Server 2012, 2016, 2019, 2022
Configure the virtual appliance

Importing the Virtual Appliance

Where to Find What You Need

Before starting with the import it is necessary to know where these resources can be accessed.

Enterprise Agents are listed in the Agent Settings.
If no agents have been installed yet, the listing shows No Enterprise Agents Found
To import a virtual appliance agent from this area, click Add New Enterprise Agent.
Follow the steps below to proceed with the import from this area of the ThousandEyes platform.

Import with the Open Virtualization Format (OVA)

Download the latest thousandeyes-va-<version>.ova file from the Cloud & Enterprise Agents > Agent Settings > Enterprise Agents > Agents page.
Click Add New Enterprise Agent on the left side of the Agent Settings screen.
There are several package types and options under this Menu. Under the Package Type, “Appliance” should be selected: Click the button in the listing labeled Download - OVA for Virtual Appliance shown above the link for this Installation Guide.
Double-click the downloaded thousandeyes-va-latest.ova file, or import it based on the virtualization software if this does not occur automatically. Click the import button and the progress of the installation will be shown.
Go through the steps in the VM application you have. Note: We recommend at least 2GB RAM memory allocated for the virtual appliance.
- Oracle VirtualBox: Instructions can be found here - VirtualBox manuals.
- VMware Fusion (10.x and later): Instructions can be found here - VMware Fusion knowledge base.
- VMware Workstation (14.x and later): Instructions can be found here - VMware Workstation knowledge base.
- VMware ESXi (6.5 and later): Instructions can be found here - VMware vSphere knowledge base
- Microsoft Hyper-V: Instructions can be found here - Enterprise Agent Deployment Using ThousandEyes Virtual Appliance (Hyper-V).
No matter which platform you choose, you will need to configure your guest (virtual machine) to use a bridged network connection, so that the guest has unimpeded network and Internet access. (see the screenshot below). NOTE: For VMware hypervisors, the VMXNET 3 adapter type is recommended. Flexible adapters are currently not supported.
Configure the virtual appliance.

Proceed to the section on configuring of the Open Virtualization Format (OVA).

Import with the Microsoft Hyper-V Format

The instructions below use Hyper-V Manager from Windows Server 2016, but the steps are similar for other supported versions of Hyper-V.
Download the latest thousandeyes-va-<version>.zip file from the Cloud & Enterprise Agents > Agent Settings > Enterprise Agents > Agents page.
Click Add New Enterprise Agent on the left side of the Agent Settings screen.
There are several package types and options under this menu. Under the Package Type, “Appliance” should be selected: Click the button in the listing labeled Download - OVA for Virtual Appliance shown above the link for this Installation Guide.
Extract the zip file to the location where you would like to keep your virtual appliance files. We recommend using the default Hyper-V virtual machines folder. Note: You cannot move the files after completing these steps.
Run Hyper-V Manager and click on "Import Virtual Machine...".
Click "Browse" to the select location of the extracted files. This folder should contain two folders: "Virtual Hard Disks" and "Virtual Machines" as well as the file "config.xml".
Select "Copy the Virtual Machine (create a new unique ID)" and leave "Duplicate all files so that the same virtual machine can be imported again" unchecked, then click Import.
After the virtual machine has been imported, click "Settings...".
Select "Network Adapter" from the left pane.
In the drop-down menu under "Network:" select the appropriate network that you would like this virtual machine to connect to. This network should be accessible to you, and have access to the Internet.

Click Ok.
You can now run the virtual machine by clicking "Connect..." then "Start".

Configure the virtual appliance.

Configuring the Virtual Appliance

In order to get a new agent to appear in the Agents Settings page listing the newly downloaded ThousandEyes Enterprise Agent, the virtual appliance will need to be configured.

After the system starts, a screen will appear that will show and IP address for the management console and default access credentials
Access the ThousandEyes virtual appliance interface through the URL in that screen and login with the credentials shown.
Press N to access manual network configuration. For specific configuration steps, see Advanced Network Settings.
Open a browser entering the URL presented on the screen. Enter the default username and password given.
Change the virtual appliance management console Web Interface Password, and click Change Password.
Following that enter the Account Group Token in the field that will show up under the Agent section. This should appear automatically after changing the password.
Retrieve the Account Group token from Cloud & Enterprise Agents > Agent Settings > Enterprise Agents > Agents > Add New Enterprise Agents view. It can be found under the link labeled "Show Account Group Token for Installation". This will reveal the token so it may be copied for use.
Paste the Account Group Token into the Account Token field. The field should turn green.
Yes is selected for Browserbot by default since this component is required for Page Load and Transaction test types.
Click Continue.
Following that The Review Section will appear and Diagnostics will begin to run. Some errors will show up initially as red then turn to green. Wait a few minutes.
When the agent checks in with the Account Group Token it should appear in the listing. For convenience if there are a number of agents listed the new Enterprise Agent will be listed.
Initially the status of the agent will show up in red as offline. Check back in to the management console Web Interface and wait for Appliance Status and Diagnostics to show up in Green. When this happens click the Complete button. See Supplemental Screenshots below for a visual detail of this and the following steps.
The Network section of the Web Interface will be shown. Select the Status section once more and click Run Diagnostics.
Flipping back to the Agent Settings page, the Agent Status in the Listing should show Status/Last Contact in yellow.
At this point, agent versions will show up in the detail. The agent will be automatically updating its version with the ThousandEyes Platform. In order to do this it needs to be able to communicate with the platform. See the Related Articles section below for more. While this is happening, check that your agent status periodically again: Cloud & Enterprise Agents > Agent Settings > Enterprise Agents > Agents > Add New Enterprise Agents. Wait for the agent to check and upgrade to the latest version. This can be confirmed after the Status/Last Contact field shows up in green and the time following last contact in minutes shows. Opening up the detail for the agent listing will show the Versions of the agent and Browserbot components (no longer in red) upgraded to the latest version.

Supplemental Screenshots

The following screenshots appear while completing configuration. During this process the agent is communicating with the platform and updating. Expect to see these views during that process:

Agent Initialization
Run diagnostics
Check status
Check for green online status

Advanced Network Settings

During the configuration process above, you can select N in step two to configure the network manually:

For both IPv4 and IPv6 configurations, users can set the configuration to auto (via DHCP), static, or disable the protocol entirely.

IPv4 only can be disabled when the IPv6 address is configured. If disabled, Enterprise Agents will then use the IPv6 address for agent communication. In dual-stack environments, the IPv4 address will be used for agent communication by default.