Cisco Catalyst 8500 and 8500L Series Edge Platforms Software Configuration Guide

PDF

Cisco ThousandEyes Enterprise Agent Application

Updated: February 6, 2026

Overview

Explains how to host and manage network intelligence agents as containerized applications on routing platforms. It provides a complete workflow for installation, configuration, and troubleshooting to gain deep visibility into digital experiences and network paths.

Cisco ThousandEyes Enterprise agent application

Cisco ThousandEyes is a network intelligence platform that

  • allows you to use its agents to run a variety of tests to monitor network and application performance,

  • enables you to view end-to-end paths across networks and services that impact your business,

  • actively monitors network traffic paths across internal, external, and internet networks in real time to analyze network performance, and

  • provides application-availability insights enriched with routing and device data for a multidimensional view of digital experience.

From Cisco IOS XE Release 17.6.1, you can use application-hosting capabilities to deploy the Cisco ThousandEyes Enterprise Agent as a container application on Cisco Catalyst 8300 and Catalyst 8200 Series Edge Platforms. This agent application runs as a docker image using Cisco IOx docker-type option. For more information on how to configure Cisco ThousandEyes in controller mode, see Cisco SD-WAN Systems and Interfaces Configuration Guide

Figure 1. Network View through ThousandEyes Application

Supported platforms and system requirements

Supported platforms and system requirements are listed.

Table 1. Supported Platforms and System Requirements
Platforms Bootflash FRU Storage DRAM
Catalyst 8300 Series Edge Platforms

C8300-1N1S-6T

8 GB

16 GB M.2 USB (Default)

8 GB

C8300-1N1S-4T2X

8 GB

16 GB M.2 USB (Default)

8 GB

C8300-2N2S-6T

8 GB

16 GB M.2 USB (Default)

8 GB

C8300-2N2S-4T2X

8 GB

16 GB M.2 USB (Default)

8 GB

Catalyst 8200 Series Edge Platforms

C8200-1N-4T

8 GB

16 GB M.2 USB (Default)

8 GB

C8200L-1N-4T

8 GB

16 GB M.2 USB (Recommended)

8 GB
Note

The minimum DRAM and storage requirement for running Cisco ThousandEyes Enterprise Agent is 8 GB. If the device does not have enough memory or storage, we recommend that you upgrade DRAM or add an external storage such as M.2 USB. When the available resources are not sufficient to run other applications, Cisco IOx generates an error message.

Workflow to install and run the Cisco ThousandEyes application

To install and run the Cisco ThousandEyes image on a device, perform these steps:

Procedure

1.

Create a new account on the Cisco ThousandEyes portal.

2.

Download the Cisco ThousandEyes application package from the software downloads page and ensure that you use the agent version 4.0.2.

3.

Copy the image on the device.
4.

Install and launch the image.
5.

Connect the agent to the controller.

Note

When you order platforms that support Cisco ThousandEyes application with Cisco IOS XE 17.6.1 software, the Cisco ThousandEyes application package is available in the bootflash of the device.

The Cisco ThousandEyes Enterprise Agent application is successfully installed and running on your device.

Workflow to host the Cisco ThousandEyes application

Use this workflow to install, configure, and launch the Cisco ThousandEyes Enterprise Agent application on your device.

To install and launch the application, perform these steps:

Before you begin

Create a new account on the Cisco ThousandEyes portal and generate the token. The Cisco ThousandEyes agent application uses this token to authenticate and check into the correct Cisco ThousandEyes account. If you receive a message stating that your token is invalid and you want to troubleshoot the issue, see Troubleshooting the Cisco ThousandEyes Application.

Note

If you configure the correct token and Domain Name Server (DNS) information, the device is discovered automatically.

Procedure

1.

Enable the Cisco IOx application environment on the device.

  • Use these commands for non-SD-WAN (autonomous mode) images:

    config terminal
 iox
end
write

  • Use these commands for SD-WAN (controller mode) images:


config-transaction
iox
commit
2.

If the IOx command is accepted, wait for a few seconds and check whether the IOx process is up and running by using the show iox command. The output must display that the show IOxman process is running.

Device #show iox

IOx Infrastructure Summary:
---------------------------
IOx service (CAF) 192.0.2.8     : Running
IOx service (HA)               : Not Supported 
IOx service (IOxman)           : Running 
IOx service (Sec storage)      : Not Supported 
Libvirtd 1.3.4                 : Running
3.

Ensure that the ThousandEyes application LXC tarball is available in the device's bootflash:.

4.

Create a virtual port group interface to enable the traffic path to the Cisco ThousandEyes application:

interface VirtualPortGroup 0
          ip address 192.0.2.22 255.255.255.0
        exit
5.

Configure the app-hosting application with the generated token:

