Installing a Physical Appliance

Last updated: Thu Sep 12 13:48:12 GMT 2019

For customers who require a turnkey hardware and software solution, the ThousandEyes Enterprise Agent can be installed on prescribed off-the-shelf hardware. A downloadable ISO image is used to install a supported version of Ubuntu LTS, the ThousandEyes Enterprise Agent, and management software onto approved Intel NUC hardware, which provides a convenient form-factor that is easily shipped to branch offices, partner sites and other environments where provisioning will only require connection to power and a wired network.

This article details the hardware requirements of the Physical Appliance and the steps required to download and install the ISO image to the hardware, and subsequent configuration.

Table of contents

Hardware requirements

Intel NUC 8th generation

SubsystemManufacturerComponentPart Number
 IntelNUC i7
NUC i5
NUC i3
MemoryAny memory configuration supported by given NUC.*

According to hardware requirements, at least 2GB of memory must be installed.
Links to Intel- and manufacturer-validated compatible components:
DiskAny single SSD or NVMe disk supported by given NUC.*

According to hardware requirements, at least 20GB of disk space must be provided.

*The Physical Appliance installation has been created to work with any Intel NUC-supported peripherals. However, ThousandEyes validates Physical Appliance deployments using the following hardware only:

The support for hardware variety compatible with this generation of Intel NUC devices is provided on a best-effort basis. If your chosen hardware configuration does not work as expected, the support will be limited to officially validated hardware only.

Intel NUC 6th & 7th generations - OBSOLETE

NOTICE: Intel NUC systems of 6th and 7th generations are obsolete and not recommended for new deployments.

ManufacturerComponentPart Number
Intel NUC i3
NUC i5
NUC i7
Crucial4GB DDR4 2400 MT/S (PC4-19200) SODIMMCT4G4SFS824A
Transcend64GB SATA III 6 Gb/s M.2 SSDMTS800

Intel NUC 5th generation - OBSOLETE

NOTICE: Intel NUC systems of 5th generation are obsolete and not recommended for new deployments.

ManufacturerComponentPart Number
Intel NUC i3
NUC i5
NUC i7
Crucial4GB DDR3 PC3-12800 SODIMMCT51264BF160B
Transcend64GB SATA III 6 Gb/s M.2 SSDMTS800


Installation environment requirements

In order to complete the installation correctly, the following is mandatory:

  • Wired network connection: The device needs to be connected to the network.
  • DHCP service: A network with a working DHCP service is required for the device to obtain IP settings during the installation.
  • DNS service: DHCP service's response must contain information about DNS servers that can be used during the installation.
  • Non-proxied and unrestricted* access to the Internet: The installation process downloads various required software packages from online sources. *Unrestricted: consult the Enterprise Agent firewall requirements for a list of locations from which packages are downloaded.

If these requirements are not satisfied, the installation will result in one of the anomalies outlined in the Troubleshooting section below.

Downloading the installer

Download the appliance installer in one of two ways: a generic installer (which does not come preconfigured), or a custom installer (which allows preconfiguration of certain advanced options for the agent).

Generic installer

Browse to Cloud & Enterprise Agents > Agent Settings > Enterprise Agents and click the Add New Enterprise Agent button. Select the Appliance package type, and click the Download - ISO button in the Physical Appliance Installer row:


Account-specific installer

Browse to Cloud & Enterprise Agents > Agent Settings > Enterprise Agents and click the Add New Enterprise Agent button. Select the Custom Appliance package type, and provide the appliance details. The appliance name is a name for the image, and you can add proxy information, specify whether or not the configuration web server is enabled, and enter preseeded SSH keys. In a custom appliance model, your account group token is built into the image:


Once the fields are complete, click the Generate button. The appliance installer will take between 15 and 30 minutes to generate. You'll get an email with a download link once the image has been generated.

Download the appliance installer image once you have the link.

Writing the ISO to a USB disk

The download process will provide an .ISO which can be written to a USB disk as a bootable image. The following process describes writing the image to a USB disk on Mac OS X and Windows.

Mac OS X / Linux instructions

  1. Insert a USB disk with a size of at least 1GB into a USB port on your computer. The disk’s content will be overwritten, so be sure to save any content you need.
  2. Open a terminal window
  3. Type diskutil list (OS X) or fdisk -l (Linux) and identify the physical disk you’re interested in imaging. It should be /dev/diskN (OS X) or /dev/sdN (Linux). In the example below, I have a 1GB USB disk in my Mac's USB port:

    dave@schadenfreude ~/Downloads> diskutil list
    /dev/disk0 (internal, physical):
       #:                       TYPE NAME                    SIZE       IDENTIFIER
       0:      GUID_partition_scheme                        *500.3 GB   disk0
       1:                        EFI EFI                     209.7 MB   disk0s1
       2:          Apple_CoreStorage Macintosh HD            499.4 GB   disk0s2
       3:                 Apple_Boot Recovery HD             650.0 MB   disk0s3
    /dev/disk1 (internal, virtual):
       #:                       TYPE NAME                    SIZE       IDENTIFIER
       0:                  Apple_HFS Macintosh HD           +499.1 GB   disk1
                                     Logical Volume on disk0s2
    /dev/disk2 (external, physical):
       #:                       TYPE NAME                    SIZE       IDENTIFIER
       0:     FDisk_partition_scheme                        *1.0 GB     disk2
       1:             Windows_FAT_32 UBUNTU-SERV             1.0 GB     disk2s1
  4. Run diskutil unmountDisk /dev/diskN (OS X) or umount /dev/sdN (Linux) to unmount the device (replace N with the actual disk number from the output above):

    dave@schadenfreude ~/Downloads> diskutil unmountDisk /dev/disk2
    Unmount of all volumes on disk2 was successful
  5. Next, write the image to disk. Run sudo dd if=<path_to_downloaded_iso> of=/dev/diskN, wait until it completes:

    dave@schadenfreude ~/Downloads> sudo dd if=thousandeyes-pa-1.9.100.iso of=/dev/disk2
    1175552+0 records in
    1175552+0 records out
    601882624 bytes transferred in 267.718384 secs (2248193 bytes/sec)

