Installing Enterprise Agents on Cisco Routers with vManage

This article covers the steps to install a ThousandEyes Enterprise Agent on Cisco routers running in SD-WAN mode that are managed by vManage. For more information about vManage, see the vManage Documentation.

vEdge routers must be added to the vManage inventory list before continuing. For more information, see the vManage Documentation.


To review the supported Cisco routers and hardware requirements, see the Support Matrix.

Installation Steps

Log into the Portal

  1. Log into the vManage portal.

  2. Navigate to Maintenance > Software Repository.

Optional: Add the Virtual Image

If this is a first time installation, add the virtual image first. Otherwise, move on to the next section:

  1. Navigate to Virtual Images.

  2. Select Upload Virtual Image > vManage.

  3. Upload the ThousandEyes installation image .tar file as an Image Package:

Note: Once the image is uploaded, the filename should be present in the Virtual Image list.

Verify the Virtual Image

To confirm the virtual image is ready, click Show Info to review and verify the virtual image's vnfProperties:

Create the Feature Template

To create a template for a specific device type:

  1. Navigate to Configuration > Templates.

  2. Select Feature > Create Template > Add Template.

  3. Under Select Device, search for the device model (for example, ISR4431) that you wish to deploy an agent to. See the Support Matrix for compatible routers.

  4. Select ThousandEyes Agent template from under Other Templates.

  5. Specify the template name and description.

  6. Under Basic Configuration, enter the relevant Account Group Token.

  7. Optional: SD-WAN mode offers the option to send agent traffic to pre-configured VPN tunnels, instead of following the default management route. Specify the service VPN template (either Default, Global, or Device Specific) to deploy the ThousandEyes agent within. This will allow you to configure tests that collect telemetry on the SD-WAN overlay and the applicable underlay path. For more information on the available VPN template configurations, see the vManage Documentation.

    Note: Ensure that the agent has network reachability from within the service VPN to the ThousandEyes cloud dashboard over the Internet.

  8. Under Advanced, configure the Name Server, Hostname, and Web Proxy.

    Note: This proxy configuration doesn't support any authentication methods. If you need to configure a proxy that requires basic or PAC authentication, you will need to use the CLI deployment option.

  9. Click Save to save the template.

Attach the Feature Template to the Device Template.

  1. Navigate to Configuration > Template > Device, then search for the device type (i.e. ISR4221x).

  2. Click the three dots icon and select Edit.

  3. Navigate to the Additional Template.

  4. Open the ThousandEyes Agent drop-down menu, and select the template created in steps 2-9.

  5. Click Update to save the changes.

Attach the Device Template to a Device

To attach the template:

  1. Click the three dots icon and select Attach Devices.

  2. Select the desired device/s from the Available Devices list, then click Attach.

    Note: The list will only contain vEdge devices that are the same model as the template.

Verify Configuration

Once the template is attached to the desired devices, you can verify it from the Running Configuration view:

  1. Navigate to Configuration > Devices.

  2. Click the three dots icon beside the desired device, and select Running Configuration.

Agent Management

Agents can be un-deployed by removing the ThousandEyes Agent feature template from the device template. However, vManage cannot disable the running Agents once they are deployed. You will need to use either the web app or the CLI for agent management. See Reconfiguring the Docker Container for CLI instructions.

Frequently Asked Questions

What is the expected NTP behavior for a Catalyst 8000 series deployed Enterprise agent?

The enterprise agent on a Catalyst 8000 series switch uses the host system kernel clock. It also sends packets to to determine any clock offset. It does not try to adjust the host or container clock but will adjust measurement timestamps based on the clock offset.

Can the default external NTP source ( be changed to a customer's internal NTP source?

No. The agent uses to determine clock offset by default; this is currently not configurable.

How do I connect to the agent shell for Cisco agents?

To access the agent shell of a Cisco Enterprise Agent that is actively running, use the following command:

catalyst#app-hosting connect appid {application name} session

Once inside the agent shell, you can refer to the agent log for any further troubleshooting:

# tail /var/log/agent/te-agent.log

If connection or DNS resolution errors are found in the log file, your agent cannot connect to the ThousandEyes platform. Check your app-vnic configuration and make sure the agent IP can reach the internet.

For more information on configuration options, see Docker Agent Config Options.

Can I use ThousandEyes troubleshooting utilities?

From Agent 4.0.2 onwards, te-agent-utils are pre-installed on Cisco Enterprise Agents. For more information on the available utilities, see CLI Network Troubleshooting Utilities.

Last updated