app-hosting appid te
          app-vnic gateway1 virtualportgroup 0 guest-interface 0
          guest-ipaddress 192.0.2.22 netmask 255.255.255.0
          app-default-gateway 192.0.2.22 guest-interface 0
          app-resource docker
             prepend-pkg-opts  Required to get the default run-time options from package.yaml
             run-opts 1 "--hostname thousandeyes"
             run-opts 2 "-e TEAGENT_ACCOUNT_TOKEN=<ThousandEyes token>"
 	     run-opts 3 "-e TEAGENT_PROXY_TYPE=STATIC -e TEAGENT_PROXY_LOCATION=proxy.something.other:80"
          name-server0 192.0.2.10  ISP’s DNS server
        end

app-hosting appid te
 app-resource docker
  prepend-pkg-opts
  run-opts 2 “--hostname
Note
You can use the proxy configuration only if the Cisco ThousandEyes agent does not have an internet access without a proxy. Also, the hostname is optional. If you do not provide the hostname during the installation, the device hostname is used as the Cisco ThousandEyes agent hostname. The device hostname is displayed on the Cisco ThousandEyes portal. The DNS name server information is optional. If the Cisco ThousandEyes agent uses a private IP address, ensure that you establish a connection to the device through NAT.
6.

Configure the start command to run the application automatically when the application is installed on the device using the install command:

app-hosting appid te
         start
7.

Install the ThousandEyes application:


app-hosting install appid <appid> package [bootflash: | harddisk: | https:]

Select a location to install the ThousandEyes application from these options:

Device# app-hosting install appid te package ?
           bootflash:  Package path  ISR4K case if image is locally available in bootflash:
           harddisk:   Package path  Cat8K case if image is locally available in M.2 USB
           https:      Package path  Download over the internet if image is not locally present in router. URL to ThousandEyes site hosting agent image to be provided here
8.

Check if the application is up and running:


Device#show app-hosting list
 App id                                   State
---------------------------------------------------------
  te                                       RUNNING
Note
If any of these steps fail, use the show logging command and check the IOx error message. If the error message is about insufficient disk space, clean the storage media (bootflash or hard disk) to free up the space. Use the show app-hosting resource command to check the CPU and disk memory.

The Cisco ThousandEyes application is successfully hosted and running on your device.

Download and copy the image to the device

Use this task to ensure the Cisco ThousandEyes application image is correctly placed on your device for installation.

To download and copy the image to bootflash, perform these steps:

Procedure

1.

Check if the Cisco ThousandEyes image is precopied to bootflash:/<directory name>.
2.

If the image is not available in the device directory, perform these steps:

  1. If the device has a direct access to internet, use the https:. option in the application install command. This option downloads the image from the Cisco ThousandEyes software downloads page into bootflash:/apps and installs the application. 

    Device# app-hosting install appid <appid string> package [bootflash: | flash | http | https://  | ftp | ] URL to image location hosted on ThousandEyes portal

Device# app-hosting install appid te1000 package https://downloads.thousandeyes.com/enterprise-agent/thousandeyes-enterprise-agent-4.0.2.cisco.tar

Installing package 'https://downloads.thousandeyes.com/enterprise-agent/thousandeyes-enterprise-agent-4.0.2.cisco.tar' for 'te1000'. 

Use 'show app-hosting list' for progress.
*Jun 29 23:43:29.244: %IOSXE-6-PLATFORM: R0/0: IOx:  App verification successful
*Jun 29 23:45:00.449: %IM-6-INSTALL_MSG: R0/0: ioxman: app-hosting: Install succeeded: te1000 installed successfully Current state is DEPLOYED
*Jun 29 23:45:01.801: %IOSXE-6-PLATFORM: R0/0: IOx:  App verification successful
*Jun 29 23:45:51.054: %IM-6-START_MSG: R0/0: ioxman: app-hosting: Start succeeded: te1000 started successfully Current state is RUNNING
  
Device#show app-hosting detail appid te1000  ( Details of Application)
App id                 : te1000
Owner                  : iox
State                  : RUNNING
Application
  Type                 : docker
  Name                 : ThousandEyes Enterprise Agent
  Version              : 4.0
  Author               : ThousandEyes <support@thousandeyes.com>
  Path                 : bootflash:thousandeyes-enterprise-agent-4.0-22.cisco.tar
Resource reservation
  Memory               : 500 MB
  Disk                 : 1 MB
  CPU                  : 1500 units
  CPU-percent          : 70 %

  2. If the device has a proxy server, copy the image manually to bootflash:/apps.

  3. Download the Cisco ThousandEyes application package from the software downloads page and ensure that you use the agent version 4.0.2.

  4. Create an application directory in the bootflash: to copy the image: 

    Device# mkdir bootflash:apps 
Create directory filename [apps]? 
Created dir bootflash:/apps

  5. Copy the Cisco ThousandEyes image to the bootflash:apps directory.

  6. Validate the image using the verify command:

    verify /md5 bootflash:apps/<file name>

The Cisco ThousandEyes image is successfully downloaded and copied to the device's bootflash.

Connect the Cisco ThousandEyes Agent with the controller

This task explains the process of the Cisco ThousandEyes agent connecting to its controller in the cloud environment.