Windows Instructions

While many Windows-compatible applications for writing bootable ISO images to USB are available, we've chosen one for documentation purposes.

  1. Download & install Rufus from here:
  2. Launch Rufus
  3. Insert a USB disk with a size of at least 1GB into a USB port on your computer. The disk’s content will be overwritten, so be sure to save any content you need:
    User-added image
  4. Select the destination device using the Device dropdown. If you only have one USB disk inserted, it will be autoselected.
  5. Browse to and select the ISO downloaded earlier in these instructions.
  6. Select DD Image option in the dropdown next to the Create a bootable disk using checkbox.
  7. Click the Start button
  8. If prompted (in case you have forgotten to select DD Image mode earlier), choose to write in DD Image mode:
    User-added image
  9. Confirm that your destination disk will be overwritten to start the writing process:
    User-added image
  10. When complete, eject the disk.

BIOS configuration

The following list is by no means a comprehensive set of BIOS configuration instructions - an IT professional should be consulted to validate the configuration of what will essentially be an always-on device.

The main BIOS configuration directives to be adjusted are these:

  • In the Boot > Boot Priority section, the UEFI Boot support should be disabled.
  • In the Power > Secondary Power Settings section, the After Power Failure option should be set to either Last State or Power On.

Imaging the device

WARNING: Before starting the installation, make sure the installation environment requirements are satisfied.

Now that you've got a bootable ISO image, time to image the box.

  1. Take the freshly written USB disk and put it into an approved hardware device.
  2. Power up the machine.  
  3. If the device’s hard disk is bootable (if it has already been used for something), you’ll need to connect a monitor and keyboard, to force the machine to boot from USB.  

    Press F10 to enter into the boot menu, and select the USB stick attached.  
  4. Allow the USB disk to boot into Install Ubuntu Server ThousandEyes Edition, this will happen automatically without user intervention:

    If the machine doesn't boot into an installation process, and instead shows a media not bootable error, then re-create the install media using the steps above.
  5. On the Finishing the installation screen, Running preseed... is the last step of the process. There will not be a warning that the device is shutting down, or an indication that the imaging process is complete.
  6. The device will shut down once the image has been successfully applied. 

Configuring the agent

The last step is configuring the agent. Depending on whether you've downloaded the generic installer or a custom installer, you'll need to configure the Agent. Power on the device after the installation has been completed, and manage the network settings using the console that comes up:


  1. Access the ThousandEyes Virtual Appliance Setup interface through the URL in that screen with the credentials shown.
  2. On the Access tab, you'll be prompted for a new password. This is required to continue with the installation.
  3. On the Agent tab, you'll be prompted for the Account Group Token. The Account Group Token can be found on the Account Groups tab of the Account Settings page for a specific account group, or in the Add New Enterprise Agent dialog on the Cloud & Enterprise Agents > Agent Settings > Enterprise Agents page:

  4. Paste the Account Group Token into the Account Group Token field. The field will turn blue:

    Select Yes if BrowserBot is to be used on the agent.
  5. Click through the remaining menus. Confirm that in the Diagnostics step, that all checks complete successfully.
  6. The Enterprise Agent should now appear in the Cloud & Enterprise Agents > Agent Settings > Enterprise Agents page of the ThousandEyes portal.


USB boot option unavailable during installation

After a properly-written USB disk has been inserted into a NUC device and the F10 key was pressed to enter the boot menu, the USB boot option is not presented on the screen.

Resolution: Disable UEFI boot support, as instructed in the BIOS configuration section.

The installation produces the "No Root File System Defined" error message

This situation can occur if USB devices (keyboard and USB installation media) are attached to the NUC via a USB expander. If there are other block devices (external disks, card readers) attached to the expander, the installer detects them and is unable to determine automatically which device to use as an installation target. Such devices may not even be standalone devices visibly connected the USB expander - they can be built into other USB devices such as printers, scanners, etc.

Resolution: Do not use USB expanders to connect keyboard and USB installation media to the target NUC.

Installed agent displays the "thousandeyes-va login:" prompt on the screen

When connecting a display to the physical appliance, the expected blue management console is not displayed (as shown in the Configuring the agent section above). Instead, a black screen with thousandeyes-va login: prompt is shown.

This is a symptom of an unsuccessful installation. The agent is missing the te-pa package which, in addition to the web admin interface, provides the physical console functionality. The most likely reason for unsuccessful installation is the lack of non-proxied and unrestricted access to the internet during the appliance installation process.

Resolution: Reinstall the appliance in an environment that satisfies the requirements listed in the Installation environment requirements section above.

Keyboard not working

When a keyboard is connected to an installed agent, keypresses may not be detected. This is another symptom of an unsuccessful installation and usually occurs when encountered when access to the Internet is unavailable during the installation phase.

Resolution: Reinstall the appliance in an environment that satisfies the requirements listed in the Installation environment requirements section above.

Do you need further assistance?

If you have any questions, reach out to the ThousandEyes Customer Success team and we'll help you out.