Installing a Physical Appliance

Last updated: Wed Apr 24 12:07:38 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

The Physical Appliance hardware must conform to the specifications used for validation by ThousandEyes. While the installation usually works with other configurations (consisting of any memory module(s) supported by a particular Intel NUC and any compatible SATA-based SSD disk with either SATA or M.2 connection, but not NVMe), we test and support only the components listed in the tables below.

NUC 8th generation

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

NUC 6th & 7th generations

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

NUC 5th generation

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


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, and identify the physical disk you’re interested in imaging. It should be /dev/diskN. In the example below, I have a 1GB USB disk in the 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
  1. Run diskutil unmountDisk /dev/diskN (replace N with the actual disk number from output above):

    dave@schadenfreude ~/Downloads> diskutil unmountDisk /dev/disk2
    Unmount of all volumes on disk2 was successful
  2. 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.


Imaging the device

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.  

    NOTE: In order to complete the installation correctly, the device needs to be connected to a network with non-proxied access to the Internet, on a segment where a DHCP service is available. If these requirements are not satisfied, the installation will come to an end, but it will not be completed correctly. The following behavior anomalies are known indicators of an unsuccessful appliance installation:
    • The agent doesn't detect the keyboard connected.
    • The agent boots into the "thousandeyes-va login:" prompt screen, instead of a blue management console shown below.
  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.


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.

Do you need assistance?

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