To connect the Cisco ThousandEyes agent with the controller, perform these steps:

Before you begin

Ensure that you have an Internet connection before you connect the agent with the controller.

Procedure

After the Cisco ThousandEyes application is up and running, the agent (ThousandEyes-agent ) process connects to the controller that is running on the cloud environment.

Note

If you have issues related to connectivity, the application logs the relevant error messages in the application-specific logs (/var/logs).

The Cisco ThousandEyes agent is successfully connected to the controller.

Modify the agent parameters

Use this task to update the configuration settings of an application agent, which requires stopping and restarting the application.

To modify the agent parameters, perform these actions:

Procedure

1.

Stop the application using the app-hosting stop appid appid command.
2.

Deactivate the application using the app-hosting deactivate appid appid command.
3.

Make the required changes to the app-hosting configuration.
4.

Activate the application using the app-hosting activate appid appid command.
5.

Start the application using the app-hosting start appid appid command.

The agent parameters have been successfully modified and the application is running with the new configuration.

Uninstall the application

Use this task to completely remove a previously installed application from your device.

To uninstall the application, perform these steps:

Procedure

1.

Stop the application using the app-hosting stop appid te command.
2.

Check if the application is in active state using the show app-hosting list command.
3.

Deactivate the application using the app-hosting deactivate appid te command.
4.

Ensure that the application is not in active state. Use the show app-hosting list command to check status of the application.
5.

Uninstall the application using the app-hosting uninstall appid te command.
6.

After the uninstallation process is complete, use the show app-hosting list command to check if the application is uninstalled successfully.

The application has been successfully uninstalled from the device.

Troubleshoot the Cisco ThousandEyes application

To troubleshoot the Cisco ThousandEyes application, perform these steps.

  • Connect to Cisco ThousandEyes agent application using the app-hosting connect appid appid session /bin/bash command.

  • Verify the configuration applied to the application /etc/te-agent.cfg.

  • View the logs in /var/log/agent/te-agent.log. You can use these logs to troubleshoot the configuration.

When the Cisco ThousandEyes application is in running state, it is registered on the ThousandEyes portal. If the application does not show up in a few minutes after the agent is in running state, check using the app-hosting connect appid thousandeyes_enterprise_agent session command.

Note

Check the DNS server connection. If the Cisco ThousandEyes agent is assigned to a private IP address, check the NAT configuration.

Device#app-hosting connect appid thousandeyes_enterprise_agent session
Device#cat /var/log/agent/te-agent.log
2021-02-04 08:59:29.642 DEBUG [e4736a40] [te.agent.AptPackageInterface] {} Initialized APT package interface
2021-02-04 08:59:29.642 INFO  [e4736a40] [te.agent.main] {} Agent version 1.103.0 starting.  Max core size is 0 and max open files is 1024
2021-02-04 08:59:29.642 DEBUG [e4736a40] [te.agent.db] {} Vacuuming database
2021-02-04 08:59:29.643 INFO  [e4736a40] [te.agent.db] {} Found version 0, expected version 50
2021-02-04 08:59:29.672 INFO  [e4708700] [te.probe.ServerTaskExecutor] {} ProbeTaskExecutor started with 2 threads.
2021-02-04 08:59:29.673 INFO  [e2f05700] [te.probe.ProbeTaskExecutor.bandwidth] {} ProbeTaskExecutor started with 1 threads.
2021-02-04 08:59:29.673 INFO  [e2704700] [te.probe.ProbeTaskExecutor.realtime] {} ProbeTaskExecutor started with 1 threads.
2021-02-04 08:59:29.673 INFO  [e1f03700] [te.probe.ProbeTaskExecutor.throughput] {} ProbeTaskExecutor started with 1 threads.
2021-02-04 08:59:29.674 DEBUG [e4736a40] [te.agent.DnssecTaskProceessor] {} Agent is not running bind
2021-02-04 08:59:29.674 DEBUG [e4736a40] [te.snmp.RequestDispatcher] {} Initialised SNMP++ session
2021-02-04 08:59:29.674 DEBUG [e4736a40] [te.snmp.RequestDispatcher] {} Initialised SNMP++ session
2021-02-04 08:59:29.674 DEBUG [e4736a40] [te.snmp.RequestDispatcher] {} Initialised SNMP++ session
2021-02-04 08:59:29.674 INFO  [e4736a40] [te.agent.main] {} Agent starting up
2021-02-04 08:59:29.675 INFO  [e4736a40] [te.agent.main] {} No agent id found, attempting to obtain one
2021-02-04 08:59:29.675 INFO  [e4736a40] [te.agent.ClusterMasterAdapter] {} Attempting to get agent id from sc1.thousandeyes.com
2021-02-04 08:59:29.679 ERROR [e4736a40] [te.agent.main] {} Error calling create_agent: Curl error - Couldn't resolve host name
2021-02-04 08:59:29.680 INFO  [e4736a40] [te.agent.main] {} Sleeping for 30 seconds